# sst/opencode architecture

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

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

## Overview

##### Project type and purpose
- This is a Turborepo-powered monorepo for “OpenCode,” a provider-agnostic AI coding agent with a client/server architecture.
- The primary goal is to ship multiple clients (CLI/TUI, Desktop UI, Web Console, Slack bot), shared SDKs/plugins, plus a serverless backend (API + database) and a public docs site.

##### File-structure clues
- Top‐level “packages” folder holds subpackages:
- packages/opencode – the CLI (Bun/TypeScript)
- packages/tui – Terminal UI library
- packages/desktop – React-based desktop client
- packages/console/app – Remix-based Web Console
- packages/console/function & packages/console/core – serverless API code + ORM/migrations
- packages/mail, packages/slack – mail templates & Slack integration
- packages/sdk – multi-language SDKs (Go, JS, Stainless)
- packages/ui – shared React component library
- packages/web – Astro-based public website and docs
- “infra” directory contains SST stacks (infra/app.ts, infra/console.ts, infra/desktop.ts) that deploy:
- An API Gateway + Lambda functions
- The Web Console (Remix app)
- The Desktop host (e.g. S3/CloudFront or self-hosted)
- Configuration files: bunfig.toml, tsconfig.json, sst.config.ts, turbo.json, GitHub workflows, Husky hooks.

##### Core components
A. Clients (left side)
- CLI Tool (packages/opencode) built in Bun/TS, loads the TUI library
- Terminal UI library (packages/tui) used by the CLI
- Desktop App (packages/desktop) in React/Electron
- Web Console (packages/console/app) in Remix SSR
- Slack Bot (packages/slack)
- Public Website & Docs (packages/web, Astro)
- SDKs for third-party integrations (packages/sdk/js, packages/sdk/go, etc.)
B. API Layer (center)
- SST “App” stack (infra/app.ts)
- API Gateway (HTTP API)
- Lambda functions (packages/console/function) implementing endpoints for auth, logs, “zen” chat, workspace, billing, keys, docs proxy, debug, Stripe webhooks
- Shared core library (packages/console/core): Drizzle ORM schemas, migrations, business logic for accounts, sessions, billing, providers, models, workspace
C. Persistence & External Services (right side)
- Amazon RDS / PostgreSQL (via Drizzle ORM)
- Amazon SES or SMTP (mail templates in packages/mail)
- Slack API (packages/slack)
- Cloudflare KV or Node-based cache (packages/console/resource)
- 3rd-party AI providers (OpenAI, Anthropic, Google) accessed via provider-agnostic abstractions in console/core/src/provider
- Stripe (billing/payment)
D. CI/CD & Deployment (bottom)
- GitHub Actions (.github/workflows) for build, test, typecheck, publish
- SST deploy (infra/*.ts)
- npm/pnpm/bun publishing scripts (script/, packages/*/script)

##### Relationships & data flows
- Clients → HTTP requests → API Gateway → Lambda handlers → console/core business logic → Drizzle ORM → Postgres
- Lambda handlers also invoke mail templates (packages/mail) and Slack integration (packages/slack) as needed
- console/core routes AI‐requests to 3rd-party model APIs
- SDKs provide a direct client abstraction over API (client.ts, client.gen.ts)
- Desktop & Web Console also call the same API endpoints
- CI/CD pipelines detect changes in packages and deploy updated stacks or publish packages

