# hny287/onlook architecture

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

- Interactive diagram: https://gitdiagram.com/hny287/onlook
- Repository: https://github.com/hny287/onlook

## Overview

##### Project type and purpose
- This is a full-stack, monorepo web application—“Onlook for Web”—that provides a visual, AI-powered code editor and preview for Next.js + TailwindCSS projects.
- It comprises:
- A Next.js front-end (apps/web/client)
- A server layer (apps/web/server and tRPC endpoints)
- Supabase serverless functions (apps/backend) for auth, database migrations, Stripe webhooks
- A Postgres database (Supabase) using Drizzle ORM (packages/db)
- Multiple shared packages (AI, parser, models, UI components, utilities)

##### File structure
- Top-level “apps” folder contains:
- backend/ – Supabase Deno functions + migrations
- web/ – Next.js client, Node/Bun-based server, and Electron-style preload script
- “packages” folder holds shared libraries:
- ai, parser, models, db, email, ui, utility, rpc etc.
- “docs” and “assets” for documentation and images
- Configuration files: workspace package.json, tsconfig.json, Dockerfiles, CI workflows

##### README
- Describes the high-level architecture:
1. On app creation → code loaded into a web container
2. Container serves code → iFrame preview
3. Editor indexes and instruments DOM ↔ code mapping
4. Edits flow bi-directionally: visual canvas ↔ code
5. AI chat tool has code access via functions
- Lists core technologies: Next.js, Supabase, Drizzle, TailwindCSS, Bun, tRPC

a. Main components
- Frontend (Next.js client in apps/web/client)
- Preload Layer (apps/web/preload)
- Editor Canvas & AI Chat UI
- API Server (apps/web/server with tRPC endpoints)
- Supabase Serverless Functions (apps/backend/functions)
- Postgres Database (Supabase)
- Web Container / Sandbox Service (to run user’s code)
- Shared packages (ai, parser, models, db, ui, utility)
- External APIs (OpenAI, Stripe)
b. Relationships & data flows
1. User’s browser ↔ Next.js client
2. Next.js client ↔ tRPC API Server (via HTTP or WebSocket)
3. tRPC API Server ↔ Supabase Postgres (via Drizzle)
4. Next.js client ↔ Supabase Functions (for realtime, auth, webhooks)
5. Editor Canvas ↔ Web Container iFrame ↔ Sandbox Service
6. AI Chat UI → RPC calls to AI package → external LLM providers
7. Stripe Webhook Function → Supabase → API Server notifications
c. Architectural patterns & principles
- Monorepo with Yarn/Bun workspaces
- Separation of concerns: client / server / serverless functions / shared libraries
- Serverless + containerized sandbox for dynamic code execution
- Micro-frontend style: Preview iframe isolated from editor UI
- tRPC for type-safe end-to-end APIs
- Drizzle ORM for type-safe database access
d. Key technologies & libraries
- Next.js (SSR, routing, API routes)
- Bun & Deno (fast JavaScript runtimes for server & functions)
- tRPC (type-safe RPC)
- Supabase (auth, Postgres, Realtime)
- Drizzle ORM (packages/db)
- AI toolkit (packages/ai)
- Parser & Instrumentation (packages/parser)
- UI Component Library (packages/ui)
- Utility & model layers (packages/utility, packages/models)

##### Detail
- Major sub-systems: preview iframe container, instrumentation, chat tool, migrations
- Shared package dependencies as a “Libraries” side bar or layer
- Don’t be afraid to break the system into modular zones (UI, API, Functions, Data, AI)
- The goal is maximum clarity on how data and events flow end-to-end, and how each component interacts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        User["User Browser"]:::external
        NextClient["Next.js Client"]:::frontend
        Preload["Preload Layer"]:::frontend
        EditorCanvas["Editor Canvas"]:::frontend
        AIChatUI["AI Chat UI"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        TRPCServer["tRPC API Server"]:::backend
    end

    %% Serverless Functions
    subgraph "Supabase Functions"
        direction TB
        SupabaseFunctions["Supabase Serverless Functions"]:::backend
    end

    %% Sandbox & Preview
    subgraph "Sandbox Service"
        direction TB
        SandboxService["Web Container / Sandbox"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PostgresDB["Postgres Database (Drizzle ORM)"]:::database
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        AIPkg["AI Toolkit"]:::library
        ParserPkg["Parser & Instrumentation"]:::library
        ModelsPkg["Data Models"]:::library
        UIPkg["UI Component Library"]:::library
        UtilPkg["Utility Functions"]:::library
        RPCPkg["RPC Helpers"]:::library
        ConstPkg["Shared Constants"]:::library
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI"]:::external
        Stripe["Stripe"]:::external
    end

    %% Connections
    User -->|"interacts via HTTP/WS"| NextClient
    NextClient -->|"uses preload script"| Preload
    NextClient -->|"HTTP/WebSocket"| TRPCServer
    NextClient -->|"HTTP (auth, realtime)"| SupabaseFunctions
    NextClient -->|"renders preview in iFrame"| EditorCanvas
    EditorCanvas -->|"loads sandbox"| SandboxService
    SandboxService -->|"instrumented by"| ParserPkg

    AIChatUI -->|"RPC calls"| RPCPkg
    AIChatUI -->|"uses AI toolkit"| AIPkg
    AIPkg -->|"calls LLM"| OpenAI

    TRPCServer -->|"Drizzle ORM"| PostgresDB
    TRPCServer -->|"triggers notifications"| NextClient
    SupabaseFunctions -->|"writes/authenticates"| PostgresDB
    Stripe -->|"webhook events"| SupabaseFunctions
    SupabaseFunctions -->|"notifies"| TRPCServer

    %% Shared Libraries dependencies
    NextClient --> UIPkg
    NextClient --> ConstPkg
    Preload --> ParserPkg
    TRPCServer --> RPCPkg
    TRPCServer --> ModelsPkg
    SupabaseFunctions --> RPCPkg
    SupabaseFunctions --> ModelsPkg
    SandboxService --> ConstPkg
    AIPkg --> UtilPkg

    %% Click Events
    click NextClient "https://github.com/hny287/onlook/tree/main/apps/web/client"
    click Preload "https://github.com/hny287/onlook/tree/main/apps/web/preload"
    click TRPCServer "https://github.com/hny287/onlook/tree/main/apps/web/server"
    click SupabaseFunctions "https://github.com/hny287/onlook/tree/main/apps/backend/supabase/functions"
    click PostgresDB "https://github.com/hny287/onlook/tree/main/packages/db"
    click AIPkg "https://github.com/hny287/onlook/tree/main/packages/ai"
    click ParserPkg "https://github.com/hny287/onlook/tree/main/packages/parser"
    click ModelsPkg "https://github.com/hny287/onlook/tree/main/packages/models"
    click UIPkg "https://github.com/hny287/onlook/tree/main/packages/ui"
    click UtilPkg "https://github.com/hny287/onlook/tree/main/packages/utility"
    click RPCPkg "https://github.com/hny287/onlook/tree/main/packages/rpc"
    click ConstPkg "https://github.com/hny287/onlook/tree/main/packages/constants"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef backend fill:#E6FFEA,stroke:#28A745,stroke-width:1px
    classDef database fill:#FFECD1,stroke:#D29922,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#6A737D,stroke-width:1px,stroke-dasharray: 5 5
    classDef library fill:#F5F5F5,stroke:#959DA5,stroke-width:1px
```
