# v-shaal/opencausol architecture

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

- Interactive diagram: https://gitdiagram.com/v-shaal/opencausol
- Repository: https://github.com/v-shaal/opencausol

## Overview

##### Project type and purpose
- This is a large monorepo for “OpenCode.ai,” an AI-powered coding agent with multiple clients (CLI/TUI, desktop GUI, web console, VSCode extension) and a server-side backend composed of serverless functions and core business logic (data, migrations, billing).
- The README calls it “The AI coding agent built for the terminal” but the file tree reveals a full-stack, multi-client, micro-services-style architecture.

##### Main components
a. Clients
- CLI/TUI client (packages/opencode – written in TypeScript/Bun)
- Desktop Electron-style GUI (packages/desktop – React)
- Web console (packages/console/app – Remix or similar SSR)
- Official website (packages/web – Astro)
- SDKs (packages/sdk/js & packages/sdk/go)
- VSCode extension (sdks/vscode)
- Slack integration (packages/slack)
b. Backend
- API layer & serverless functions (packages/console/function – auth, log processing)
- Core business logic & data layer (packages/console/core – Drizzle ORM, migrations, models)
- Mail templates & sending (packages/console/mail)
- Infrastructure definitions (infra/*.ts – SST stacks for AWS Lambda, Dynamo/Postgres, S3, CloudFront, API Gateway, Stripe)
- Shared cloud resources (packages/console/resource)
c. External Services
- Anthropic/OpenAI/Google local LLM providers
- Stripe (billing)
- GitHub/Discord (OAuth, notifications)
- Email service (SES or third-party)

##### Relationships and data flows
- Clients invoke the CLI binary or GUI, which calls into the local opencode engine (packages/opencode). That engine streams commands to a background API endpoint (packages/console/function).
- The API layer routes requests into core business logic (packages/console/core), which reads/writes a database (e.g., RDS via Drizzle) and interacts with billing (Stripe) and storage (S3).
- Mail component generates emails.
- Infrastructure code (infra/) deploys the serverless endpoints, database, DNS, CloudFront, and websockets or REST API.
- SDKs are generated clients for the API layer, consumed by UI or external integrators.

##### Architectural patterns and design principles
- Micro-client architecture: CLI, desktop, web, SDKs, Slack, VSCode extension all reuse the same core API.
- Serverless backend (SST) with function-per-purpose.
- Shared core library for business logic (monorepo packages/console/core).
- Drizzle ORM and migration scripts for database schema.
- CI/CD workflows automate type checks, tests, deployments, and release across all packages.
- LSP support and TUI focus for the CLI.

##### Technologies, frameworks, and libraries
- Bun (runtime) and Turborepo (monorepo management)
- TypeScript and React (desktop, console/app)
- Astro (website)
- SST (infrastructure as code)
- Drizzle ORM (database)
- AWS Lambda, API Gateway, S3, CloudFront, RDS
- Stripe, OAuth providers, Email service
- Go (SDK for Go)
- VSCode Extension API

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Clients"
        direction TB
        CLI["CLI/TUI (opencode CLI)"]:::client
        Desktop["Desktop GUI (OpenCode Desktop)"]:::client
        WebConsole["Web Console (Remix SSR)"]:::client
        Website["Official Website (Astro)"]:::client
        JSSDK["JavaScript SDK"]:::client
        GoSDK["Go SDK"]:::client
        VSCode["VSCode Extension"]:::client
        Slack["Slack Integration"]:::client
    end

    subgraph "API Layer & Serverless Functions"
        direction TB
        Auth["Auth Function"]:::api
        LogProcessor["Log Processor Function"]:::api
        MailService["Mail Service"]:::api
    end

    subgraph "Core Business Logic & Data"
        direction TB
        CoreSrc["Core Source (packages/console/core/src)"]:::core
        DrizzleConfig["Drizzle Config"]:::core
        Migrations["Migrations"]:::core
        Database["PostgreSQL / Drizzle ORM"]:::core
    end

    subgraph "Infrastructure Definitions"
        direction TB
        InfraApp["Main App Stack"]:::infra
        InfraConsole["Console Function Stack"]:::infra
        InfraDesktop["Desktop Stack"]:::infra
        InfraStage["Stage Configuration"]:::infra
        SharedResource["Shared Cloud Resources"]:::infra
    end

    subgraph "External Services"
        direction TB
        Stripe["Stripe (Billing)"]:::external
        OAuth["OAuth Providers (GitHub, Discord)"]:::external
        EmailService["SES / Email Service"]:::external
    end

    %% Connections
    CLI -->|calls| Auth
    Desktop -->|calls| Auth
    WebConsole -->|calls| Auth
    Website -->|calls| Auth
    JSSDK -->|calls| Auth
    GoSDK -->|calls| Auth
    VSCode -->|uses SDK| JSSDK
    Slack -->|calls| Auth

    Auth -->|routes to| CoreSrc
    LogProcessor -->|processes logs and routes| CoreSrc
    MailService -->|generates emails| MailService
    CoreSrc -->|configures via| DrizzleConfig
    CoreSrc -->|runs migrations| Migrations
    CoreSrc -->|reads/writes| Database

    CoreSrc -->|billing calls| Stripe
    CoreSrc -->|auth calls| OAuth
    MailService -->|sends via| EmailService

    InfraApp -->|deploys| Auth
    InfraConsole -->|deploys| LogProcessor
    InfraDesktop -->|deploys desktop backend| Auth
    InfraStage -->|configures stage| InfraApp
    SharedResource -->|provides resources| Auth
    SharedResource -->|provides resources| CoreSrc
    SharedResource -->|provides resources| MailService

    %% Click Events
    click CLI "https://github.com/v-shaal/opencausol/tree/dev/packages/opencode"
    click Desktop "https://github.com/v-shaal/opencausol/tree/dev/packages/desktop"
    click WebConsole "https://github.com/v-shaal/opencausol/tree/dev/packages/console/app"
    click Website "https://github.com/v-shaal/opencausol/tree/dev/packages/web"
    click JSSDK "https://github.com/v-shaal/opencausol/tree/dev/packages/sdk/js"
    click GoSDK "https://github.com/v-shaal/opencausol/tree/dev/packages/sdk/go"
    click VSCode "https://github.com/v-shaal/opencausol/tree/dev/sdks/vscode"
    click Slack "https://github.com/v-shaal/opencausol/tree/dev/packages/slack"
    click Auth "https://github.com/v-shaal/opencausol/blob/dev/packages/console/function/src/auth.ts"
    click LogProcessor "https://github.com/v-shaal/opencausol/blob/dev/packages/console/function/src/log-processor.ts"
    click MailService "https://github.com/v-shaal/opencausol/tree/dev/packages/console/mail"
    click CoreSrc "https://github.com/v-shaal/opencausol/tree/dev/packages/console/core/src/"
    click DrizzleConfig "https://github.com/v-shaal/opencausol/blob/dev/packages/console/core/drizzle.config.ts"
    click Migrations "https://github.com/v-shaal/opencausol/tree/dev/packages/console/core/migrations/"
    click SharedResource "https://github.com/v-shaal/opencausol/tree/dev/packages/console/resource"
    click InfraApp "https://github.com/v-shaal/opencausol/blob/dev/infra/app.ts"
    click InfraConsole "https://github.com/v-shaal/opencausol/blob/dev/infra/console.ts"
    click InfraDesktop "https://github.com/v-shaal/opencausol/blob/dev/infra/desktop.ts"
    click InfraStage "https://github.com/v-shaal/opencausol/blob/dev/infra/stage.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#66b2ff,color:#003366
    classDef api fill:#d4edda,stroke:#28a745,color:#155724
    classDef core fill:#fff3cd,stroke:#ffcd39,color:#856404
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef external fill:#fff5e6,stroke:#ffcc66,color:#663d00
```
