How terragon-labs/terragon-oss works
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: