Developer Guide

Introduction

Welcome to Prompt Stack

Prompt-Stack Developer Guide

Learn how to build with Prompt-Stack. This interactive guide walks you through every feature with practical examples.

Built with AI-first development in mind
Testing features coming soon!
Checking authentication...

What's New in Prompt-Stack Web

Prompt-Stack Web is a complete rewrite focused on developer experience and reliability:

Enhanced CLI & Setup

  • One-command setup with ./setup.sh
  • Smart state tracking in .setup-state.json
  • Progressive enhancement: add features as needed
  • Automated deployment with prompt-stack deploy

Admin System & Auth

  • First user automatically becomes admin
  • Role-based access control built-in
  • Protected routes with (authenticated) folder
  • Demo mode fallback when no config

Developer Experience

  • New ./scripts/diagnose.sh for debugging
  • CLAUDE.md AI assistant operating manual
  • Automatic Docker restart handling
  • Dramatically improved setup experience

Enhanced Features

  • Master env file: .env.master
  • Environment sync with ./setup.sh sync
  • Deployment URL tracking
  • Better CORS handling for production

Key Improvements vs Original Prompt-Stack

❌ Old (prompt-stack-site)

  • • Manual setup with multiple steps
  • • Environment variables often failed
  • • No state tracking between sessions
  • • Complex deployment process
  • • Limited AI provider support
  • • No admin system

✅ New (prompt-stack-web)

  • • One-command setup: ./setup.sh
  • • Smart state tracking & auto-recovery
  • • Progressive enhancement approach
  • • Automated deployment: prompt-stack deploy
  • • 4 AI providers including DeepSeek
  • • First user = automatic admin

Result: Significantly fewer setup issues and better error recovery

Getting Started

Start building with zero configuration:

1. Quick Start Commands

One-command setup (NEW!)
./setup.sh
Check setup status
./setup.sh status
Quick diagnosis
./scripts/diagnose.sh

No configuration needed - works immediately in demo mode!

Compare to old version: required copying .env files, installing dependencies, and manual Docker commands.

2. Progressive Enhancement (NEW!)

1

Add authentication

./setup.sh supabase
2

Add AI providers

./setup.sh ai
3

Deploy to production

prompt-stack deploy

Important: After adding API keys, log out and back in to refresh auth tokens!

New Admin System!

The first user to sign up automatically becomes admin.

Admin features will be available in a future update. For now, focus on building your product!

Architecture Overview

Understanding the folder structure and where to build your features.

Frontend Structure

frontend/app/

🎯 Your application pages - Build your features here!

frontend/app/(authenticated)/

🔒 Protected pages that require login

frontend/app/prompt-stack/

📚 Demo pages and this guide (don't build here!)

frontend/components/

🧩 Reusable React components

frontend/lib/

🛠️ Utilities and helper functions

Backend Structure

backend/app/api/endpoints/

🚀 API route handlers

backend/app/services/

💼 Business logic (LLM, auth, payments)

backend/app/models/

📋 Data models and schemas

backend/app/core/

⚙️ Configuration and utilities

backend/.env

🔑 Environment variables and API keys

Key Principle: Build in the Right Place

✅ DO Build Here:

  • app/dashboard/page.tsx
  • app/(authenticated)/profile/page.tsx
  • app/api/custom-endpoint/route.ts

❌ DON'T Build Here:

  • app/prompt-stack/* (demos only)
  • app/auth/* (already built)
  • • Root config files (unless necessary)

Core Features Walkthrough

Explore each feature with interactive examples and code snippets.

Ready

Authentication System

Supabase auth with demo mode fallback. Includes login, register, and protected routes.

Email/password authentication
Protected route middleware
Demo mode for testing
Built-in and ready
Ready

AI Integration

Multiple LLM providers with streaming support and demo fallback.

POST /api/llm/generate
• OpenAI (GPT-4o)
• Anthropic (Claude)
• Google (Gemini)
• DeepSeek (Ultra low cost)
• Demo mode included
Ready to integrate
Ready

Vector Search

PostgreSQL with pgvector for semantic search. In-memory demo mode.

POST /api/vectors/embedPOST /api/vectors/search

Perfect for RAG applications and semantic search features.

API docs at /docs when running
Ready

Payment Processing

Stripe & Lemon Squeezy integration with demo checkout flows.

Subscription management
Webhook handling
Demo checkout flow
Ready to integrate
Ready

Form Components

Reusable form components with validation and error handling.

Input validation
Error states
Loading states
Pre-built and ready
Live

API Documentation

Auto-generated FastAPI docs with interactive testing.

http://localhost:8000/docs

Test endpoints directly from the browser with Swagger UI.

Available at localhost:8000/docs

Code Examples

Copy these examples to quickly implement common features.

Creating a Protected Page

Add this to app/(authenticated)/your-page/page.tsx

TypeScript
export default function YourProtectedPage() {
  const { user } = useAuth()
  
  return (
    <div>
      <h1>Welcome, {user?.email}!</h1>
      {/* Your protected content */}
    </div>
  )
}

Making AI API Calls

Example using the LLM generation endpoint:

JavaScript
const response = await fetch('/api/llm/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Your prompt here',
    model: 'gpt-4o-mini', // or 'demo'
    stream: false
  })
})