##### Architectural patterns & design principles
- Monorepo with Turborepo: atomic packages + shared tooling
- Client/Server separation: multiple thin clients consume a single REST/FaaS backend
- Serverless microservices via SST (Api + Lambda)
- Hexagonal/business-logic layer in console/core, leveraged by both function handlers and Remix loaders
- Shared UI component library (packages/ui for Web Console, packages/tui for CLI)
- Provider-agnostic AI layer (console/core/src/provider) enabling pluggable model backends
- Database migrations managed via Drizzle and compiled snapshots (console/core/migrations)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients (green)
    subgraph "Clients" 
        direction TB
        CLI["CLI Tool<br/>(Bun/TypeScript)"]:::client
        TUI["Terminal UI Library"]:::client
        Desktop["Desktop App<br/>(React/Electron)"]:::client
        WebConsoleClient["Web Console<br/>(Remix SSR)"]:::client
        SlackBot["Slack Bot"]:::client
        PublicSite["Public Website & Docs<br/>(Astro)"]:::client
        SDKs["SDKs<br/>(Go, JS, Stainless)"]:::client
    end

    CLI -->|uses| TUI
    CLI -->|HTTP Requests| APIGateway
    Desktop -->|HTTP Requests| APIGateway
    WebConsoleClient -->|HTTP Requests| APIGateway
    SlackBot -->|HTTP Requests| APIGateway
    PublicSite -->|HTTP Requests| APIGateway
    SDKs -->|API Client| APIGateway

    %% API Layer (blue)
    subgraph "API Layer" 
        direction TB
        SSTApp["SST App Stack<br/>(infra/app.ts)"]:::infra
        APIGateway["API Gateway<br/>(HTTP API)"]:::api
        Lambdas["Lambda Functions"]:::api
        CoreLib["Shared Core Library<br/>(ORM & Business Logic)"]:::lib
        MailTemplates["Mail Templates"]:::api
        CacheResource["Cache Resource"]:::api
        ProviderAI["AI Provider Abstractions"]:::api
    end

    SSTApp --> APIGateway
    APIGateway -->|routes to| Lambdas
    Lambdas -->|calls| CoreLib
    Lambdas -->|sends emails| MailTemplates
    Lambdas -->|uses cache| CacheResource
    CoreLib -->|routes AI requests| ProviderAI

    %% Persistence & External Services (orange)
    subgraph "Data & External Services"
        direction TB
        Postgres["PostgreSQL<br/>(Amazon RDS)"]:::db
        SES["Email Service<br/>(SES/SMTP)"]:::db
        SlackAPI["Slack API"]:::db
        CacheExt["Cloudflare KV / Node Cache"]:::db
        AIProviders["3rd-Party AI Providers"]:::db
        Stripe["Stripe<br/>(Billing)"]:::db
    end

    CoreLib -->|DB queries| Postgres
    MailTemplates -->|SMTP| SES
    SlackTemplates -- uses --> SlackAPI
    ProviderAI --> AIProviders
    Lambdas -->|Stripe webhooks| Stripe

    %% CI/CD & Deployment (gray)
    subgraph "CI/CD & Infra"
        direction TB
        GHActions["GitHub Actions"]:::infra
        Turborepo["Turborepo Config<br/>(turbo.json)"]:::infra
        SSTConfig["SST Config<br/>(sst.config.ts)"]:::infra
        PublishScripts["Publish & Release Scripts"]:::infra
        InfraConsole["SST Console Stack<br/>(infra/console.ts)"]:::infra
        InfraDesktop["SST Desktop Stack<br/>(infra/desktop.ts)"]:::infra
    end

    GHActions --> SSTApp
    GHActions --> InfraConsole
    GHActions --> InfraDesktop
    GHActions --> PublishScripts

    %% Styles
    classDef client fill:#e0ffe0,stroke:#00aa00,stroke-width:1px;
    classDef api fill:#e0f0ff,stroke:#0066cc,stroke-width:1px;
    classDef lib fill:#f5e0ff,stroke:#aa00aa,stroke-width:1px;
    classDef db fill:#fff0e0,stroke:#cc6600,stroke-width:1px;
    classDef infra fill:#f0f0f0,stroke:#666666,stroke-width:1px;

    %% Click Events
    click CLI "https://github.com/sst/opencode/tree/dev/packages/opencode"
    click TUI "https://github.com/sst/opencode/tree/dev/packages/tui"
    click Desktop "https://github.com/sst/opencode/tree/dev/packages/desktop"
    click WebConsoleClient "https://github.com/sst/opencode/tree/dev/packages/console/app"
    click SlackBot "https://github.com/sst/opencode/tree/dev/packages/slack"
    click PublicSite "https://github.com/sst/opencode/tree/dev/packages/web"
    click SDKs "https://github.com/sst/opencode/tree/dev/packages/sdk/go"
    click SSTApp "https://github.com/sst/opencode/blob/dev/infra/app.ts"
    click InfraConsole "https://github.com/sst/opencode/blob/dev/infra/console.ts"
    click InfraDesktop "https://github.com/sst/opencode/blob/dev/infra/desktop.ts"
    click Lambdas "https://github.com/sst/opencode/tree/dev/packages/console/function/src"
    click CoreLib "https://github.com/sst/opencode/tree/dev/packages/console/core/src"
    click CoreLib "https://github.com/sst/opencode/tree/dev/packages/console/core/migrations"
    click MailTemplates "https://github.com/sst/opencode/tree/dev/packages/console/mail/emails/templates"
    click CacheResource "https://github.com/sst/opencode/blob/dev/packages/console/resource/resource.cloudflare.ts"
    click CacheResource "https://github.com/sst/opencode/blob/dev/packages/console/resource/resource.node.ts"
    click ProviderAI "https://github.com/sst/opencode/blob/dev/packages/console/core/src/provider.ts"
    click ProviderAI "https://github.com/sst/opencode/blob/dev/packages/console/core/src/schema/provider.sql.ts"
    click GHActions "https://github.com/sst/opencode/tree/dev/.github/workflows"
    click Turborepo "https://github.com/sst/opencode/blob/dev/turbo.json"
    click SSTConfig "https://github.com/sst/opencode/blob/dev/sst.config.ts"
    click PublishScripts "https://github.com/sst/opencode/tree/dev/script/"
```
