Architecture Decision Records
ADRs document significant architectural decisions and their context.
Agents
| ADR | Decision |
|---|---|
| 001 - Background Agents | Kubernetes-native agent execution with sandbox isolation |
| 002 - OpenHands Agent Sandbox | OpenHands as the agent runtime framework |
| 003 - Context Forge | IBM Context Forge as the MCP gateway |
| 004 - Autonomous Agents | Design for fully autonomous agent workflows |
| 005 - Role-Based MCP Access | Role-based access control for MCP tool servers |
| 006 - OIDC Auth MCP Gateway | OAuth 2.1 / OIDC authentication for remote MCP access |
| 007 - Agent Run Orchestration Service | Dedicated service for dispatching and tracking agent job runs |
| 008 - Cluster Patrol Loop Resilience | Crash recovery and per-sweep supervision for cluster_agents loops |
| 009 - Automated Test Generation Bots | Agent-driven test generation pipeline |
| 010 - Recipe-Driven Agent Registry | Goose recipe YAML as the source of truth for agent definitions |
| 011 - Agent MCP v1 Follow-ons | Deferred self-improvement loop scope after v1 MCP surface shipped |
| 011 - Cloudflare Managed OAuth | Cloudflare-managed OAuth for the MCP gateway (duplicate number) |
| 012 - Knowledge Gardener Model Pipeline | Two-tier model pipeline for the knowledge gardener |
| 013 - Knowledge Gardener Gemma4-Only | Single-model pipeline replacement for the gardener |
| 014 - AX + Substrate Agent Runtime | Split-roles adoption of google/ax + agent-substrate, retiring orchestrator + cluster_agents |
| 015 - Temporal as Orchestration Substrate | Adopt Temporal for workflow execution + scheduling; supersedes ADR 014 |
| 016 - NATS as Canonical Event Stream | NATS JetStream as the system-wide event bus between independently-owned components |
| 017 - Domain Event Schema | Event envelope schema + tombstone semantics across the system |
Docs
| ADR | Decision |
|---|---|
| 001 - Static Docs Site | VitePress for architecture documentation |
Networking
| ADR | Decision |
|---|---|
| 001 - Cloudflare Envoy Gateway | Cloudflare Tunnel + Envoy Gateway for ingress |
Platform
| ADR | Decision |
|---|---|
| 001 - Obsidian Vault Monolith Migration | Migrate Obsidian vault into the monolith on TigerFS |
| 002 - CDN-Cached Data Fetching | Public JSON endpoints cache at the Cloudflare edge; clients poll cached |
003 - CDN Cache Rule Scoped to public.jomcgi.dev | Scope CDN cache rule to public.jomcgi.dev (supersedes 002 partially) |
| 004 - Iceberg-on-SeaweedFS Lakehouse with Hot-Swap Quack Serving | Event-sourced lakehouse; NATS → Iceberg → Quack hot-swap; partially evolves 001 |
Security
| ADR | Decision |
|---|---|
| 001 - Bazel Semgrep | Semgrep SAST integrated via Bazel rules |
| 002 - Semgrep Rule Generation via RL | RL-finetuned Qwen 3.5 9B for generating Semgrep rules from CVEs |
| 003 - gVisor RuntimeClass | User-space kernel isolation for agent sandbox pods via runsc |
Services
| ADR | Decision |
|---|---|
| 001 - Discord History Backfill | One-time backfill of Discord channel history into pgvector |
| 002 - Discord Chat Automation | Scheduling, triggers, and proactive posting for the Discord bot |
Tooling
| ADR | Decision |
|---|---|
| 001 - OCI Tool Distribution | Multi-arch OCI image for developer tools, eliminating local Bazel |
| 002 - Service Deployment Tooling | Copier template to scaffold new services, eliminating per-service boilerplate |
| 003 - Spec-First CLI and Skills | OpenAPI as source of truth; CLI commands and Claude skills are derived |