const data = await response.json()
console.log(data.content)

New CLI Commands (prompt-stack-web exclusive)

Enhanced command-line tools for better developer experience:

Smart Setup Commands

./setup.sh

One-command setup with state tracking

./setup.sh status

Check configuration status

./setup.sh sync

Sync env across services

New Diagnostic Tools

./scripts/diagnose.sh

Auto-diagnose common issues

./scripts/diagnose.sh --quick

Quick health check

prompt-stack deploy

Automated deployment (NEW!)

CLI Improvements Summary

The new CLI is designed to eliminate common setup frustrations:

  • State Persistence: Remembers your configuration between sessions
  • Auto-Recovery: Detects and fixes common issues automatically
  • Smart Recommendations: Suggests next steps based on current state
  • Docker Management: Handles container restarts automatically

Common Patterns

Best practices and patterns used throughout Prompt-Stack.

Error Handling

Consistent error handling across frontend and backend:

// Frontend error handling
try {
  const res = await fetch('/api/endpoint')
  const data = await res.json()
  
  if (!data.success) {
    setError(data.message || 'Something went wrong')
    return
  }
  
  // Process data
} catch (error) {
  setError('Network error')
} finally {
  setLoading(false)
}

• Always check data.success

• Display user-friendly error messages

• Include loading states

Loading States

Provide feedback during async operations:

// Loading state pattern
const [loading, setLoading] = useState(false)
const [data, setData] = useState(null)

async function fetchData() {
  setLoading(true)
  try {
    const result = await api.getData()
    setData(result)
  } finally {
    setLoading(false)
  }
}

// In your component
{loading ? (
  <div className="animate-pulse">Loading...</div>
) : (
  <div>{data}</div>
)}

Form Validation

Client-side validation before API calls:

// Form validation pattern
function validateForm() {
  const errors = {}
  
  if (!email.includes('@')) {
    errors.email = 'Valid email required'
  }
  
  if (password.length < 6) {
    errors.password = 'Min 6 characters'
  }
  
  setErrors(errors)
  return Object.keys(errors).length === 0
}

// On submit
if (!validateForm()) return

API Response Format

Standardized API responses:

// Success response
{
  "success": true,
  "data": { /* your data */ },
  "message": "Success"
}

// Error response
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

• Always include success boolean

• Consistent structure across all endpoints

• Clear error messages for debugging

Next Steps

Ready to build? Here's how to customize Prompt-Stack for your project:

1. Set Up Your Database

Configure Supabase for production authentication and data storage.

  • • Create Supabase project
  • • Add environment variables
  • • Enable authentication

2. Add AI Capabilities

Connect your preferred AI providers for advanced features.

  • • Add API keys to .env
  • • Choose your models
  • • Implement AI features

3. Deploy to Production

Ship your app with confidence using our deployment guides.

  • • Deploy frontend to Vercel
  • • Deploy backend to Railway
  • • Configure production env

Troubleshooting Guide

Common issues and how to fix them.

🐳 Docker Issues

Containers won't start:

docker-compose -f docker-compose.dev.yml down
docker-compose -f docker-compose.dev.yml up -d

Port already in use:

# Find what's using port 3000
lsof -i :3000
# Kill the process
kill -9 [PID]

🔑 Environment Variables

Changes not taking effect:

⚠️ Docker requires full restart for env changes!

docker-compose -f docker-compose.dev.yml down
docker-compose -f docker-compose.dev.yml up -d

API key format issues:

Correct format in .env:

OPENAI_API_KEY=sk-...
OpenAI=sk-...

🔐 Authentication Problems

"Supabase not configured" when testing LLMs:

You need Supabase for authentication before testing LLMs!

Setup order: Supabase → LLMs → Other services

Can't sign in:

  • • Check Supabase URL and keys are correct
  • • Verify email confirmation if using real Supabase
  • • Try demo mode first to isolate issues

🚀 API Connection Issues

Frontend can't reach backend:

  • • Ensure backend is running: docker ps
  • • Check logs: docker logs prompt-stack-backend-1
  • • Verify API URL: http://localhost:8000

CORS errors:

Check CORS_ORIGINS in backend/.env includes your frontend URL

🔧 Quick Debug Commands

Check Status:

docker psmake logscurl http://localhost:8000/

Reset Everything:

make cleanmake dev./scripts/test-api-simple.sh

Migrating from prompt-stack-site

Upgrading from the original Prompt-Stack? Here's what you need to know:

Key Differences

File Structure Changes

  • setup.sh now handles everything (no manual copying)
  • .setup-state.json tracks your configuration
  • .env.master for centralized env management

New Features

  • Admin system (first user = admin)
  • DeepSeek AI provider ($0.14/M tokens!)
  • Automated deployment command

Quick Migration Steps:

  1. Clone prompt-stack-web (don't try to update in place)
  2. Run ./setup.sh - it handles everything
  3. Copy your API keys from old .env files when prompted
  4. Your existing Supabase project works as-is
  5. Test with ./scripts/diagnose.sh

No database migrations needed - fully compatible with existing data!

Need Help?

Prompt-Stack is designed to be AI-friendly. Use your favorite AI assistant to help you build faster.