# mendableai/open-lovable architecture

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

- Interactive diagram: https://gitdiagram.com/mendableai/open-lovable
- Repository: https://github.com/mendableai/open-lovable

## Overview

##### Project Type & Purpose
- This is a full-stack Next.js (React) application (“Open Lovable”) that lets users chat with AI to scaffold, edit, and preview React apps in real time.
- The App Router’s “app” directory contains both the UI pages and a suite of serverless API routes under `app/api/*`. These handlers orchestrate sandboxes, invoke AI services, scrape data, manage Vite builds, and return streaming code or logs back to the frontend.

##### Key Architectural Components
a. Frontend (Next.js App Router & React components)
- app/page.tsx, app/layout.tsx – pages and global layout
- app/components/ui & components/ui – shared UI primitives (buttons, inputs, toggles)
- components/CodeApplicationProgress, SandboxPreview, HMRErrorDetector – visual feedback & previews
- Tailwind CSS (globals.css, tailwind.config.ts) for styling
b. Backend / Orchestrator (Next.js Serverless API routes)
- app/api/*/route.ts – handlers like analyze-edit-intent, generate-ai-code-stream, run-command, sandbox-status, etc.
- config/app.config.ts – central configuration for keys, timeouts, sandbox parameters
- lib/*.ts – shared utilities (file parsing, intent analysis, context selection, file search execution)
c. External Services
- E2B API (Sandboxes) – containerized environments for running user code & Vite dev server
- Firecrawl API – web scraping / screenshotting for “scrape-url-enhanced” and “scrape-screenshot”
- AI Providers – OpenAI, Anthropic, Groq for code generation, intent analysis, streaming responses
d. Local Dev & Build Tools
- Vite (monitored via sandbox logs & vite-error endpoints)
- Next.js build & dev commands (`npm run dev`)
- ESLint, PostCSS, pnpm/ npm lockfiles, TypeScript config

##### Relationships & Data Flows
- User interacts with the React UI in the browser → UI triggers API calls (e.g., “Generate Code,” “Analyze Intent”).
- API Route receives request → uses lib utilities to:
1) Call AI provider(s) to generate or analyze code
2) Spin up or manipulate an E2B sandbox via E2B_API_KEY (create, run, kill, install packages)
3) Run Vite inside sandbox, capture logs, detect errors, apply HMR fixes
4) Optionally call Firecrawl for scraping tasks
- Streaming responses (SSE / fetch streams) traverse back to the UI to update code editor, preview pane, or error detector in real time.

##### Architectural Patterns & Principles
- Serverless micro-endpoints: each API function is a single-responsibility route.
- Streaming-first UX: endpoints named `*-stream` deliver chunked updates.
- “Sandbox-as-a-Service”: ephemeral containers via E2B while isolating user code executions.
- Clear separation: UI layer vs. orchestration layer vs. sandbox execution vs. third-party AI/web services.

##### Diagramming Recommendations
- Blue for frontend
- Green for serverless/API
- Orange for sandbox runtime
- Purple for external 3rd-party services
- Data formats: JSON payloads, code chunks, log streams.

## Diagram (Mermaid)

```mermaid
graph TB

  %% Client Layer
  subgraph "Client (Browser UI)"
    direction TB
    Page["app/page.tsx"]:::frontend
    Layout["app/layout.tsx"]:::frontend
    UICore["app/components/ui"]:::frontend
    ExtUI["components/ui"]:::frontend
    Progress["CodeApplicationProgress.tsx"]:::frontend
    ErrorDet["HMRErrorDetector.tsx"]:::frontend
    SandboxPrev["SandboxPreview.tsx"]:::frontend
    GlobalsCSS["app/globals.css"]:::frontend
    TailwindConf["tailwind.config.ts"]:::frontend
    PostCSS["postcss.config.mjs"]:::frontend
    NextConf["next.config.ts"]:::frontend
  end

  %% Backend Layer
  subgraph "Serverless Backend (Next.js API Routes)" 
    direction TB
    AnalyzeIntent["app/api/analyze-edit-intent/route.ts"]:::backend
    GenCodeStream["app/api/generate-ai-code-stream/route.ts"]:::backend
    ApplyCodeStream["app/api/apply-ai-code-stream/route.ts"]:::backend
    CreateSandbox["app/api/create-ai-sandbox/route.ts"]:::backend
    KillSandbox["app/api/kill-sandbox/route.ts"]:::backend
    MonitorLogs["app/api/monitor-vite-logs/route.ts"]:::backend
    RunCmd["app/api/run-command/route.ts"]:::backend
    SandboxStatus["app/api/sandbox-status/route.ts"]:::backend
    ScrapeURL["app/api/scrape-url-enhanced/route.ts"]:::backend
    ScrapeShot["app/api/scrape-screenshot/route.ts"]:::backend
    Config["config/app.config.ts"]:::config

    subgraph "Shared Utilities (lib)" 
      direction TB
      ContextSel["lib/context-selector.ts"]:::util
      IntentAnalyzer["lib/edit-intent-analyzer.ts"]:::util
      FileParser["lib/file-parser.ts"]:::util
      SearchExec["lib/file-search-executor.ts"]:::util
      Utils["lib/utils.ts"]:::util
      Icons["lib/icons.ts"]:::util
    end
  end

  %% Sandbox Manager
  E2B["E2B Sandbox Service"]:::sandbox

  %% External Services
  subgraph "External Third-Party Services"
    direction TB
    AIProv["AI Providers\n(OpenAI/Anthropic/Groq)"]:::external
    Firecrawl["Firecrawl API"]:::external
  end

  %% Data Flows
  Page -->|"HTTP REST"| AnalyzeIntent
  Page -->|"HTTP REST"| GenCodeStream
  Page -->|"HTTP REST"| CreateSandbox

  AnalyzeIntent -->|"Calls AI Provider"| AIProv
  GenCodeStream -->|"Calls AI Provider"| AIProv
  CreateSandbox -->|"Manage sandbox"| E2B
  RunCmd -->|"Executes in sandbox"| E2B
  MonitorLogs -->|"Streams logs"| E2B
  ScrapeURL -->|"HTTP REST"| Firecrawl
  ScrapeShot -->|"HTTP REST"| Firecrawl
  KillSandbox -->|"Manage sandbox"| E2B
  SandboxStatus -->|"Query status"| E2B

  GenCodeStream -->|"- - - SSE Stream"| Page
  MonitorLogs -->|"- - - SSE Stream"| Page

  %% Click Events
  click Page "https://github.com/mendableai/open-lovable/blob/main/app/page.tsx"
  click Layout "https://github.com/mendableai/open-lovable/blob/main/app/layout.tsx"
  click UICore "https://github.com/mendableai/open-lovable/tree/main/app/components/ui"
  click ExtUI "https://github.com/mendableai/open-lovable/tree/main/components/ui"
  click Progress "https://github.com/mendableai/open-lovable/blob/main/components/CodeApplicationProgress.tsx"
  click ErrorDet "https://github.com/mendableai/open-lovable/blob/main/components/HMRErrorDetector.tsx"
  click SandboxPrev "https://github.com/mendableai/open-lovable/blob/main/components/SandboxPreview.tsx"
  click GlobalsCSS "https://github.com/mendableai/open-lovable/blob/main/app/globals.css"
  click TailwindConf "https://github.com/mendableai/open-lovable/blob/main/tailwind.config.ts"
  click PostCSS "https://github.com/mendableai/open-lovable/blob/main/postcss.config.mjs"
  click NextConf "https://github.com/mendableai/open-lovable/blob/main/next.config.ts"
  click AnalyzeIntent "https://github.com/mendableai/open-lovable/blob/main/app/api/analyze-edit-intent/route.ts"
  click GenCodeStream "https://github.com/mendableai/open-lovable/blob/main/app/api/generate-ai-code-stream/route.ts"
  click ApplyCodeStream "https://github.com/mendableai/open-lovable/blob/main/app/api/apply-ai-code-stream/route.ts"
  click CreateSandbox "https://github.com/mendableai/open-lovable/blob/main/app/api/create-ai-sandbox/route.ts"
  click KillSandbox "https://github.com/mendableai/open-lovable/blob/main/app/api/kill-sandbox/route.ts"
  click MonitorLogs "https://github.com/mendableai/open-lovable/blob/main/app/api/monitor-vite-logs/route.ts"
  click RunCmd "https://github.com/mendableai/open-lovable/blob/main/app/api/run-command/route.ts"
  click SandboxStatus "https://github.com/mendableai/open-lovable/blob/main/app/api/sandbox-status/route.ts"
  click ScrapeURL "https://github.com/mendableai/open-lovable/blob/main/app/api/scrape-url-enhanced/route.ts"
  click ScrapeShot "https://github.com/mendableai/open-lovable/blob/main/app/api/scrape-screenshot/route.ts"
  click Config "https://github.com/mendableai/open-lovable/blob/main/config/app.config.ts"
  click ContextSel "https://github.com/mendableai/open-lovable/blob/main/lib/context-selector.ts"
  click IntentAnalyzer "https://github.com/mendableai/open-lovable/blob/main/lib/edit-intent-analyzer.ts"
  click FileParser "https://github.com/mendableai/open-lovable/blob/main/lib/file-parser.ts"
  click SearchExec "https://github.com/mendableai/open-lovable/blob/main/lib/file-search-executor.ts"
  click Utils "https://github.com/mendableai/open-lovable/blob/main/lib/utils.ts"
  click Icons "https://github.com/mendableai/open-lovable/blob/main/lib/icons.ts"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#1E71E1,color:#000
  classDef backend fill:#DFF7D0,stroke:#3C9E14,color:#000
  classDef sandbox fill:#FFE4B3,stroke:#E69A00,color:#000
  classDef external fill:#E7D0FF,stroke:#7C3FBF,color:#000
  classDef config fill:#F0F0F0,stroke:#999,color:#000
  classDef util fill:#E8F7D0,stroke:#6C9E00,color:#000
```
