Setup Guide

Get the development environment running locally.

Prerequisites

• Bun 1.0+ (not npm or Node.js)
• PostgreSQL (via Supabase) or local install
• Git
• VS Code (recommended)

Installation

1. Clone Repository

git clone https://github.com/your-org/your-repo.git
cd your-repo

2. Install Dependencies

bun install

3. Environment Variables

Create .env file:

cp .env.example .env

Edit .env:

# Database (Supabase)
DATABASE_URL=postgresql://postgres:[password]@db.[project].supabase.co:5432/postgres

# Supabase
PUBLIC_SUPABASE_URL=https://[project].supabase.co
PUBLIC_SUPABASE_ANON_KEY=eyJ...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Cloudflare R2 (for file storage)
R2_ACCOUNT_ID=your-account-id
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
R2_BUCKET_NAME=your-bucket-name

# Optional
AI_TIMEOUT_MS=30000
MAX_RETRIES=3

4. Database Setup

Option A: Supabase Cloud

1. Create project at supabase.com
2. Copy connection string to .env
3. Run migrations:

bun drizzle-kit push

Option B: Local PostgreSQL

# Start PostgreSQL
docker run -d \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15

# Update .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mydb

# Run migrations
bun drizzle-kit push

5. Seed Database (Optional)

bun run seed

Creates:

• Test agency
• Test user (test@example.com / password123)
• Sample projects

6. Start Development Server

bun run dev

Opens:

• Frontend: http://localhost:5173
• API: http://localhost:5173/api

7. Start Documentation (VitePress)

cd docs
bun install
bun run docs:dev

Opens: http://localhost:5174

---

Verify Setup

Test Database Connection

bun run db:test

Should output:

✅ Database connected
✅ Tables exist: agencies, projects, versions, assets, ai_logs, users

Test API

curl http://localhost:5173/api/health

Should return:

{"status":"ok","timestamp":"2025-05-04T..."}

Test AI Integration

bun run test:ai

Calls Claude API with a test prompt. Should return success.

---

Development Workflow

File Structure

src/
├── routes/              # SvelteKit pages & API
│   ├── +layout.svelte
│   ├── +page.svelte
│   ├── projects/
│   └── api/
├── lib/
│   ├── components/      # UI components
│   ├── server/          # Server-only code
│   │   ├── db/
│   │   ├── ai/
│   │   └── api/
│   └── stores/          # Client state
└── app.html

Hot Reload

Changes are instantly reflected (no rebuild):

• Svelte components
• API routes (via +server.ts)
• Styles

Database schema changes require migration:

bun drizzle-kit generate
bun drizzle-kit push

---

VS Code Extensions

Recommended:

• Svelte for VS Code (svelte.svelte-vscode)
• Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
• Prettier (esbenp.prettier-vscode)
• ESLint (dbaeumer.vscode-eslint)

Install all:

code --install-extension svelte.svelte-vscode
code --install-extension bradlc.vscode-tailwindcss
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint

---

Troubleshooting

Port Already in Use

# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

Database Connection Failed

1. Check DATABASE_URL in .env
2. Verify PostgreSQL is running
3. Check firewall/network

# Test connection
psql $DATABASE_URL

Bun Command Not Found

# Install Bun
curl -fsSL https://bun.sh/install | bash

AI API Errors

1. Verify ANTHROPIC_API_KEY in .env
2. Check API key at console.anthropic.com
3. Check rate limits

---

Next Steps

• Architecture Overview
• Database Schema
• API Reference
• Adding Features