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.
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
./setup.sh
./setup.sh status
./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!)
Add authentication
./setup.sh supabase
Add AI providers
./setup.sh ai
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.
Authentication System
Supabase auth with demo mode fallback. Includes login, register, and protected routes.
AI Integration
Multiple LLM providers with streaming support and demo fallback.
POST /api/llm/generate
Vector Search
PostgreSQL with pgvector for semantic search. In-memory demo mode.
POST /api/vectors/embed
POST /api/vectors/search
Perfect for RAG applications and semantic search features.
API docs at /docs when runningPayment Processing
Stripe & Lemon Squeezy integration with demo checkout flows.
Form Components
Reusable form components with validation and error handling.
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/docsCode Examples
Copy these examples to quickly implement common features.
Creating a Protected Page
Add this to app/(authenticated)/your-page/page.tsx
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:
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 ps
make logs
curl http://localhost:8000/
Reset Everything:
make clean
make 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:
- Clone prompt-stack-web (don't try to update in place)
- Run
./setup.sh
- it handles everything - Copy your API keys from old .env files when prompted
- Your existing Supabase project works as-is
- 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.