Architecture

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

System diagram

┌─────────────────────────────────────────────────────┐
│  Entry Points                                       │
│  Slack @mention │ Jira assign │ GitHub @bucky       │
└────────┬────────┴──────┬──────┴──────┬──────────────┘
         │               │             │
         ▼               ▼             ▼
┌─────────────────────────────────────────────────────┐
│  Agent Service (Go + Google ADK)                    │
│  - LLM reasoning (Claude via Bedrock)               │
│  - MCP tools (Sourcegraph, Grafana)                 │
│  - Custom tools (create sessions, dispatch work)     │
│  - Session continuity across platforms              │
└────────────────────┬────────────────────────────────┘
                     │ repository_dispatch
                     ▼
┌─────────────────────────────────────────────────────┐
│  GitHub Actions Workflows                           │
│  - Thin caller workflows (in target repos)          │
│  - Reusable shared workflows (in buck-bronson)      │
│  - Composite actions (execute, review, setup)       │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────┐
│  Claude Code Runner                                 │
│  - Docker container (ubuntu + gh CLI)               │
│  - Claude AI via AWS Bedrock                        │
│  - MCP plugins (Sourcegraph, Grafana, PostHog)      │
│  - Dev tools (Node.js, Go, Playwright)              │
└─────────────────────────────────────────────────────┘

Three-layer architecture

Layer 1: Entry points

Events arrive from Slack (@bucky mentions, thread replies, Block Kit interactions), Jira (ticket assignments, comments), GitHub (issue comments, PR lifecycle), or the web dashboard. Each entry point has a dedicated webhook handler that verifies authenticity and routes events to the agent.

Layer 2: Agent service

A Go service built on Google ADK. The agent uses Claude (via AWS Bedrock Converse API) to reason about incoming events. It has access to:

• MCP toolsets: Sourcegraph for code search, Grafana for observability
• Custom function tools: Create Jira tickets, create dashboard sessions, dispatch Claude sessions, post to Slack/Jira, post to the feed channel
• Session management: Cross-platform session continuity via SessionIndex (maps slack:channel:ts, jira:issueKey, dashboard:session_id to canonical UUIDs)

The agent processes events asynchronously via a goroutine worker pool (10 workers) with panic recovery.

Layer 3: GitHub Actions workflows

When the agent dispatches work, it fires a repository_dispatch event to the target repo. The thin caller workflow delegates to shared reusable workflows in buck-bronson, which:

1. Pull the Claude runner Docker image from ECR
2. Resolve the preset to determine dev environment and plugins
3. Set up the dev environment (Node.js, Go, Playwright as needed)
4. Run Claude Code with the task prompt, MCP plugins, and dev tools

Callback loop

When a Claude session completes, the report-session-outcome action POSTs results back to the agent via an OIDC-authenticated callback. 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).

Key infrastructure

Component	Technology	Details
Agent runtime	Go + Google ADK	ECS deployment via FSD
LLM	Claude via AWS Bedrock	Custom model.LLM wrapper for Converse API
Session storage	Aurora PostgreSQL	GORM auto-migration, 30-day expiry
Image storage	S3 + CloudFront	Re-hosted images from Slack/Jira/runners
CI/CD runners	Docker (Ubuntu + gh CLI)	ECR-hosted, pulled fresh each run
Observability	OpenTelemetry + Prometheus + PostHog	Custom bucky.* metrics, LLM analytics
Proto/RPC	Connect RPC + Buf	Dashboard API, published to Buf Schema Registry