# terragon-labs/terragon-oss architecture

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

- Interactive diagram: https://gitdiagram.com/terragon-labs/terragon-oss
- Repository: https://github.com/terragon-labs/terragon-oss

## Overview

##### Main Components
a. User Interfaces
- Web UI (apps/www: Next.js frontend + API routes)
- CLI Tool (“terry” in apps/cli)
- Documentation site (apps/docs)
- Optional integrations: Slack commands/webhooks, GitHub app mentions
b. API & Real-Time Services
- Next.js API Routes (apps/www/src/app/api/…) serve as HTTP/REST and proxy to AI providers
- Broadcast Service (apps/broadcast): WebSocket server for real-time task status updates
- MCP Server (packages/mcp-server): gRPC/HTTP server for CLI/MCP-compatible clients
c. Task Orchestration & Execution
- Daemon Service (packages/daemon): orchestrates agent sessions, retries, logging
- Sandbox Service (packages/sandbox + sandbox-image): spins up isolated Docker containers per task
- Agent Library (packages/agent): common agent abstraction and tool-call logic
d. Shared Backend
- Shared Package (packages/shared): database schema, data models, cron jobs, feature-flag logic
- Database (PostgreSQL via Drizzle ORM)
- Redis (caching, rate limiting, queues)
- R2 (object storage for attachments/images)
- Stripe (billing & webhooks)
e. External AI & Third-Party Services
- AI Providers: Anthropic (Claude Code), OpenAI Codex, Amp, Google Gemini, OpenRouter
- GitHub API (PR creation, webhook handlers)
- Slack API (slash commands, event subscriptions)

##### Relationships & Data Flows
1) User triggers a task via Web UI / CLI / Slack mention / GitHub mention
2) Web UI or CLI calls Next.js API or MCP Server → enqueues task (via Redis or direct Daemon API)
3) Daemon Service picks up task → uses Sandbox Service to run isolated container
4) Sandbox clones repo, runs code, tests, formatting, then writes results to shared DB and/or pushes commit & PR to GitHub
5) Daemon logs status events → Broadcast Service pushes real-time updates back to UI/WebSocket clients
6) Next.js frontend queries shared DB or listens on WebSocket for live updates
7) Billing events flow: UI → Next.js server actions → Shared package writes to Stripe / DB

