# ducan-ne/opencoder architecture

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

- Interactive diagram: https://gitdiagram.com/ducan-ne/opencoder
- Repository: https://github.com/ducan-ne/opencoder

## Overview

##### Project type and purpose
- OpenCoder is a single-package, terminal-based coding assistant that combines a React UI shell with an AI-driven core and a plugin system for “tools” (file I/O, grep, diagnostics, MCP like Playwright, web search).
- It’s distributed as an NPM/Bun CLI (`npx opencoder`), uses Vite for bundling, Vitest for tests, and the Vercel AI SDK for LLM integration.

##### File structure
- Top-level:
- package.json, tsconfig.json, vite.config.ts, vitest.config.ts → build & test configuration
- scripts/ → codegen & patch scripts
- public/assets (yoga.wasm) → WASM runtime for tree-sitter
- examples/ → usage examples showing custom tools & MCP setups
- src/ → main application code subdivided into:
– app/ + components/ → React UI and context
– core.tsx, app.tsx, main.tsx, mcp.tsx → bootstrapping & orchestration
– lib/ → utilities (storage, prompts, diff, logger, config, typescript diagnostics, etc.)
– tools/ → built-in and shared tools; tool registry
- test/ → Vitest suites for UI snapshots, chat flows, utils, tool confirmation

##### README insights
- Built on Vercel AI SDK (pluggable providers)
- Cross-platform shell via Deno
- High-FPS UI with React concurrent rendering
- Plugin system for MCP and custom tools

##### Main components
a. CLI/Runner Layer
- Entrypoint (`src/main.tsx`, `src/app.tsx`)
- Shell abstraction (Deno-backed cross-platform shell)
b. UI Layer
- React components (`src/app/`, `src/components/`)
- WASM asset loader (`public/assets/yoga.wasm`)
c. Core Logic & State
- Chat orchestration (`src/core.tsx`, `src/app/chat.tsx`)
- Context & store (`src/app/context.tsx`, `src/lib/store/`)
- Prompts & config (`src/lib/prompts.ts`, `bump.config.ts`)
d. AI SDK Integration
- Vercel AI SDK adapter (bundled under `src/bundled/`)
- Model providers (OpenAI, Anthropic, Ollama, etc.)
e. Tool Abstraction & Plugin System
- Tool registry & loader (`src/tools/tools.ts`)
- Built-in tools (read/write/edit files, grep, diagnostics)
- MCP tools (Playwright, web-search via `src/mcp.tsx`)
f. OS / External Services
- File system & process access (native Node/Bun + Deno shell)
- Network calls (LLM endpoints, auto-updater checks)
- Persistent storage (chat history via `src/lib/storage.ts`)
g. Build & Test Infrastructure
- Vite (bundling), Vitest (unit/UI tests), scripts for types & import rewriting

##### Relationships & interactions
- User types input → React UI component → dispatches to Core
- Core builds AI SDK request → Vercel AI SDK → external LLM → response
- Core inspects response for tool calls → invokes Tool modules → Tools interact with FS or external APIs → returns result to Core
- Core updates chat history (in-memory + persistent store) → UI re-renders updated chat
- Auto-updater component polls NPM registry for updates
- Examples folder is not part of runtime but illustrates extension points

##### Architectural patterns & technologies
- Plugin/Registry pattern for tools & MCP extensions
- Component-driven UI with React concurrent rendering
- Separation of concerns: UI vs Core vs Tools vs AI adapter vs OS boundary
- Dependency injection via user config (model provider, tool list)
- High performance via WASM (tree-sitter) and React Compiler

