Architecture Overview

This page explains the high-level system architecture, data flow, and key design decisions.

System Layers

graph TB
    A[Frontend - SvelteKit] --> B[Backend API - Hono.js]
    B --> C[AI Orchestration]
    B --> D[Database - PostgreSQL]
    C --> E[Planner Agent]
    C --> F[Image Planner Agent]
    C --> G[Executor Agent]
    C --> H[MCP Server - Web Design Strategy]
    D --> I[Drizzle ORM]

Layer Details

1. Frontend (SvelteKit)

Location: src/routes/, src/lib/components/

Responsibilities:

• UI rendering (shadcn-svelte components)
• Visual editor (Lexical)
• Real-time updates (Supabase Realtime)
• State management (Svelte stores)

Key Files:

• src/routes/+layout.svelte - Root layout
• src/routes/projects/[id]/+page.svelte - Project editor
• src/lib/components/editor/LexicalEditor.svelte - Visual editor

---

2. Backend API (Hono.js)

Location: src/lib/server/api/

Responsibilities:

• REST endpoints
• WebSocket connections
• Authentication/Authorization
• Database queries
• AI pipeline orchestration

Key Endpoints:

POST   /api/projects          - Create new project
GET    /api/projects/:id      - Fetch project
PUT    /api/projects/:id      - Update project
POST   /api/generate          - Trigger AI generation
WS     /api/realtime          - WebSocket updates

See: API Reference

---

3. AI Orchestration

Location: src/lib/server/ai/

Multi-Agent Pipeline:

1. Planner Agent (planner.ts)

   • Reads user brief
   • Generates design brief (style, colors, typography, sections)
   • Output: DesignBrief object

2. Image Planner Agent (image-planner.ts)

   • Reads design brief
   • Generates image specifications with prompts
   • Output: ImageSpec[] array

3. Executor Agent (executor.ts)

   • Reads design brief + image specs
   • Generates production code (SvelteKit components)
   • Output: Complete code with all files

MCP Integration: All agents load skill files from MCP Server:

• skill:///agents/planner.md
• skill:///agents/executor.md
• skill:///references/styles.md

See: AI Pipeline

---

4. Database (PostgreSQL + Drizzle)

Location: src/lib/server/db/

Schema:

• agencies - Client agencies
• projects - Individual projects
• versions - Code versions per project
• assets - Images, files
• ai_logs - AI agent call logs
• users - User accounts

See: Database Schema

---

Data Flow

Project Creation Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant DB
    participant AI

    User->>Frontend: Fill form & click "Generate"
    Frontend->>API: POST /api/projects
    API->>DB: Insert project (status: planning)
    API-->>Frontend: Return project ID
    Frontend->>User: Show "Planning..." status
    
    API->>AI: Call Planner Agent
    AI->>AI: Generate design brief
    AI-->>API: Return DesignBrief
    API->>DB: Update project.brief
    
    API->>AI: Call Image Planner (parallel)
    AI-->>API: Return ImageSpec[]
    
    API->>AI: Call Executor Agent
    AI->>AI: Generate code
    AI-->>API: Return code
    
    API->>DB: Insert version
    API->>DB: Update project (status: complete)
    API->>Frontend: WebSocket push update
    Frontend->>User: Show generated code

Key Points

1. Async Processing: AI pipeline runs async, UI updates via WebSocket
2. Parallel Execution: Image planner runs parallel to executor for speed
3. Error Handling: Every step logs to ai_logs, failures set status: error
4. Cost Tracking: Token usage and cost tracked per agent call

---

Component Communication

Frontend Components

ProjectEditor.svelte (main container)
├─ AIChat.svelte
│   └─ sends prompts to /api/generate
├─ LexicalEditor.svelte
│   ├─ receives code updates via WebSocket
│   └─ emits changes to parent
└─ PropertiesPanel.svelte
    └─ updates element properties via stores

Backend Services

api/
├─ projects.ts (CRUD endpoints)
├─ generate.ts (AI generation endpoint)
└─ realtime.ts (WebSocket handler)

ai/
├─ planner.ts (design brief generation)
├─ executor.ts (code generation)
└─ image-planner.ts (asset planning)

db/
├─ schema.ts (table definitions)
└─ queries.ts (common queries)

---

External Dependencies

Service	Purpose	Docs
Supabase	PostgreSQL + Auth + Realtime	Link
Anthropic	Claude API (AI agents)	Link
Cloudflare	Hosting (Pages + Workers)	Link
Cloudflare R2	File storage (images, exports)	Link

---

Key Design Decisions

See Architecture Decision Records:

• ADR 001 - Why SvelteKit over Next.js
• ADR 002 - Why Drizzle over Prisma
• ADR 003 - Why Lexical for editing

---

Performance Considerations

Frontend

• Code Splitting: Route-based lazy loading
• Image Optimization: Cloudflare Images (auto WebP)
• Bundle Size: Svelte compiles to vanilla JS (~40% smaller than React)

Backend

• Database Pooling: Supabase connection pooling
• Caching: Cloudflare KV for frequently accessed data
• Edge Functions: Cloudflare Workers (low latency globally)

AI

• Parallel Execution: Image planner + Executor run concurrently
• Streaming: Use Claude streaming for faster perceived response
• Token Optimization: Skill files cached via prompt caching

---

Monitoring & Logging

Application Logs: Cloudflare Workers Dashboard
Database Logs: Supabase Logs & Metrics
AI Logs: Custom ai_logs table (all agent calls tracked)
Error Tracking: TODO - Sentry integration planned

Cost Dashboard Query:

SELECT 
  DATE(created_at) as date,
  agent,
  SUM(tokens) as total_tokens,
  SUM(cost) as total_cost
FROM ai_logs
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY DATE(created_at), agent
ORDER BY date DESC;

---

Security

Authentication

• Provider: Supabase Auth
• Methods: Email/Password, OAuth (Google, GitHub)
• JWT: Stored in httpOnly cookie

Authorization

• Row Level Security: Enabled on all tables
• Role-Based: owner / admin / member / client
• Multi-Tenancy: Users scoped to agency via agency_id

See: Auth Flow

---

Next Steps

• Database Schema - Detailed table structures
• AI Pipeline - How agents work together
• API Reference - Complete API documentation