Architecture

This page covers the full technical architecture. For a higher-level overview, see How Bucky Works.

System diagram

graph TD
    subgraph Entry Points
        SlackBuck["Slack @buck"]
        SlackDolly["Slack @dolly"]
        SlackPearl["Slack @pearl"]
        Jira["Jira"]
        GitHub["GitHub"]
        Dashboard["Dashboard"]
    end

    subgraph NATS["NATS JetStream"]
        BuckSubjects["webhooks.buck.*"]
        DollySubjects["webhooks.dolly.*"]
        PearlSubjects["webhooks.pearl.*"]
    end

    subgraph Buck["Buck (ECS)"]
        BuckADK["ADK Agent + Tools"]
    end

    subgraph Dolly["Dolly (ECS)"]
        DollyADK["ADK Agent + Tools"]
    end

    subgraph Pearl["Pearl (ECS)"]
        PearlADK["ADK Agent + Tools"]
    end

    subgraph Shared["Shared Infrastructure"]
        Bedrock["Bedrock Claude"]
        Aurora["Aurora PostgreSQL"]
        S3["S3"]
    end

    subgraph BuckOnly["Buck Only"]
        EKS["EKS Session Pods"]
        GHA["GitHub Actions"]
    end

    SlackBuck --> BuckSubjects
    SlackDolly --> DollySubjects
    SlackPearl --> PearlSubjects
    Jira --> NATS
    GitHub --> BuckSubjects
    Dashboard --> NATS

    BuckSubjects --> Buck
    DollySubjects --> Dolly
    PearlSubjects --> Pearl

    Buck --> Shared
    Dolly --> Shared
    Pearl --> Shared

    Buck --> EKS
    Buck --> GHA

Three-layer architecture

Layer 1: Entry points

Events arrive from multiple sources, each routed to the appropriate agent:

• Slack: Three bot users — @buck, @dolly, and @pearl — each with dedicated OAuth tokens and signing secrets. Mentions, thread replies, and Block Kit interactions are routed to the corresponding agent.
• Jira: Buck is the only agent assignable in Jira. Ticket assignments and comments on Buck’s tickets trigger his webhook. Dolly and Pearl interact with Jira programmatically (creating tickets, commenting) but are triggered via Slack.
• GitHub App: Issue and PR comments mentioning @bucky route to Buck.
• Dashboard: Web dashboard sessions route to the appropriate agent.

Each entry point has a shared webhook handler (platform layer) that verifies authenticity and publishes events to NATS JetStream.

Layer 2: Agent services

Three Go services built on a shared platform with Google ADK:

• Buck — Engineering agent. Dispatches Claude sessions to EKS pods, creates Jira tickets, manages code review workflows. Default model is configurable (Claude Sonnet by default).
• Dolly — Project management agent. Decomposes epics into tickets, generates reports, searches Confluence and Google Drive. Default model is Claude Opus.
• Pearl — Design agent. Generates components, reviews designs, manages snippets and design languages, integrates with Figma. Default model is Claude Opus.

All three share the platform layer for NATS event routing, Bedrock LLM access, session indexing, and storage. Each agent has its own ADK agent definition with custom tools and prompts.

Layer 3: EKS session pods (Buck only)

When Buck dispatches implementation or planning work, it creates an ephemeral Kubernetes Job via PodOrchestrator. Each pod runs the base image (buck-bronson-claude-base) or a custom image extending it, with:

1. Target repo(s) cloned into the workspace (natively multi-repo)
2. MCP plugins configured (Sourcegraph, Grafana, PostHog, Playwright)
3. AWS credentials forwarded for Bedrock access
4. Pod-bound JWT for authenticating callbacks to the agent

Sessions run inside a tmux session, enabling interactive terminal access from the dashboard via WebSocket tunneling.

PR automation (GitHub Actions)

Pull request workflows remain on GitHub Actions. Target repos install thin caller workflows that delegate to shared reusable workflows in buck-bronson:

• bucky-code-review.yml: Automatic AI code review when PRs are opened or updated

Session lifecycle

When a session completes, the pod reports results to the agent’s runner API using pod-bound JWT authentication. The agent resumes reasoning in the original session and can chain follow-up actions (e.g., post results to Jira, notify in Slack, dispatch another session).

Sessions can also pause mid-work — the pod saves workspace and conversation state to S3 — and resume later with follow-up instructions. The dashboard receives real-time pod status updates (pending, running, succeeded, failed) via SSE.

Key infrastructure

Component	Technology	Details
Agent runtime	Go + Google ADK	Three ECS services via FSD, shared platform layer
LLM	Claude via AWS Bedrock	Custom model.LLM wrapper for Converse API
Message bus	NATS JetStream	Durable webhook queue + session event streaming
Session pods	Ephemeral EKS Jobs	buck-bronson-claude-base image (or custom), bucky-sessions namespace (Buck only)
PR automation	GitHub Actions	Code review (thin caller + shared reusable workflow)
Session storage	Aurora PostgreSQL	GORM auto-migration, 30-day expiry
State persistence	S3	Pause/resume state archives + terminal scrollback
Image storage	S3 + CloudFront	Re-hosted images from Slack/Jira/runners
Observability	OpenTelemetry + Prometheus + PostHog	Custom metrics, LLM analytics across all agents
Proto/RPC	Connect RPC + Buf	Dashboard API, AttachSession bidi streaming, published to BSR
Knowledge	Confluence, Google Drive	Dolly uses for team documentation and project context
Design	Figma	Pearl integrates for design file access and token extraction