# dyad-sh/dyad architecture

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

- Interactive diagram: https://gitdiagram.com/dyad-sh/dyad
- Repository: https://github.com/dyad-sh/dyad

## Overview

##### Project type and purpose
- This is “Dyad,” a local, open‑source AI app builder packaged as a desktop application.
- It uses a multi‐process architecture (main/preload/renderer), React/TypeScript on the front end, Vite as the build tool, an embedded SQLite database via Drizzle ORM for persistence, and IPC to bridge UI and core logic.

##### File structure
- Top‐level Vite/Electron configs: vite.main.config.mts, vite.preload.config.mts, vite.renderer.config.mts
- src/main & src/preload: Node/Electron main‐process code, IPC host setup, settings management.
- src/renderer (index.html, renderer.tsx, src/app, src/pages, src/components, src/hooks, src/routes): React UI with routing, components, atoms for state.
- src/ipc: Typed IPC client/host definitions, handlers (app, chat, shell, GitHub, settings), processors, and utils.
- src/db + drizzle/: Drizzle ORM schema, migrations, and SQLite store.
- scripts & tools: Build‐time helpers and OS integration scripts (macOS certs, code extraction).

##### README
- Confirms it’s a local, cross‑platform AI builder: privacy‑focused, bring‑your‑own API keys, no cloud lock‑in.

##### Main components and relationships
a. Renderer Process (UI)
- React components, pages and routes (src/pages, src/routes)
- State management via Jotai atoms (src/atoms) and custom hooks (src/hooks)
- Calls into exposed IPC methods to drive chats, app execution, settings, etc.
b. Preload Layer
- Exposes a secure, typed API surface (ipc_client, ipc_host, ipc_types) to the renderer
- Marshals messages between the sandboxed UI and the Node main process
c. Main Process (Core Logic)
- IPC handlers for chat, app loading, dependency management, proposals, GitHub integration, settings (src/ipc/handlers)
- IPC processors for heavy work (executeAddDependency, response_processor)
- Utilities for file IO, shell commands, lock management, environment reading (src/ipc/utils)
- Settings lifecycle (src/main/settings.ts)
d. Data Layer
- Drizzle ORM (drizzle.config.ts) managing SQLite migrations in drizzle/ and runtime schema in src/db
- File‐based storage of user apps, versions, and proposals
e. External Services
- AI API clients (OpenAI or user‑provided) invoked from handlers
- GitHub API integration
- System shell for running user apps

