# sparrow-js/an-codeai architecture

> Architecture diagram of the GitHub repository sparrow-js/an-codeai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sparrow-js/an-codeai
- Repository: https://github.com/sparrow-js/an-codeai

## Overview

##### Project Type and Purpose
- Full-stack web application built with Next.js 13 (app router) and TypeScript.
- Purpose: AI-powered code generation sandbox in the browser. Users can chat with an AI assistant, generate full-stack code, preview it in an isolated WebContainer, manage Git, and deploy.

##### File Structure
- **app/**: Next.js pages and serverless API routes.
– Client & server React components under `(auth)`, `login`, `chat`, `workbench`, etc.
– **app/api/**: Route handlers for authentication, chat, LLM calls, Git proxy, deploy to Netlify/Fly, file operations, usage stats, health checks.
- **components/** & **ui/**: Reusable UI and client widgets (Chat UI, Editor, Settings tabs, Sidebar, Workbench).
- **lib/.server/** & **lib/modules/llm/**: Server-only logic for LLM orchestration and provider implementations.
- **lib/persistence** & **db/**: Database definition (Drizzle schema + migrations), and persistence layer for chat history, settings.
- **lib/webcontainer/**: Isolated sandbox runtime (WebContainer) for in-browser code execution.
- **middleware.ts**, **auth.ts**, **next.config.ts**: Global config, auth integration (NextAuth, Supabase), and routing middleware.
- **.github/workflows/**: CI/CD (clone, deploy to Netlify, revert).

##### Extract Additional Insights from README
- AI-powered full-stack web development in the browser.
- Isolated sandbox environment per project.
- Deploy to ZIP, local folder sync, self-hosting with Next.js.

##### Main Components
A. **Browser (Client)**
– React/Next.js app (Server Components + Client Components)
– Chat UI, Code Editor (CodeMirror), Settings UI, Workbench panels
– WebContainer iframe or worker for sandbox preview
B. **Next.js Server**
– Server-side rendering and API routes under `app/api/*`
– Authentication (NextAuth + Supabase)
– Middleware for session, routing
C. **LLM Layer**
– **lib/.server/llm/** orchestration, streaming, context selection
– **lib/modules/llm/providers/** plugin-style integrations (OpenAI, Anthropic, Cohere, …)
D. **Persistence Layer**
– Drizzle-driven relational DB (Edge-DB or Supabase)
– Migrations, schema, connection pool
– In-browser localStorage fallback for chat history
E. **WebContainer Sandbox**
– **lib/webcontainer/**: spin up in-page container for running generated Node.js apps
– Terminal + file system emulation
F. **External Services**
– GitHub (via git-proxy API) for cloning, pushing code
– Deployment targets: Netlify, Fly.io, Cloudflare
– LLM providers’ APIs
– Supabase (Auth + optional persistence)

##### Relationships and Data Flows
1. User interacts with the Next.js frontend (Chat UI, Editor, Settings).
2. Frontend calls serverless endpoints under `/api/*`:
– `/api/llmcall` → orchestrates LLM request → streams tokens back to client.
– `/api/chat` & `/api/chats/*` → CRUD chat history.
– `/api/git-proxy` → Git operations with external repos.
– `/api/deploy-to-netlify` or `/api/deploy-to-machine` → triggers CI/CD.
– `/api/fire-crawl`, `/api/enhancer` → auxiliary AI utilities.
3. Server handlers invoke:
– **LLM modules** → external LLM APIs.
– **Persistence** → Drizzle on relational DB or localStorage.
– **WebContainer** → create sandbox environment.
– **Deployment scripts** → Netlify CLI, Fly CLI, shell utilities.
4. Browser captures sandbox output (terminal, live preview) via WebContainer client.

##### Architectural Patterns and Principles
- **Client/Server Component Split** (Next.js 13 app router).
- **Serverless Micro-APIs** for modular backend features.
- **Plugin Architecture** for LLM providers (registry + base-provider).
- **Isolated Sandbox** using WebContainer (in-browser virtualization).
- **Declarative DB Migrations** (Drizzle) with versioned SQL.
- **Externalization** of CI/CD via GitHub Actions and deploy targets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Frontend (Browser)" 
        direction TB
        A1["Next.js App"]:::frontend
        A2["Chat UI"]:::frontend
        A3["Code Editor"]:::frontend
        A4["Settings UI"]:::frontend
        A5["Workbench Panels"]:::frontend
        A6["WebContainer Sandbox"]:::sandbox
    end

    subgraph "Backend (Next.js Server)" 
        direction TB
        subgraph "Serverless API" 
            direction TB
            B1["Auth API<br>/api/auth/[...nextauth]"]:::api
            B2["LLM API<br>/api/llmcall"]:::api
            B3["Chat API<br>/api/chat"]:::api
            B4["Chats CRUD API<br>/api/chats/*"]:::api
            B5["Git Proxy API<br>/api/git-proxy/[...path]"]:::api
            B6["Deploy Netlify API<br>/api/deploy-to-netlify"]:::api
            B7["Deploy Machine API<br>/api/deploy-to-machine"]:::api
            B8["Health Check API<br>/api/health"]:::api
        end

        C1["Middleware<br>Session & Routing"]:::backend
        C2["Supabase Auth Integration"]:::backend
    end

    subgraph "LLM Layer" 
        direction TB
        D1["Orchestration<br>lib/.server/llm"]:::backend
        D2["Manager<br>manager.ts"]:::backend
        D3["Base Provider<br>base-provider.ts"]:::backend
        D4["Provider Plugins<br>lib/modules/llm/providers"]:::backend
        D5["Registry<br>registry.ts"]:::backend
    end

    subgraph "Persistence Layer" 
        direction TB
        E1["Drizzle DB<br>schema & migrations"]:::database
        E2["Persistence Logic<br>lib/persistence"]:::backend
        E3["localStorage Fallback"]:::frontend
    end

    subgraph "External Services" 
        direction TB
        F1["GitHub"]:::external
        F2["Netlify"]:::external
        F3["Fly.io"]:::external
        F4["Cloudflare"]:::external
        F5["LLM Provider APIs"]:::external
        F6["Supabase"]:::external
    end

    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        G1["clone.yml"]:::external
        G2["deploy-to-netlify.yml"]:::external
        G3["revert-remote.yml"]:::external
    end

    %% Connections
    A1 --> A2
    A1 --> A3
    A1 --> A4
    A1 --> A5
    A1 --> A6

    A2 -->|POST /api/llmcall| B2
    B2 -->|"calls"| D1
    D1 --> D4
    D4 --> F5

    A2 -->|POST /api/chat| B3
    B3 --> E2
    E2 --> E1
    B3 --> E3

    A2 -->|GET /api/chats/*| B4
    B4 --> E2

    A3 -->|POST /api/git-proxy| B5
    B5 --> F1

    A5 -->|POST /api/deploy-to-netlify| B6
    B6 --> F2
    A5 -->|POST /api/deploy-to-machine| B7
    B7 --> F3

    A6 -->|"Sandbox runtime"| A6

    B1 --> C2
    C1 --> B1
    B1 --> F6

    C1 --> B2
    C1 --> B3

    B8 --> C1

    %% CI/CD triggers
    F1 -->|push event| G1
    G1 -->|deploy| G2
    G1 -->|revert| G3

    %% Click Events for component mapping
    click A1 "https://github.com/sparrow-js/an-codeai/tree/main/app/"
    click A2 "https://github.com/sparrow-js/an-codeai/tree/main/components/chat/"
    click A3 "https://github.com/sparrow-js/an-codeai/tree/main/components/editor/"
    click A4 "https://github.com/sparrow-js/an-codeai/tree/main/components/ui/"
    click A5 "https://github.com/sparrow-js/an-codeai/tree/main/components/workbench/"
    click B1 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/auth/[...nextauth]/route.ts"
    click B2 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/llmcall/route.ts"
    click B3 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/chat/route.ts"
    click B4 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/chats/…/route.ts"
    click B5 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/git-proxy/[...path]/route.ts"
    click B6 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/deploy-to-netlify/route.ts"
    click B7 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/deploy-to-machine/route.ts"
    click B8 "https://github.com/sparrow-js/an-codeai/blob/main/app/api/health/route.ts"
    click C2 "https://github.com/sparrow-js/an-codeai/blob/main/lib/supabase.ts"
    click C1 "https://github.com/sparrow-js/an-codeai/blob/main/middleware.ts"
    click D1 "https://github.com/sparrow-js/an-codeai/tree/main/lib/.server/llm/"
    click D2 "https://github.com/sparrow-js/an-codeai/blob/main/lib/modules/llm/manager.ts"
    click D3 "https://github.com/sparrow-js/an-codeai/blob/main/lib/modules/llm/base-provider.ts"
    click D4 "https://github.com/sparrow-js/an-codeai/tree/main/lib/modules/llm/providers/"
    click D5 "https://github.com/sparrow-js/an-codeai/blob/main/lib/modules/llm/registry.ts"
    click E1 "https://github.com/sparrow-js/an-codeai/blob/main/db/schema.ts"
    click E2 "https://github.com/sparrow-js/an-codeai/blob/main/lib/persistence/index.ts"
    click E3 "https://github.com/sparrow-js/an-codeai/blob/main/lib/persistence/localStorage.ts"
    click A6 "https://github.com/sparrow-js/an-codeai/blob/main/lib/webcontainer/index.ts"
    click A6 "https://github.com/sparrow-js/an-codeai/blob/main/components/workbench/terminal/Terminal.tsx"
    click A6 "https://github.com/sparrow-js/an-codeai/blob/main/components/workbench/terminal/TerminalTabs.tsx"
    click A6 "https://github.com/sparrow-js/an-codeai/blob/main/components/workbench/Preview.tsx"
    click G1 "https://github.com/sparrow-js/an-codeai/blob/main/.github/workflows/clone.yml"
    click G2 "https://github.com/sparrow-js/an-codeai/blob/main/.github/workflows/deploy-to-netlify.yml"
    click G3 "https://github.com/sparrow-js/an-codeai/blob/main/.github/workflows/revert-remote.yml"

    %% Styles
    classDef frontend fill:#E8F5FE,stroke:#0288D1,color:#01579B;
    classDef backend fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A;
    classDef api fill:#E1F5FE,stroke:#039BE5,color:#0277BD,stroke-dasharray: 5 5;
    classDef database fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef external fill:#E0F2F1,stroke:#00796B,color:#004D40;
    classDef sandbox fill:#FFFDE7,stroke:#F9A825,color:#F57F17;
```