##### Architectural Patterns
- Monorepo with multiple apps & packages sharing code (packages/*)
- Microservices / containerized sandbox per task
- Event-driven updates via WebSocket (Broadcast)
- CQRS style server actions in Next.js API
- Cron-driven automations in Shared (packages/shared/src/automations)

##### Relevant Technologies & Frameworks
- Node.js v20+, pnpm, TurboRepo
- Next.js 14 (app directory, server & client components)
- TypeScript throughout
- Docker (for sandbox-image)
- Redis, PostgreSQL, R2, Stripe, WebSockets
- gRPC/HTTP for MCP Server
- Drizzle ORM, Jotai (state), TRPC-like patterns in Next.js server actions

##### Detailed Element Checklist
1) UI/API calls
2) Task enqueue in Redis / direct Daemon call
3) Daemon → Sandbox spin-up
4) Sandbox → GitHub (commit & PR)
5) Daemon → Broadcast → UI
6) Billing & storage flows
- Optionally annotate:

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        Browser["Next.js Frontend"]:::presentation
        CLI["CLI Tool (terry)"]:::presentation
        Docs["Documentation Site"]:::presentation
    end

    subgraph "API Layer"
        API["Next.js API Routes"]:::api
        GitHubWebhook["GitHub Webhook Handlers"]:::api
        SlackWebhook["Slack Webhook Handlers"]:::api
        StripeLib["Stripe Helpers"]:::api
    end

    subgraph "Real-Time Layer"
        Broadcast["Broadcast Service (WS)"]:::realtime
    end

    subgraph "MCP/API Server"
        MCP["MCP Server"]:::api
    end

    subgraph "Orchestration Layer"
        Daemon["Daemon Service"]:::orchestration
        CronJobs["Cron Jobs (Automations)"]:::orchestration
    end

    subgraph "Execution Layer"
        SandboxSvc["Sandbox Service"]:::execution
        SandboxImg["Sandbox Docker Image"]:::execution
    end

    subgraph "Libraries"
        Agent["Agent Library"]:::library
        Shared["Shared Package"]:::library
    end

    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::data
        Redis["Redis"]:::data
        R2Storage["R2 Object Storage"]:::data
    end

    subgraph "External Services"
        AIProviders["AI Provider APIs"]:::external
        GitHubAPI["GitHub API"]:::external
        SlackAPI["Slack API"]:::external
        StripeExt["Stripe"]:::external
    end

    %% Relationships
    Browser -->|"HTTP POST /api/new-task"| API
    CLI -->|"gRPC/HTTP"| MCP
    CLI -->|"HTTP POST /api/new-task"| API
    API -->|"enqueue task"| Redis
    MCP -->|"enqueue task"| Redis
    CronJobs -->|"schedule tasks"| Daemon
    Daemon -->|"pick task"| Redis
    Daemon -->|"spin up container"| SandboxSvc
    SandboxSvc -->|"use Docker Image"| SandboxImg
    SandboxSvc -->|"write results"| Postgres
    SandboxSvc -->|"upload artifacts"| R2Storage
    Daemon -->|"log status"| Broadcast
    Broadcast -->|"WebSocket: task-status"| Browser
    API -->|"read data"| Postgres
    API -->|"billing events"| StripeExt
    StripeExt -->|"webhooks"| StripeLib
    API -->|"proxy AI calls"| AIProviders
    GitHubWebhook -->|"handle events"| Daemon
    SlackWebhook -->|"handle events"| Daemon
    Daemon -->|"commit & PR"| GitHubAPI
    Daemon --> Agent
    SandboxSvc --> Agent
    Shared --> Daemon
    Shared --> API
    Shared --> SandboxSvc

    %% Click Events
    click Browser "https://github.com/terragon-labs/terragon-oss/tree/main/apps/www"
    click CLI "https://github.com/terragon-labs/terragon-oss/tree/main/apps/cli"
    click Docs "https://github.com/terragon-labs/terragon-oss/tree/main/apps/docs"
    click API "https://github.com/terragon-labs/terragon-oss/tree/main/apps/www/src/app/api"
    click GitHubWebhook "https://github.com/terragon-labs/terragon-oss/tree/main/apps/www/src/app/api/webhooks/github"
    click SlackWebhook "https://github.com/terragon-labs/terragon-oss/tree/main/apps/www/src/app/api/webhooks/slack"
    click StripeLib "https://github.com/terragon-labs/terragon-oss/blob/main/apps/www/src/lib/stripe.ts"
    click Broadcast "https://github.com/terragon-labs/terragon-oss/tree/main/apps/broadcast"
    click MCP "https://github.com/terragon-labs/terragon-oss/tree/main/packages/mcp-server"
    click Daemon "https://github.com/terragon-labs/terragon-oss/tree/main/packages/daemon"
    click CronJobs "https://github.com/terragon-labs/terragon-oss/tree/main/packages/shared"
    click SandboxSvc "https://github.com/terragon-labs/terragon-oss/tree/main/packages/sandbox"
    click SandboxImg "https://github.com/terragon-labs/terragon-oss/tree/main/packages/sandbox-image"
    click Agent "https://github.com/terragon-labs/terragon-oss/tree/main/packages/agent"
    click Shared "https://github.com/terragon-labs/terragon-oss/tree/main/packages/shared"
    click Shared "https://github.com/terragon-labs/terragon-oss/blob/main/packages/shared/drizzle.config.ts"
    click R2Storage "https://github.com/terragon-labs/terragon-oss/tree/main/packages/r2"

    %% Styles
    classDef presentation fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef api fill:#cce0ff,stroke:#333,stroke-width:1px
    classDef realtime fill:#ccffff,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ccffec,stroke:#333,stroke-width:1px
    classDef execution fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef library fill:#ffffcc,stroke:#333,stroke-width:1px
    classDef data fill:#ffdb99,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px
```
