# forkbikash/opencode architecture

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

- Interactive diagram: https://gitdiagram.com/forkbikash/opencode
- Repository: https://github.com/forkbikash/opencode

## Overview

##### Project type and purpose
- This is a full-stack, multi-client monorepo that delivers:
- A terminal-first CLI/TUI (“OpenCode”) agent (packages/opencode + packages/tui).
- A web-based “console” management UI (packages/console/app + packages/console/core + serverless functions + mail + resource infra).
- A public landing site (packages/web).
- Language SDKs (packages/sdk/go, sdk/js, sdk/stainless).
- A VSCode extension (sdks/vscode).
- Purpose: provide an LLM-powered coding assistant with local CLI/TUI clients, remote server for state, multi-client frontend, database, mail, and pluggable LLM providers.

##### File structure
- Top-level “packages/…” directories map to deployable components:
- packages/opencode: Node/TS CLI logic (bin/opencode) and language-model agent core.
- packages/tui: Go-based terminal UI library.
- packages/console/app: React/Remix-style web console.
- packages/console/core: shared business logic, database schema (Drizzle), migrations.
- packages/console/function: serverless handlers (auth, log processing).
- packages/console/mail: email templates and renderer.
- packages/console/resource: SST definitions for AWS resources.
- packages/web: Astro-based marketing/docs site.
- packages/sdk: generated client libraries.
- sdks/vscode: VSCode extension bundling the core CLI.
- “infra/”: SST stacks deploying the app, console, desktop, and staging environments.
- Config files (bunfig.toml, tsconfig.json, turbo.json, workflow YAMLs) orchestrate build/test/deploy.

##### README for additional insights
- Mentions client/server architecture: CLI/TUI client can drive a remote server.
- Recommends Anthropic, but provider-agnostic.
- Uses Bun, Go, SST for local development and infra.

##### Main components
a. Clients (green cluster)
– Terminal CLI/TUI (TS binary + Go TUI library)
– VSCode extension
– Web console UI (React/Remix)
– Public landing site (Astro)
b. API Layer (blue cluster)
– API Gateway / HTTP endpoints (handled by serverless functions in packages/console/function)
– Auth service (OAuth + session management)
– Core server (packages/opencode/src/server & packages/console/core)
– Event bus / message queue (for logging & session events)
c. Data stores (orange cluster)
– Relational DB (Postgres via Drizzle ORM + migrations)
– Blob store / S3 (for attachments, logs)
– Key-value store / Cloudflare KV (optional, for caches)
– Mail templates & rendering engine (packages/console/mail)
d. Infrastructure (gray cluster)
– SST stacks (infra/app.ts, infra/console.ts, infra/desktop.ts, infra/stage.ts)
– CI/CD pipelines (GitHub Actions workflows)
e. External services (purple cluster)
– LLM providers (Anthropic, OpenAI, Google, local models)
– Email provider (SES or SMTP)
– Stripe (billing webhook)
– Git hosting (GitHub API)

##### Relationships and interactions
- CLI/TUI, VSCode, Web console → API Gateway → Auth → Core server → DB
- Core server emits events → Event bus → Log processor → Storage
- Core server triggers mail → Mail service → Email provider
- Infrastructure provisions resources via SST → AWS (Lambda, API Gateway, RDS, S3, CloudFront)
- SDKs are generated from stainless schemas after server-side changes (server.ts)

