Architecture
Architecture
Section titled “Architecture”This document outlines the overall architecture of the platform. Each component has its own deep-dive document in this folder.
Design principles
Section titled “Design principles”For long-term direction and review tenets, see VISION.md.
- Extensibility - Extend the system without modifying core code. Critical components are accessed through internal interfaces (ComputeStrategy, MemoryStore) so implementations can be swapped.
- Flexibility - This field moves fast. Components should be replaceable as better options emerge.
- Reliability - Long-running agents will fail. The platform must drive every task to a terminal state regardless of what happens to the agent.
- Cost efficiency - Agents burn hours of compute and inference tokens. Cost must be a first-class concern, not an afterthought.
- Security by default - Agents execute code with repo access. Isolated sandboxed environments, fine-grained access control, and least-privilege access are mandatory.
- Observability - Task lifecycle, agent reasoning, tool use, and outcomes should all be visible for monitoring, debugging, and improvement.
How a task runs
Section titled “How a task runs”Each task follows a blueprint - a hybrid workflow that mixes deterministic steps (no LLM, predictable, cheap) with one agentic step (LLM-driven, flexible, expensive).
flowchart LR
A[Admission] --> B[Context hydration]
B --> C[Pre-flight checks]
C --> D[Agent execution]
D --> E[Finalization]
- Admission (deterministic) - The orchestrator validates the request, checks concurrency limits, and loads the repository’s Blueprint configuration.
- Context hydration (deterministic) - The platform fetches external data (GitHub issue body, PR diff, review comments), loads memory from past tasks, resolves attachments (URL fetch with SSRF protection, screening, upload to S3), and assembles the full prompt. For PR tasks, the prompt is screened through Bedrock Guardrails.
- Pre-flight checks (deterministic) - GitHub API reachability and repository access are verified. Doomed tasks fail fast with a clear reason before consuming compute.
- Agent execution (agentic) - The agent runs in an isolated compute environment: clone repo, create branch, edit code, commit, run tests, create PR. The orchestrator polls for completion without blocking.
- Finalization (deterministic) - The orchestrator infers the result (PR created or not), writes memory, updates task status, and releases concurrency.
The orchestrator and agent are deliberately separated. The orchestrator handles everything deterministic (cheap Lambda invocations); the agent handles everything that needs LLM reasoning (expensive compute + tokens). This separation provides reliability (crashed agents don’t leave orphaned state), cost efficiency (bookkeeping doesn’t burn tokens), security (the agent can’t bypass platform invariants), and testability (deterministic steps are unit-tested without LLM calls).
For the full orchestrator design, see ORCHESTRATOR.md. For the API contract, see API_CONTRACT.md.
Deployment boundaries
Section titled “Deployment boundaries”AgentStack keeps the shared Task API, its route integrations, data stores and selected compute backends together. Registry, RegistryApi and the hosted Linear consent page retain their existing nested boundaries. Network ownership is selected by networkTopology:
| Topology | Network ownership | Stack dependencies |
|---|---|---|
inline (default) | AgentVpc and DnsFirewall inside the application stack | Existing parent/nested structure |
split | Separate ${stackName}-network stack | Application imports network references; network has no application references |
The split gives networking an independent deployment lifecycle and reduces the application template’s resource count. It preserves AZ selection, DNS observation mode and security rules. All stacks receive solution attribution and provenance tags, while existing removal policies remain in effect. The split is available for new installations; existing inline-to-split migration is deferred pending a populated rehearsal; see deployment guidance and ADR-023. Live migration has not been validated.
Optional modules (Slack, Linear, Jira, deploy-preview screenshots, Agent Registry, Tool Gateway) are selected by one validated DeploymentFeatures value, which is resolved from abca.deployment.json and the context switches. A disabled module is omitted rather than moved to another stack, because the integrations attach routes to the shared Task API. Synthesis rejects modules that the target Region does not support. See deployment profiles and ADR-024.
Repository onboarding
Section titled “Repository onboarding”Onboarding is CDK-based. Plain repository definitions in cdk/src/blueprints/definitions.ts feed both network egress policy and the Blueprint constructs in the application stack. Each construct writes a RepoConfig record to DynamoDB; the orchestrator reads it at task time. Resolving configuration before stack construction keeps the optional network stack independent of repository resources.
Blueprints configure how the orchestrator executes steps for each repo: compute strategy, model selection, turn limits, GitHub token, and optional custom steps. See REPO_ONBOARDING.md for the full design.
Model selection
Section titled “Model selection”Different tasks and repos may benefit from different models. The model_id field in the Blueprint config allows per-repo overrides:
| Workflow | Suggested model | Model ID (as wired in cdk/src/stacks/agent.ts) | Rationale |
|---|---|---|---|
coding/new-task-v1 | Claude Sonnet 4 | anthropic.claude-sonnet-4-6 | Good balance of quality and cost |
coding/pr-iteration-v1 | Claude Sonnet 4 | anthropic.claude-sonnet-4-6 | Needs to understand review feedback and make code changes |
coding/pr-review-v1 | Claude Haiku 5.5 | anthropic.claude-haiku-5-5 | Fast and cheap - review is read-only analysis |
| Complex/critical repos | Claude Opus 5.5 | anthropic.claude-opus-5-5 | Highest quality; also the platform default when a repo pins nothing |
Cost model
Section titled “Cost model”The dominant cost is Bedrock inference + compute, not infrastructure. Memory, Lambda, DynamoDB, and API Gateway are a small fraction of total cost.
| Scale | Tasks/month | Estimated monthly cost |
|---|---|---|
| Low (1 developer) | 30-60 | $150-500 |
| Medium (small team) | 200-500 | $500-3,000 |
| High (org-wide) | 2,000-5,000 | $5,000-30,000 |
For the full breakdown, see COST_MODEL.md.
Known architectural risks
Section titled “Known architectural risks”Identified via external review (March 2026) and tracked in repository issues.
| Risk | Severity | Status |
|---|---|---|
| Agent vs. orchestrator DynamoDB race - agent writes terminal status without conditional expressions | High | Resolved - ConditionExpression guards added to agent state writes |
| No DLQ on orchestrator async invocation | High | Resolved - durable execution manages retries; CloudWatch alarm added |
| Concurrency counter drift on orchestrator crash | Medium | Resolved - ConcurrencyReconciler Lambda runs every 15 minutes |
| Single NAT Gateway (single AZ failure blocks egress) | Medium | Mitigated - configurable via natGateways prop |
| Dual-language prompt assembly (TypeScript + Python) | Medium | Mitigated - Python path retained only for local/dry-run mode |
What ABCA is not
Section titled “What ABCA is not”ABCA is not a construct library. There is no jsii compilation, no npm publishing, and no stable public API for external consumers. It is a deployable CDK application and a reference architecture for building agent platforms on AWS.
| Audience | How to use ABCA |
|---|---|
| Operators | Deploy the CDK app, onboard repos via Blueprint, submit tasks through CLI/API/webhooks. |
| Platform developers | Extend by implementing internal interfaces (ComputeStrategy, custom step Lambdas). |
| Teams building their own platforms | Study the architecture and design docs. Fork and adapt the patterns. |