# trolleroof/cafecode architecture

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

- Interactive diagram: https://gitdiagram.com/trolleroof/cafecode
- Repository: https://github.com/trolleroof/cafecode

## Overview

##### Project type and purpose
- This is a full-stack AI-powered coding tutor platform called “Cafécode.”
- Frontend: Next.js 13+ with TypeScript, Tailwind, shadcn/ui, Monaco editor, and WebContainer.
- Backend: Node.js/Express microservices in Docker, deployed on Fly.io.
- Database: Supabase (Postgres + row-level security + real-time auth).
- External services: Gemini AI API for code assistance, Stripe for payments.

##### File structure
- Top-level folders:
- frontend – Next.js app, UI components, client-side services, WebContainer integration.
- backend – Express routes, services modules, workspace files, Docker and deployment scripts.
- supabase – SQL migrations and local config for the Postgres database.
- .kiro/specs – spec-driven design documents (design.md, requirements.md, tasks.md).
- Notice subdirectories:
- frontend/app + frontend/components: screens and reusable UI.
- frontend/services + frontend/hooks: client-side orchestration layers.
- backend/routes + backend/services: modular API handlers and business logic.
- backend/workspaces: per-user ephemeral file systems.
- docker-compose.yml, backend/Dockerfile, backend/fly.toml: deployment config.
- Configuration and build scripts:
- next.config.js, tsconfig.json, tailwind.config.ts, postcss.config.js for frontend.
- .dockerignore, Dockerfile, deploy.sh for backend.
- supabase/.temp and supabase/migrations for DB provisioning.

##### README for additional insights
- Reinforces microservices architecture separating AI orchestration, workspace management, payment, file sync.
- Highlights real-time syncing via WebSockets and/or WebContainerSyncService.
- Describes migration from server-side node-pty pty streams to in-browser WebContainer runtime.

##### Main components and their relationships
A. Frontend
- Next.js SSR/SSG UI with pages under frontend/app.
- Monaco editor, file explorer, terminal rendered via WebContainer in the browser.
- Client-side services (BuildService, PreviewService, SynchronizationService) talk to backend over REST or WebSockets.
- Auth workflows using Supabase client library and JWT.
B. WebContainer sandbox
- Browser-native Node.js runtime that executes code, file I/O, and terminal sessions.
- Synchronized state via WebContainerSyncService and backend sync endpoints.
C. Backend (Express)
- HTTP API endpoints (routes folder) for account, guided projects, code analysis, file management, payments, search, translation.
- Services layer handles business logic: UserWorkspaceManager, FileSystemIndexer, StepDecisionEngine, StripeService, Gemini integration, etc.
- Real-time channels (WebSockets) for editor/terminal syncing.
- Middleware stack: Helmet, CORS, rate limiter, JWT verification against Supabase Auth.
- Workspace persistence and ephemeral storage under backend/workspaces.
D. Database (Supabase/Postgres)
- User profiles, project metadata, payment records.
- Row-level security ensures each user only sees their workspace.
- Triggers or migrations to enforce schema constraints.
E. External services
- Gemini AI API for code suggestions and decision engine.
- Stripe API for payment processing.
- Supabase Auth & realtime.
F. Deployment
- Frontend: Vercel or custom server via next config.
- Backend: Docker on Fly.io with fly.toml, deploy.sh.
- Supabase project provisioned via CLI and migrations.

