Platform Layer

The platform layer (internal/platform/) provides shared infrastructure. Buck imports platform packages to handle event routing, LLM access, session tracking, storage, and external service integrations.

NATS JetStream

NATS JetStream is the central message bus for all webhook events and session lifecycle updates. Two streams handle different concerns.

WEBHOOKS stream

Property	Value
Subjects	webhooks.>
Retention	WorkQueue
MaxAge	72 hours
MaxMsgs	100,000
Storage	File

All incoming webhook events are published to this stream. The WorkQueue retention policy ensures each message is delivered to exactly one consumer.

SESSIONS stream

Property	Value
Subjects	sessions.>
Retention	Limits
MaxAge	24 hours
MaxMsgsPerSubject	10
Storage	File

Session lifecycle events (status changes, pause/resume notifications) are published here. The Limits retention with per-subject caps keeps a rolling window of recent events per session.

Buck’s consumer

Buck runs a durable consumer that pulls from its namespace within the WEBHOOKS stream:

Property	Value
Consumer name	buck-webhook-workers
Filter subject	webhooks.buck.*
Ack policy	Explicit
Ack wait	10 minutes
Max deliveries	5

Session event consumers use ordered consumers with a sessions.{sessionID}.> filter and DeliverLastPerSubject policy to catch up on the latest state.

Routing

Publishers route events to webhooks.buck.{jobType} where jobType is one of: slack, slack_interaction, jira, session-update, github_comment, dashboard_message.

Buck’s consumer only receives events matching its namespace.

Per-session ordering

A 256-slot sharded mutex (FNV32a hash of session ID) ensures that events for the same session execute sequentially. This prevents race conditions when multiple events arrive for the same conversation in rapid succession, while still allowing high concurrency across different sessions.

Retry and backoff

Failed messages follow a backoff schedule before redelivery:

Attempt	Delay
1	0s (immediate)
2	5s
3	30s
4	2m
5	10m

After 5 failed attempts, the message is terminated and logged for investigation.

Bedrock LLM

The Claude model wrapper (internal/platform/bedrock/) provides LLM access via the AWS Bedrock Converse API:

• Translates between ADK’s genai types and Bedrock’s message/content block types
• Handles consecutive same-role message merging (required by Bedrock)
• Converts tool use and tool result blocks between ADK and Bedrock formats
• Supports multimodal input — images from Slack threads and Jira attachments are passed as Bedrock ImageBlock payloads
• Uses the ECS task role for AWS credentials

The model ID is configurable (Buck defaults to Sonnet).

Session Index

The session index (internal/platform/sessionindex/) maps platform-specific identifiers to canonical UUID sessions. This enables cross-platform session continuity — a conversation started in Slack can continue in Jira or the dashboard.

Key format: buck:{platform}:{identifier}

Pattern	Example
Slack thread	buck:slack:{channelID}:{threadTS}
Jira ticket	buck:jira:{issueKey}
Dashboard session	buck:dashboard:{sessionID}

The index is backed by PostgreSQL with a 30-day expiry on unused entries. Lookups are bidirectional — given a platform key, find the session; given a session ID, find all linked platform keys.

Storage

The storage layer (internal/platform/storage/) provides an S3 image store with CloudFront CDN:

• Re-hosts images from Slack (bot token download), Jira (API download), and runner uploads
• Returns permanent CloudFront URLs when CLOUDFRONT_DOMAIN is configured
• Falls back to pre-signed S3 GET URLs (7-day TTL) without CloudFront
• Persists images referenced in conversations

Platform clients

API clients used by Buck:

Client	Path	Auth
Jira	internal/platform/jira/	REST API v3, basic auth (email + API token)
Slack	internal/platform/slack/	Web API + Block Kit, bot OAuth token
GitHub	internal/platform/github/	App installation tokens
Celestials	internal/platform/celestials/	Internal service, no auth