##### Architectural patterns & principles
- Client/Server separation: multiple thin clients talking HTTP/websocket to the same backend.
- Serverless microservices: discrete Lambda functions for auth, billing, chat (“zen”) endpoints.
- Shared core library: business logic and DB layer centralized in packages/console/core and packages/opencode/src/server.
- Event-driven logging and asynchronous tasks via an internal bus.
- Monorepo orchestration: Turborepo + Bun + Go + SST.
- Provider-agnostic LLM interface: pluggable providers under src/session and src/provider.

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Clients" 
    direction TB
    CLICore["Terminal CLI Agent\n(Node/TS)"]:::client
    TUILib["Terminal TUI Library\n(Go)"]:::client
    VSCodeExt["VSCode Extension"]:::client
    WebConsole["Web Console UI\n(React/Remix)"]:::client
    Landing["Public Landing Site\n(Astro)"]:::client
  end

  subgraph "API Layer"
    direction TB
    APIGW["API Gateway\n(Serverless)"]:::backend
    AuthFunc["Auth Service\n(Function)"]:::backend
    CoreServer["Core Server\n(Node/TS)"]:::backend
    LogProc["Log Processor\n(Function)"]:::backend
  end

  subgraph "Data Layer"
    direction TB
    Postgres["Postgres\n(Drizzle ORM)"]:::data
    KVStore["KV Store\n(Cloudflare KV)"]:::data
    EventBus["Event Bus\n(Message Queue)"]:::data
    S3Store["Blob Store\n(S3)"]:::data
    MailService["Mail Templates & Renderer"]:::data
  end

  subgraph "Infrastructure" 
    direction TB
    SST_App["infra/app.ts"]:::infra
    SST_Console["infra/console.ts"]:::infra
    SST_Desktop["infra/desktop.ts"]:::infra
    SST_Stage["infra/stage.ts"]:::infra
    CICD["CI/CD Pipelines\n(.github/workflows)"]:::infra
  end

  subgraph "External Services"
    direction TB
    LLM["LLM Providers"]:::external
    EmailProv["Email Provider\n(SES/SMTP)"]:::external
    Stripe["Stripe\n(Billing Webhook)"]:::external
    GitHubAPI["GitHub API"]:::external
  end

  %% Client to API
  CLICore -->|"HTTP/REST"| APIGW
  TUILib -->|"RPC"| CLICore
  VSCodeExt -->|"HTTP/REST"| APIGW
  WebConsole -->|"HTTP/REST, WebSocket"| APIGW

  %% API flow
  APIGW -->|"Authorize"| AuthFunc
  AuthFunc -->|"JWT Session"| CoreServer
  APIGW -->|"Invoke"| CoreServer

  %% Core to data
  CoreServer -->|"SQL Queries"| Postgres
  CoreServer -.->|"Cache"| KVStore

  %% Event-driven logging
  CoreServer -->|"Publish Events"| EventBus
  EventBus -->|"Consume Logs"| LogProc
  LogProc -->|"Store Logs"| S3Store

  %% Mail flow
  CoreServer -->|"Trigger Email"| MailService
  MailService -->|"SMTP"| EmailProv

  %% Billing and external
  CoreServer -->|"Webhook"| Stripe
  CoreServer -->|"API Calls"| GitHubAPI
  CoreServer -->|"LLM API"| LLM

  %% Infra provisioning
  CICD -->|"Deploy"| SST_App
  CICD -->|"Deploy"| SST_Console
  CICD -->|"Deploy"| SST_Desktop
  CICD -->|"Deploy"| SST_Stage
  SST_App --> APIGW
  SST_App --> CoreServer
  SST_App --> Postgres
  SST_App --> S3Store
  SST_Console --> WebConsole
  SST_Desktop --> CLICore

  %% Click Events
  click CLICore "https://github.com/forkbikash/opencode/tree/dev/packages/opencode"
  click TUILib "https://github.com/forkbikash/opencode/tree/dev/packages/tui"
  click VSCodeExt "https://github.com/forkbikash/opencode/tree/dev/sdks/vscode"
  click WebConsole "https://github.com/forkbikash/opencode/tree/dev/packages/console/app"
  click CoreServer "https://github.com/forkbikash/opencode/tree/dev/packages/console/core"
  click AuthFunc "https://github.com/forkbikash/opencode/blob/dev/packages/console/function/src/auth.ts"
  click LogProc "https://github.com/forkbikash/opencode/blob/dev/packages/console/function/src/log-processor.ts"
  click MailService "https://github.com/forkbikash/opencode/tree/dev/packages/console/mail"
  click SST_App "https://github.com/forkbikash/opencode/blob/dev/infra/app.ts"
  click SST_Console "https://github.com/forkbikash/opencode/blob/dev/infra/console.ts"
  click SST_Desktop "https://github.com/forkbikash/opencode/blob/dev/infra/desktop.ts"
  click SST_Stage "https://github.com/forkbikash/opencode/blob/dev/infra/stage.ts"
  click CICD "https://github.com/forkbikash/opencode/blob/dev/.github/workflows/*.yml"

  %% Styles
  classDef client fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32,stroke-width:2px
  classDef backend fill:#e3f2fd,stroke:#1565c0,color:#1565c0,stroke-width:2px
  classDef data fill:#fff3e0,stroke:#ef6c00,color:#ef6c00,stroke-width:2px
  classDef infra fill:#eceff1,stroke:#546e7a,color:#546e7a,stroke-width:2px
  classDef external fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a,stroke-width:2px
```
