Developer Guide

Project Structure

Understanding the codebase organization

Project Structure

Understanding how Prompt Stack is organized will help you navigate the codebase and build features efficiently.

Directory Overview

prompt-stack/
├── frontend/              # Next.js application
├── backend/               # FastAPI application
├── supabase/             # Database migrations
├── scripts/              # Utility scripts
├── docs/                 # Documentation
├── docker-compose.dev.yml
├── docker-compose.prod.yml
├── Makefile              # Development commands
├── setup.sh              # Interactive setup wizard
└── CLAUDE.md             # AI assistant guide

Frontend Structure

frontend/
├── app/                   # Next.js App Router
│   ├── (authenticated)/   # 🔒 Protected routes
│   │   ├── dashboard/    
│   │   ├── profile/      
│   │   └── settings/     
│   ├── auth/             # Authentication pages
│   ├── api/              # API route handlers
│   └── page.tsx          # 🏠 Homepage
├── components/           
│   ├── ui/               # Reusable UI components
│   ├── forms/            # Form components
│   ├── layout/           # Layout components
│   └── providers/        # Context providers
├── lib/                  # Utilities and hooks
├── services/             # API client functions
└── public/               # Static assets

💡 Key Insight: The (authenticated) folder automatically protects all routes inside it. No need to add auth checks to individual pages!

Backend Structure

backend/
├── app/
│   ├── api/
│   │   ├── endpoints/    # API route handlers
│   │   │   ├── auth.py
│   │   │   ├── llm.py
│   │   │   ├── payments.py
│   │   │   └── vectors.py
│   │   └── router.py     # Route registration
│   ├── services/         # Business logic
│   │   ├── llm/         # AI provider services
│   │   ├── auth/        # Authentication logic
│   │   └── payments/    # Payment processing
│   ├── models/          # Pydantic models
│   ├── core/            # Core utilities
│   │   ├── config.py    # Settings management
│   │   ├── auth.py      # JWT handling
│   │   └── features.py  # Feature flags
│   └── main.py          # FastAPI app
├── tests/               # Test files
└── requirements.txt     # Python dependencies

Key Files to Know

Configuration Files

`.env.master`

Master environment template - all variables in one place

# Core settings
ENVIRONMENT=development
DEMO_MODE=auto

# Service API keys
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
# ... etc

`backend/.env`

Backend-specific environment variables

CORS_ORIGINS=["http://localhost:3000"]
FRONTEND_URL=http://localhost:3000
DATABASE_URL=postgresql://...

`frontend/.env.local`

Frontend-specific environment variables

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

Where to Build Features

✅ Build Here

  • app/ - Your pages
  • app/(authenticated)/ - Protected pages
  • components/ - Custom components
  • backend/app/api/endpoints/ - API routes
  • backend/app/services/ - Business logic

❌ Don't Touch

  • app/prompt-stack/ - Demo pages
  • app/auth/ - Auth system
  • core/ - Core utilities
  • docker-compose.yml - Unless needed
  • supabase/migrations/ - Use CLI

File Naming Conventions

page.tsxNext.js page component
layout.tsxLayout wrapper for pages
loading.tsxLoading state component
error.tsxError boundary component
ComponentName.tsxReact components (PascalCase)
use-hook-name.tsCustom hooks (kebab-case)

Important Patterns

Frontend Patterns

Server vs Client Components

// Server Component (default)
export default async function Page() {
  const data = await fetchData() // ✅ Can fetch on server
  return <div>{data}</div>
}

// Client Component
'use client'
export default function Page() {
  const [state, setState] = useState() // ✅ Can use hooks
  return <div>{state}</div>
}

Protected Page Pattern

// app/(authenticated)/my-feature/page.tsx
export default function MyFeaturePage() {
  const { user } = useAuth() // ✅ User guaranteed
  return <div>Welcome {user.email}</div>
}

Backend Patterns

API Endpoint Pattern

# backend/app/api/endpoints/my_feature.py
from fastapi import APIRouter, Depends
from app.core.auth import get_current_user
from app.core.response_utils import create_response

router = APIRouter()

@router.get("/my-endpoint")
async def my_endpoint(user = Depends(get_current_user)):
    # Your logic here
    return create_response(
        success=True,
        data={"message": "Hello World"}
    )

Database Structure

supabase/
├── migrations/
│   ├── 001_initial_schema.sql
│   ├── 002_add_user_roles.sql
│   └── 003_update_profile_creation.sql
└── config.toml

📝 Note: Database migrations run automatically. To add new tables or modify schema, create a new migration file with the next number in sequence.

Script Utilities

`setup.sh`

Interactive setup wizard - handles all configuration

`scripts/diagnose.sh`

Diagnose common issues - run this first when debugging

`scripts/test-api-simple.sh`

Quick API health check

Best Practices

📁

Keep related files together

Components with their styles, tests, and types in the same folder

🏷️

Use TypeScript everywhere

Type safety prevents bugs and improves developer experience

🎨

Follow existing patterns

Look at similar files before creating new ones

🔍

Use the search tools

VS Code search or grep to find examples

Back to overview →