##### Elements to include for clarity
- Clear labels on every component and service.
- Layer separation (presentation, application, data, external).
- Annotations for important design principles (microservices, spec-driven, real-time sync).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    subgraph "User’s Browser" 
        U[("User Interface")]
    end

    %% Frontend Layer
    subgraph "Frontend App (Next.js + WebContainer)" 
        direction TB
        FE_APP["Next.js App"]:::compute
        FE_CONFIG["Global Styles & Config"]:::compute
        subgraph "UI Components" 
            ME["MonacoEditor"]:::compute
            FE["FileExplorer"]:::compute
            TE["Terminal"]:::compute
            WCF["WebContainerFileExplorer"]:::compute
            WCT["WebContainerTerminal"]:::compute
            PM["PaymentModal & Handlers"]:::compute
        end
        subgraph "Client-Side Services"
            BS["BuildService"]:::compute
            PS["PreviewService"]:::compute
            SS["SynchronizationService"]:::compute
            WCS["WebContainerService"]:::compute
            WFS["WebContainerFileSystem"]:::compute
        end
        subgraph "Auth Workflows"
            SA["supabase.ts"]:::compute
            UA["useAuth"]:::compute
        end
    end

    %% WebContainer Sandbox (in-browser)
    subgraph "WebContainer Sandbox" 
        direction TB
        WCR["Browser Node.js Runtime"]:::compute
        WCS2["WebContainerSyncService"]:::compute
    end

    %% Backend Layer
    subgraph "Backend API (Express)" 
        direction TB
        BE_SERVER["server.js"]:::compute
        subgraph "Routes (HTTP/WebSocket)"
            R_ACCOUNT["account.js"]:::compute
            R_CODE["code.js"]:::compute
            R_FILES["files.js / files-v2.js"]:::compute
            R_GUIDED["guided.js / guided_recap.js"]:::compute
            R_HINT["hint.js"]:::compute
            R_SEARCH["search.js"]:::compute
            R_STRIPE["stripe.js"]:::compute
            R_SYNC["sync.js"]:::compute
            R_TRANSLATE["translate.js"]:::compute
            R_LANG["java.js / nodejs.js / python.js"]:::compute
        end
        subgraph "Services (Business Logic)"
            S_UWM["UserWorkspaceManager"]:::compute
            S_UFS["UserFileService"]:::compute
            S_USM["UserTerminalManager"]:::compute
            S_INDEX["FileSystemIndexer"]:::compute
            S_DECIDE["StepDecisionEngine"]:::compute
            S_WS["WebContainerSyncService"]:::compute
            S_STRIPE["StripeService"]:::compute
            S_GEM["gemini.js"]:::compute
            S_PROFILE["ProfileService"]:::compute
            S_PARSE["InstructionParser"]:::compute
            S_STATIC["StaticCreationChecker"]:::compute
            S_CACHE["Cache"]:::compute
        end
        subgraph "Workspace Persistence"
            WS["workspaces/ (ephemeral FS)"]:::compute
        end
        subgraph "Middleware"
            MW["Helmet, CORS, RateLimiter, JWT"]:::compute
        end
    end

    %% Database
    DB["Supabase / Postgres"]:::database
    MIG["migrations/ & .temp/"]:::database

    %% External Services
    GEM["Gemini AI API"]:::external
    STR["Stripe API"]:::external
    AUTH["Supabase Auth & Realtime"]:::external

    %% Connections
    U -->|"interacts with"| FE_APP
    FE_APP -->|"HTTP/SSR"| FE_CONFIG
    FE_APP -->|"uses TS/Tailwind"| FE_CONFIG
    FE_APP -->|"renders"| ME & FE & TE
    FE_APP -->|"integrates"| WCF & WCT
    FE_APP -->|"invokes"| BS & PS & SS
    FE_APP -->|"auth via"| SA & UA
    FE_APP -->|"executes in"| WCR
    WCR -->|"sync events"| WCS2
    WCS2 -->|"WS REST"| R_SYNC
    FE_APP -->|"REST/WebSocket"| BE_SERVER
    BE_SERVER -->|"routes to"| R_ACCOUNT & R_CODE & R_FILES & R_GUIDED & R_HINT & R_SEARCH & R_STRIPE & R_SYNC & R_TRANSLATE & R_LANG
    BE_SERVER -->|"calls"| S_UWM & S_UFS & S_USM & S_INDEX & S_DECIDE & S_WS & S_STRIPE & S_GEM & S_PROFILE & S_PARSE & S_STATIC & S_CACHE
    BE_SERVER -->|"manages FS"| WS
    BE_SERVER -->|"uses middleware"| MW
    BE_SERVER -->|"SQL/Realtime"| DB
    BE_SERVER -->|"runs migrations"| MIG
    BE_SERVER -->|"calls AI"| GEM
    BE_SERVER -->|"processes payments"| STR
    BE_SERVER -->|"verifies JWT"| AUTH

    %% Click Events
    click FE_APP "https://github.com/trolleroof/cafecode/tree/production/frontend/app"
    click FE_CONFIG "https://github.com/trolleroof/cafecode/blob/production/frontend/app/globals.css"
    click FE_CONFIG "https://github.com/trolleroof/cafecode/blob/production/frontend/globals.css"
    click FE_CONFIG "https://github.com/trolleroof/cafecode/blob/production/frontend/tailwind.config.ts"
    click FE_CONFIG "https://github.com/trolleroof/cafecode/blob/production/frontend/postcss.config.js"
    click FE_CONFIG "https://github.com/trolleroof/cafecode/blob/production/frontend/tsconfig.json"
    click FE_CONFIG "https://github.com/trolleroof/cafecode/blob/production/frontend/next.config.js"
    click ME "https://github.com/trolleroof/cafecode/blob/production/frontend/components/MonacoEditor.tsx"
    click FE "https://github.com/trolleroof/cafecode/blob/production/frontend/components/FileExplorer.tsx"
    click TE "https://github.com/trolleroof/cafecode/blob/production/frontend/components/Terminal.tsx"
    click WCF "https://github.com/trolleroof/cafecode/blob/production/frontend/components/WebContainerFileExplorer.tsx"
    click WCT "https://github.com/trolleroof/cafecode/blob/production/frontend/components/WebContainerTerminal.tsx"
    click BS "https://github.com/trolleroof/cafecode/blob/production/frontend/services/BuildService.ts"
    click PS "https://github.com/trolleroof/cafecode/blob/production/frontend/services/PreviewService.ts"
    click SS "https://github.com/trolleroof/cafecode/blob/production/frontend/services/SynchronizationService.ts"
    click WCS "https://github.com/trolleroof/cafecode/blob/production/frontend/services/WebContainerService.ts"
    click WFS "https://github.com/trolleroof/cafecode/blob/production/frontend/services/WebContainerFileSystem.ts"
    click SA "https://github.com/trolleroof/cafecode/blob/production/frontend/lib/supabase.ts"
    click UA "https://github.com/trolleroof/cafecode/blob/production/frontend/hooks/useAuth.ts"
    click WCS2 "https://github.com/trolleroof/cafecode/tree/production/.kiro/specs/webcontainer-vite-integration"
    click R_ACCOUNT "https://github.com/trolleroof/cafecode/blob/production/backend/routes/account.js"
    click R_CODE "https://github.com/trolleroof/cafecode/blob/production/backend/routes/code.js"
    click R_FILES "https://github.com/trolleroof/cafecode/blob/production/backend/routes/files.js"
    click R_FILES "https://github.com/trolleroof/cafecode/blob/production/backend/routes/files-v2.js"
    click R_GUIDED "https://github.com/trolleroof/cafecode/blob/production/backend/routes/guided.js"
    click R_HINT "https://github.com/trolleroof/cafecode/blob/production/backend/routes/hint.js"
    click R_SEARCH "https://github.com/trolleroof/cafecode/blob/production/backend/routes/search.js"
    click R_STRIPE "https://github.com/trolleroof/cafecode/blob/production/backend/routes/stripe.js"
    click R_SYNC "https://github.com/trolleroof/cafecode/blob/production/backend/routes/sync.js"
    click R_TRANSLATE "https://github.com/trolleroof/cafecode/blob/production/backend/routes/translate.js"
    click R_LANG "https://github.com/trolleroof/cafecode/blob/production/backend/routes/java.js"
    click R_LANG "https://github.com/trolleroof/cafecode/blob/production/backend/routes/nodejs.js"
    click R_LANG "https://github.com/trolleroof/cafecode/blob/production/backend/routes/python.js"
    click BE_SERVER "https://github.com/trolleroof/cafecode/blob/production/backend/server.js"
    click S_UWM "https://github.com/trolleroof/cafecode/blob/production/backend/services/UserWorkspaceManager.js"
    click S_UFS "https://github.com/trolleroof/cafecode/blob/production/backend/services/UserFileService.js"
    click S_USM "https://github.com/trolleroof/cafecode/blob/production/backend/services/UserTerminalManager.js"
    click S_INDEX "https://github.com/trolleroof/cafecode/blob/production/backend/services/FileSystemIndexer.js"
    click S_DECIDE "https://github.com/trolleroof/cafecode/blob/production/backend/services/StepDecisionEngine.js"
    click S_WS "https://github.com/trolleroof/cafecode/blob/production/backend/services/WebContainerSyncService.js"
    click S_STRIPE "https://github.com/trolleroof/cafecode/blob/production/backend/services/StripeService.js"
    click S_GEM "https://github.com/trolleroof/cafecode/blob/production/backend/services/gemini.js"
    click WS "https://github.com/trolleroof/cafecode/tree/production/backend/workspaces/"
    click MIG "https://github.com/trolleroof/cafecode/tree/production/supabase/migrations/"
    click MIG "https://github.com/trolleroof/cafecode/tree/production/supabase/.temp/"
    click STR "https://github.com/trolleroof/cafecode/blob/production/backend/routes/stripe.js"
    click GEM "https://github.com/trolleroof/cafecode/blob/production/backend/services/gemini.js"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef database fill:#D5E8D4,stroke:#82B366,stroke-width:1px
    classDef external fill:#F3E2A9,stroke:#D79B00,stroke-width:1px
    classDef websocket stroke-dasharray: 5 5
```
