How sst/opencode works
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)