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"]
        Jira["Jira"]
        GitHub["GitHub"]
        Dashboard["Dashboard"]
    end

    subgraph NATS["NATS JetStream"]
        BuckSubjects["webhooks.buck.*"]
    end

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

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

    subgraph Execution["Execution"]
        EKS["EKS Session Pods"]
        GHA["GitHub Actions"]
    end

    SlackBuck --> BuckSubjects
    Jira --> NATS
    GitHub --> BuckSubjects
    Dashboard --> NATS

    BuckSubjects --> Buck

    Buck --> Shared

    Buck --> EKS
    Buck --> GHA

Three-layer architecture

Layer 1: Entry points

Events arrive from multiple sources, all routed to Buck:

• Slack: @buck bot user with OAuth token and signing secret. Mentions, thread replies, and Block Kit interactions are routed to Buck.
• Jira: Ticket assignments and comments on Buck’s tickets trigger his webhook.
• GitHub App: Issue and PR comments mentioning @bucky route to Buck.
• Dashboard: Web dashboard sessions route to Buck.

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

Layer 2: Agent service

A Go service built on 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).

The platform layer provides NATS event routing, Bedrock LLM access, session indexing, and storage. Buck’s ADK agent definition includes custom tools and prompts.

Layer 3: EKS session pods

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	ECS service 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
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
Proto/RPC	Connect RPC + Buf	Dashboard API, AttachSession bidi streaming, published to BSR