##### Architectural patterns and design principles
- Multi‑process separation (UI ↔ HTML/JS sandbox, Preload ↔ secure bridge, Main ↔ Node/Electron)
- Typed, modular IPC channels for each domain (chat, files, dependencies, settings)
- Code organization: Handlers (entry points) → Processors (business logic) → Utils (shared helpers)
- ORM + migrations ensure reproducible local database schema

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Renderer Process (UI)
    subgraph "Renderer Process (UI)"
        direction TB
        R_HTML["index.html"]:::ui
        R_ENTRY["renderer.tsx"]:::ui
        subgraph "App Shell"
            direction TB
            R_LAYOUT["layout.tsx"]:::ui
            R_TITLE["TitleBar.tsx"]:::ui
        end
        subgraph "Pages & Routes"
            direction TB
            R_PAGES["Pages (home.tsx, chat.tsx, app-details.tsx, settings.tsx)"]:::ui
            R_ROUTES["Routes (home.tsx, chat.tsx, app-details.tsx, settings.tsx, root.tsx)"]:::ui
            R_ROUTER["router.ts"]:::ui
        end
        subgraph "Components"
            direction TB
            R_CMPTS["Components/*"]:::ui
        end
        subgraph "State & Hooks"
            direction TB
            R_ATOMS["Atoms/*"]:::ui
            R_HOOKS["Hooks/*"]:::ui
        end
    end

    %% Preload Layer
    subgraph "Preload Layer (IPC Bridge)"
        direction TB
        P_ENTRY["preload.ts"]:::ipc
        P_VITE["vite.preload.config.mts"]:::ipc
        subgraph "Typed IPC Surface"
            direction TB
            IPC_CLIENT["ipc_client.ts"]:::ipc
            IPC_HOST["ipc_host.ts"]:::ipc
            IPC_TYPES["ipc_types.ts"]:::ipc
        end
    end

    %% Main Process (Core Logic)
    subgraph "Main Process (Core Logic)"
        direction TB
        M_ENTRY["main.ts"]:::core
        M_SETTINGS["settings.ts"]:::core
        M_VITE["vite.main.config.mts"]:::core
        subgraph "IPC Handlers"
            direction TB
            H_APP["app_handlers.ts"]:::core
            H_CHAT["chat_handlers.ts"]:::core
            H_CHAT_STREAM["chat_stream_handlers.ts"]:::core
            H_DEP["dependency_handlers.ts"]:::core
            H_GH["github_handlers.ts"]:::core
            H_PROP["proposal_handlers.ts"]:::core
            H_SET["settings_handlers.ts"]:::core
            H_SHELL["shell_handler.ts"]:::core
            H_NODE["node_handlers.ts"]:::core
            H_DEBUG["debug_handlers.ts"]:::core
        end
        subgraph "Processors"
            direction TB
            P_ADD_DEP["executeAddDependency.ts"]:::core
            P_RESP["response_processor.ts"]:::core
        end
        subgraph "Utilities & Helpers"
            direction TB
            U_FILE["file_utils.ts"]:::core
            U_SHELL["runShellCommand.ts"]:::core
            U_MODEL["get_model_client.ts"]:::core
            U_GIT["git_author.ts"]:::core
            U_LOCK["lock_utils.ts"]:::core
            U_PROC["process_manager.ts"]:::core
            U_ENV["read_env.ts"]:::core
        end
    end

    %% Data Layer (Persistence)
    subgraph "Data Layer"
        direction TB
        D_DRIZZLE_CONF["drizzle.config.ts"]:::data
        D_MIGRATIONS["drizzle/*"]:::data
        subgraph "Runtime Schema & DB"
            direction TB
            D_SCHEMA["schema.ts"]:::data
            D_INDEX["index.ts"]:::data
        end
    end

    %% External Services Integrations
    subgraph "External Services"
        direction TB
        EXT_AI["AI Service"]:::ext
        EXT_GH["GitHub API"]:::ext
        EXT_SHELL["Shell Commands"]:::ext
        EXT_VITE["vite.renderer.config.mts"]:::ext
    end

    %% Connections
    R_ENTRY -->|"calls IPC"| P_ENTRY
    R_HTML -->|loads| R_ENTRY
    R_LAYOUT --> R_ENTRY
    R_PAGES --> R_ENTRY
    R_ROUTES --> R_ENTRY
    R_CMPTS --> R_ENTRY
    R_ATOMS --> R_ENTRY
    R_HOOKS --> R_ENTRY

    P_ENTRY -->|"forwards"| IPC_CLIENT
    P_ENTRY --> IPC_HOST
    IPC_HOST -->|"IPC messages"| M_ENTRY

    M_ENTRY --> H_APP
    M_ENTRY --> H_CHAT
    M_ENTRY --> H_CHAT_STREAM
    M_ENTRY --> H_DEP
    M_ENTRY --> H_GH
    M_ENTRY --> H_PROP
    M_ENTRY --> H_SET
    M_ENTRY --> H_SHELL
    M_ENTRY --> H_NODE
    M_ENTRY --> H_DEBUG

    H_DEP --> P_ADD_DEP
    H_CHAT --> P_RESP

    H_APP --> D_INDEX
    H_CHAT --> D_INDEX
    H_PROP --> D_INDEX
    H_SET --> D_INDEX
    H_GH --> U_GIT

    M_ENTRY --> U_FILE
    M_ENTRY --> U_SHELL
    M_ENTRY --> U_MODEL
    M_ENTRY --> U_GIT
    M_ENTRY --> U_LOCK
    M_ENTRY --> U_PROC
    M_ENTRY --> U_ENV

    M_ENTRY --> D_DRIZZLE_CONF
    M_ENTRY --> D_MIGRATIONS
    M_ENTRY --> D_SCHEMA

    M_ENTRY --> EXT_AI
    M_ENTRY --> EXT_GH
    M_ENTRY --> EXT_SHELL
    M_ENTRY --> EXT_VITE

    EXT_AI -->|responses| H_CHAT_STREAM
    EXT_GH -->|webhooks/response| H_GH
    EXT_SHELL -->|cmd output| H_SHELL

    %% Click Events
    click R_HTML "https://github.com/dyad-sh/dyad/blob/main/index.html"
    click R_ENTRY "https://github.com/dyad-sh/dyad/blob/main/src/renderer.tsx"
    click R_LAYOUT "https://github.com/dyad-sh/dyad/blob/main/src/app/layout.tsx"
    click R_TITLE "https://github.com/dyad-sh/dyad/blob/main/src/app/TitleBar.tsx"
    click R_PAGES "https://github.com/dyad-sh/dyad/tree/main/src/pages/"
    click R_ROUTES "https://github.com/dyad-sh/dyad/tree/main/src/routes/"
    click R_ROUTER "https://github.com/dyad-sh/dyad/blob/main/src/router.ts"
    click R_CMPTS "https://github.com/dyad-sh/dyad/tree/main/src/components/"
    click R_ATOMS "https://github.com/dyad-sh/dyad/tree/main/src/atoms/"
    click R_HOOKS "https://github.com/dyad-sh/dyad/tree/main/src/hooks/"
    click P_ENTRY "https://github.com/dyad-sh/dyad/blob/main/src/preload.ts"
    click P_VITE "https://github.com/dyad-sh/dyad/blob/main/vite.preload.config.mts"
    click IPC_CLIENT "https://github.com/dyad-sh/dyad/blob/main/src/ipc/ipc_client.ts"
    click IPC_HOST "https://github.com/dyad-sh/dyad/blob/main/src/ipc/ipc_host.ts"
    click IPC_TYPES "https://github.com/dyad-sh/dyad/blob/main/src/ipc/ipc_types.ts"
    click M_ENTRY "https://github.com/dyad-sh/dyad/blob/main/src/main.ts"
    click M_SETTINGS "https://github.com/dyad-sh/dyad/blob/main/src/main/settings.ts"
    click M_VITE "https://github.com/dyad-sh/dyad/blob/main/vite.main.config.mts"
    click H_APP "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/app_handlers.ts"
    click H_CHAT "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/chat_handlers.ts"
    click H_CHAT_STREAM "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/chat_stream_handlers.ts"
    click H_DEP "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/dependency_handlers.ts"
    click H_GH "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/github_handlers.ts"
    click H_PROP "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/proposal_handlers.ts"
    click H_SET "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/settings_handlers.ts"
    click H_SHELL "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/shell_handler.ts"
    click H_NODE "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/node_handlers.ts"
    click H_DEBUG "https://github.com/dyad-sh/dyad/blob/main/src/ipc/handlers/debug_handlers.ts"
    click P_ADD_DEP "https://github.com/dyad-sh/dyad/blob/main/src/ipc/processors/executeAddDependency.ts"
    click P_RESP "https://github.com/dyad-sh/dyad/blob/main/src/ipc/processors/response_processor.ts"
    click U_FILE "https://github.com/dyad-sh/dyad/blob/main/src/ipc/utils/file_utils.ts"
    click U_SHELL "https://github.com/dyad-sh/dyad/blob/main/src/ipc/utils/runShellCommand.ts"
    click U_MODEL "https://github.com/dyad-sh/dyad/blob/main/src/ipc/utils/get_model_client.ts"
    click U_GIT "https://github.com/dyad-sh/dyad/blob/main/src/ipc/utils/git_author.ts"
    click U_LOCK "https://github.com/dyad-sh/dyad/blob/main/src/ipc/utils/lock_utils.ts"
    click U_PROC "https://github.com/dyad-sh/dyad/blob/main/src/ipc/utils/process_manager.ts"
    click U_ENV "https://github.com/dyad-sh/dyad/blob/main/src/ipc/utils/read_env.ts"
    click D_DRIZZLE_CONF "https://github.com/dyad-sh/dyad/blob/main/drizzle.config.ts"
    click D_MIGRATIONS "https://github.com/dyad-sh/dyad/tree/main/drizzle/"
    click D_SCHEMA "https://github.com/dyad-sh/dyad/blob/main/src/db/schema.ts"
    click D_INDEX "https://github.com/dyad-sh/dyad/blob/main/src/db/index.ts"
    click EXT_VITE "https://github.com/dyad-sh/dyad/blob/main/vite.renderer.config.mts"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef ipc fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef core fill:#FFF4CC,stroke:#DAA520,color:#DAA520;
    classDef data fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef ext fill:#F0F0F0,stroke:#808080,color:#808080;
```