##### Elements
- Core & State (green rectangles)
- Tools & Plugins (orange)
- AI Providers (purple cloud)
- Annotations for key frameworks (React, Vite, Vitest, Deno shell)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User Input"]:::external -->|types command| CLI["CLI Entrypoint"]:::core

    subgraph "CLI/Runner Layer"
        direction TB
        CLI["src/main.tsx"]:::core
        Boot["src/app.tsx<br/>src/index.ts"]:::core
    end

    CLI -->|bootstraps| Boot

    subgraph "UI Layer"
        direction TB
        UI["React UI Shell"]:::ui
        Components["UI Components"]:::ui
        WASM["WASM Loader"]:::external
    end

    Boot --> UI
    UI --> Components
    UI --> WASM

    subgraph "Core Logic & State"
        direction TB
        Core["Core Orchestrator"]:::core
        ChatFlow["Chat Flow"]:::core
        ChatMsg["Chat Messages"]:::core
        Context["Context Provider"]:::core
        Store["Store & Tool Confirmation"]:::core
        Prompts["Prompts & Config"]:::core
    end

    Components --> Core
    Core --> ChatFlow
    ChatFlow --> ChatMsg
    Core --> Context
    Context --> Store
    Core --> Prompts

    subgraph "AI SDK Integration"
        direction TB
        TSAdapter["Tree-sitter Adapter"]:::ai
        SDK["Vercel AI SDK"]:::ai
        Providers["LLM Providers"]:::ai
    end

    Core -->|builds request| SDK
    SDK --> Providers
    SDK --> TSAdapter

    subgraph "Tool Abstraction & Plugin System"
        direction TB
        Registry["Tool Registry"]:::tools
        Builtins["Built-in Tools"]:::tools
        MCP["MCP Extensions"]:::tools
    end

    Core --> Registry
    Registry --> Builtins
    Registry --> MCP

    subgraph "Built-in Tools"
        direction TB
        Read["read-file"]:::tools
        Write["write-file"]:::tools
        Edit["edit-file"]:::tools
        Grep["grep"]:::tools
        Glob["glob"]:::tools
        Diag["check-diagnostics"]:::tools
        Bash["bash"]:::tools
        Eval["evaluate"]:::tools
        MemR["memory-read"]:::tools
        MemW["memory-write"]:::tools
        Fallback["fallback-rejected-message"]:::tools
        Fetch["fetch"]:::tools
    end

    Builtins --> Read
    Builtins --> Write
    Builtins --> Edit
    Builtins --> Grep
    Builtins --> Glob
    Builtins --> Diag
    Builtins --> Bash
    Builtins --> Eval
    Builtins --> MemR
    Builtins --> MemW
    Builtins --> Fallback
    MCP --> Fetch

    subgraph "OS / External Services"
        direction TB
        FS["File System"]:::external
        Shell["Shell Abstraction"]:::external
        Network["Network/API"]:::external
        Storage["Persistent Storage"]:::external
    end

    Read --> FS
    Write --> FS
    Edit --> FS
    Bash --> Shell
    Eval --> Shell
    Fetch --> Network
    Store --> Storage

    subgraph "Build & Test Infrastructure"
        direction TB
        Vite["vite.config.ts"]:::build
        Vitest["vitest.config.ts"]:::build
        Scripts["Codegen & Patch Scripts"]:::build
        Tests["test/"]:::build
    end

    Boot --> Vite
    Boot --> Vitest
    Vite --> Scripts
    Vitest --> Tests

    %% Data flow back to UI
    Core -->|updates chat| Components
    Components -->|renders| UI

    %% Click Events
    click CLI "https://github.com/ducan-ne/opencoder/blob/main/src/main.tsx"
    click Boot "https://github.com/ducan-ne/opencoder/blob/main/src/app.tsx"
    click UI "https://github.com/ducan-ne/opencoder/tree/main/src/app/"
    click Components "https://github.com/ducan-ne/opencoder/tree/main/src/components/"
    click WASM "https://github.com/ducan-ne/opencoder/blob/main/public/assets/yoga.wasm"
    click Core "https://github.com/ducan-ne/opencoder/blob/main/src/core.tsx"
    click ChatFlow "https://github.com/ducan-ne/opencoder/blob/main/src/app/chat.tsx"
    click ChatMsg "https://github.com/ducan-ne/opencoder/blob/main/src/app/chat-message.tsx"
    click Context "https://github.com/ducan-ne/opencoder/blob/main/src/app/context.tsx"
    click Store "https://github.com/ducan-ne/opencoder/tree/main/src/lib/store/"
    click Storage "https://github.com/ducan-ne/opencoder/blob/main/src/lib/storage.ts"
    click Prompts "https://github.com/ducan-ne/opencoder/blob/main/src/lib/prompts.ts"
    click Prompts "https://github.com/ducan-ne/opencoder/blob/main/bump.config.ts"
    click TSAdapter "https://github.com/ducan-ne/opencoder/blob/main/src/bundled/treesitter.js"
    click Registry "https://github.com/ducan-ne/opencoder/blob/main/src/tools/tools.ts"
    click Read "https://github.com/ducan-ne/opencoder/blob/main/src/tools/read-file.tsx"
    click Write "https://github.com/ducan-ne/opencoder/blob/main/src/tools/write-file.tsx"
    click Edit "https://github.com/ducan-ne/opencoder/blob/main/src/tools/edit-file.tsx"
    click Grep "https://github.com/ducan-ne/opencoder/blob/main/src/tools/grep.tsx"
    click Glob "https://github.com/ducan-ne/opencoder/blob/main/src/tools/glob.tsx"
    click Diag "https://github.com/ducan-ne/opencoder/blob/main/src/tools/check-diagnostics.tsx"
    click Bash "https://github.com/ducan-ne/opencoder/blob/main/src/tools/bash.tsx"
    click Eval "https://github.com/ducan-ne/opencoder/blob/main/src/tools/evaluate.tsx"
    click MemR "https://github.com/ducan-ne/opencoder/blob/main/src/tools/memory-read.tsx"
    click MemW "https://github.com/ducan-ne/opencoder/blob/main/src/tools/memory-write.tsx"
    click Fallback "https://github.com/ducan-ne/opencoder/blob/main/src/tools/shared/fallback-rejected-message.tsx"
    click MCP "https://github.com/ducan-ne/opencoder/blob/main/src/mcp.tsx"
    click Fetch "https://github.com/ducan-ne/opencoder/blob/main/src/tools/fetch.tsx"
    click FS "https://github.com/ducan-ne/opencoder/blob/main/src/lib/file.ts"
    click Shell "https://github.com/ducan-ne/opencoder/blob/main/src/lib/env.ts"
    click Vite "https://github.com/ducan-ne/opencoder/blob/main/vite.config.ts"
    click Vitest "https://github.com/ducan-ne/opencoder/blob/main/vitest.config.ts"
    click Scripts "https://github.com/ducan-ne/opencoder/blob/main/scripts/dts.ts"
    click Scripts "https://github.com/ducan-ne/opencoder/blob/main/scripts/patch.js"
    click Scripts "https://github.com/ducan-ne/opencoder/blob/main/scripts/rewrite-import.js"
    click Tests "https://github.com/ducan-ne/opencoder/tree/main/test/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,stroke-width:1px,rx:5px,ry:5px
    classDef core fill:#DFFFD0,stroke:#28a745,stroke-width:1px,rx:5px,ry:5px
    classDef tools fill:#FFE8C0,stroke:#d9730d,stroke-width:1px,rx:5px,ry:5px
    classDef external fill:#F0F0F0,stroke:#6a737d,stroke-width:1px,rx:5px,ry:5px
    classDef ai fill:#E8D0FF,stroke:#6f42c1,stroke-width:1px,rx:5px,ry:5px
    classDef build fill:#FFF4D0,stroke:#cb2431,stroke-width:1px,rx:5px,ry:5px
```
