Architecture
This page is a system-level overview of how the platform's components fit together. It is intentionally high-level — enough to orient new contributors and evaluators without descending into per-component internals.
For the founding principles and lifecycle that motivate this architecture, see Vision. Deeper sequence diagrams for individual flows (agent invocation, OAuth handshake, WebSocket lifecycle) are intentionally out of scope here and will follow as separate documents.
The architecture is presented as two complementary top-to-bottom views:
- The request path — what happens when a signed-in user clicks a button in the UI.
- The agent runtime — what happens after the request path triggers an agent job.
Together they cover every component the platform is built from. For the complete list of AWS services the Terraform stack provisions or calls, see AWS services.
Request path
The synchronous, user-facing path. From the browser down to the data stores.
flowchart TB
subgraph Client["Browser"]
SPA["React 19 SPA<br/>(Vite, Yjs client)"]
end
subgraph Edge["Frontend"]
CF["CloudFront distribution"]
S3F[("S3 bucket")]
CF -->|default S3 origin| S3F
end
subgraph APIs["Backend APIs"]
REST["API Gateway REST"]
WS["API Gateway WebSocket"]
YJS["ECS Fargate Yjs server<br/>(behind internal ALB)"]
end
subgraph Lambdas["Lambda functions"]
direction LR
CRUD["CRUD handlers<br/>(projects, sprints, requirements,<br/>user-stories, tasks, reviews, …)"]
GIT["GitHub & tracker integration<br/>(github, trackers)"]
AGCTL["Agent control plane<br/>(intents, questions)<br/>+ agents (v1 history, admin)"]
WSL["WebSocket lifecycle<br/>(authorizer, connection, message)"]
end
subgraph Data["Data stores"]
direction LR
NEP[("Neptune<br/>(graph)")]
DDB[("DynamoDB tables")]
S3[("S3 buckets")]
end
SPA -->|HTTPS / WSS| CF
CF -->|/api/*| REST
CF -->|/ws| WS
CF -->|/yjs/* via VPC Origin| YJS
REST --> CRUD
REST --> GIT
REST --> AGCTL
WS --> WSL
CRUD -->|Gremlin / SigV4| NEP
GIT --> DDB
AGCTL --> NEP
WSL --> DDB
Components
Browser. A React 19 single-page application built with Vite. It uses AWS Amplify for direct Cognito SRP login and, when enabled, Cognito-hosted OIDC/SAML federation. It calls the REST API with the resulting Cognito JWT as a Bearer token and opens two distinct WebSocket connections: one to the application WebSocket API for agent progress and notifications, and one to the Yjs collaboration server for real-time spec editing.
CloudFront. A single distribution multiplexes all client traffic over one domain. The default behavior serves the SPA from a private S3 bucket via Origin Access Control. /api/* routes to the REST API Gateway. /ws routes to the WebSocket API Gateway. /yjs/* routes through a CloudFront VPC Origin to an internal ALB sitting in front of the Yjs collaboration server. Routing through one distribution lets every backend share a single domain and a single TLS certificate, and keeps the SPA's API and WebSocket calls same-origin.
Custom domain (optional). Because that one distribution is the only public application entry point, serving the platform on a custom hostname requires one ACM certificate in us-east-1 and one distribution change — nothing else. There is no API Gateway custom domain (browsers never address it directly) and no certificate on the internal ALB (HTTP-only behind the VPC Origin). The Cognito managed-login domain is a separate federation endpoint; it redirects authentication traffic and never serves the application.
Whichever hostname is canonical becomes the single source for the OAuth redirect URIs, the CORS allowlists and the frontend's endpoint URLs. Those last ones are inlined into the bundle at build time, which is why changing the domain needs a frontend redeploy and not just an apply. The CloudFront domain stays in the CORS allowlist alongside any custom hostname, so enabling a domain does not break bundles that are already loaded. See Setup.
Cognito User Pool. Admin-only local sign-up, optional TOTP MFA, and federation to multiple OIDC/SAML providers. Cognito is always the broker and sole JWT issuer. A pre-token trigger replaces federated users' Cognito groups with roles mapped from their external claim; local users continue to use Cognito groups. platform-admin gates the Admin page, workflow/block authoring, and user management (the legacy member, approver, owner groups remain for existing installs; day-to-day space access is governed by per-space membership roles). The REST API Gateway uses a built-in Cognito authorizer, the WebSocket API Gateway uses a custom Lambda authorizer, and the Yjs server verifies the same token in-process on WebSocket upgrade. See Enterprise SSO for the trust boundaries and role semantics.
API Gateway REST. Fronts the platform's CRUD and orchestration endpoints. Resources mirror the graph model: spaces (/projects), intents, workflows, sprints, requirements, user stories, tasks, code files, reviews, questions, timeline events, plus integration endpoints for GitHub OAuth, trackers, and the agent control plane. CORS headers are injected on gateway-level 4xx/5xx responses so the SPA always sees them.
API Gateway WebSocket. A separate API for application-level real-time messages — agent progress, notifications, presence pings. Routes are $connect (custom Cognito JWT authorizer Lambda), $disconnect, $default, sync, and notification. Connection state lives in a DynamoDB table indexed by user ID and document ID; server-to-client pushes use execute-api:ManageConnections.
Yjs server. A long-running Node container on ECS Fargate that handles real-time collaborative editing of specs. It is a separate fabric from the application WebSocket API, for reasons explained below.
On every WebSocket upgrade the Yjs server verifies the Cognito JWT and a short-lived HMAC-signed scope token, bound to that identity and the requested intent/sprint/space. It exchanges CRDT sync (type 0) and awareness (type 1) messages; a small persistence extension (type 4) confirms checkpoint completion. Unknown document-name formats are rejected. Sockets close at scope-token expiry (4401), and clients reconnect with jitter and fresh authorization, so a removed member can retain an existing session for at most the remaining token life.
Standalone mode keeps one process-local document owner and relies on browser REST autosaves for business-data persistence. Opt-in cluster mode distributes document owners across ECS workers using DynamoDB membership and fenced leases, forwards sockets between workers, and recovers binary Yjs checkpoints from S3 before synchronization. Workers checkpoint before idle eviction or ownership transfer. Manual sizing and automatic scaling are configured through yjs_scaling; a single hot document still has one owner. See Yjs operations for limits, rollout, recovery, metrics, load testing, and snapshot retention.
This is why the Yjs server is on ECS rather than Lambda or API Gateway WebSocket: a CRDT relay needs persistent in-memory state shared across all clients editing the same document, which is incompatible with Lambda's stateless-per-invocation execution model. Internal ALB ingress is restricted to CloudFront's managed prefix list, so the server is not directly reachable from the internet.
Realtime doc-secret rotation runbook. The HMAC secret behind the realtime scope tokens lives in SSM Parameter Store at /{project}/{env}/realtime-doc-secret and is read by three consumers: the discussions Lambda (issuer), the ws-connection Lambda, and the Yjs ECS task. To rotate it:
- Taint and re-apply the Terraform
random_password.realtime_doc_secret(or write a new SecureString value directly). - Force new ECS deployments of the Yjs service so the task re-reads the secret (
aws ecs update-service --force-new-deployment). - Publish a new version of the
ws-connectionanddiscussionsLambdas (any redeploy works — the secret is cached per container and re-fetched on cold start). - Expect up to ten minutes of reconnect churn: tokens signed with the old secret fail verification, clients transparently fetch fresh ones. No data is at risk — the secret only gates realtime channel membership; durable writes are independently authorized in the REST layer.
Lambda functions. All business logic lives in Lambda. CRUD handlers map one-to-one onto graph artifacts and write to Neptune over Gremlin with SigV4. The GitHub and tracker handlers manage OAuth flows and read repository data on behalf of users. The agent control plane (intents) creates, starts, and rewinds intents, answers human gates, and hands execution to the agent runtime; the questions Lambda serves recorded agent Q&A; the agents Lambda serves read-only v1 agent history plus the shared admin surface — GET/PUT /agents/settings (Bedrock bearer token, Kiro API key, default CLI models, all SSM-backed) and GET /agents/capabilities (model discovery via the AgentCore runtime). The WebSocket lifecycle Lambdas (authorizer, connection, message) authorize, register, and route messages on the application WebSocket API.
Data stores. Neptune holds the structured graph: requirements, user stories, tasks, code files, reviews, agent runs, intents and their artifacts, discussion threads and their messages, and the relationships between them. See the data model for the core graph and DynamoDB models. DynamoDB holds authoritative space membership and append-only permission audit history, alongside operational state — WebSocket connections, agent questions and outputs (v1 history), v2 execution process state (stages, gates, outputs, metrics), building blocks and workflows, sessions, notifications, Yjs document metadata, discussion guards/locks and per-user read cursors, and per-user OAuth connections. S3 holds the SPA bundle, building-block bodies and scripts, custom rules, intent attachments and reports, agent code snapshots, and access logs.
Not shown. Secrets Manager stores platform-wide provider OAuth application credentials and the optional GitHub App private key. SSM Parameter Store stores provider tokens, GitHub App configuration, and agent authentication material. Spaces bind repository access through GitHub OAuth or GitHub App installations, GitLab OAuth, or Bitbucket OAuth. GitHub Issues, GitLab Issues, and Jira Cloud provide tracker imports and delivery comments; GitHub and GitLab issues also close after all final delivery requests merge. These integrations are omitted from the diagram to keep it readable; see Git and Tracker Integration for their authentication and delivery behavior.
Agent runtime
The asynchronous path. What happens after the user starts an intent from the UI.
flowchart TB
INT["intents Lambda<br/>(create / start / rewind,<br/>gate answers)"]
ORCH["v2-orchestrator<br/>(durable Lambda)"]
AC["Bedrock AgentCore runtime<br/>(ARM64 container: headless CLI<br/>+ stdio MCP server)"]
subgraph Outputs["Agent outputs"]
direction LR
NEP[("Neptune<br/>graph artifacts")]
DDB[("DynamoDB<br/>process state: stages,<br/>gates, outputs, metrics")]
end
GITP["Git providers<br/>(GitHub / GitLab)"]
WS["API Gateway WebSocket"]
SPA["Browser SPA"]
INT -->|async Invoke on start| ORCH
INT -->|scheduled unit-PR reconciliation| GITP
ORCH -->|dispatch stage<br/>as background job| AC
AC -.->|durable callback:<br/>stage verdict| ORCH
INT -.->|durable callback:<br/>gate answered| ORCH
AC -->|MCP graph writes| NEP
AC --> DDB
ORCH --> DDB
ORCH -->|open PRs| GITP
AC -->|direct fan-out| WS
ORCH -->|direct fan-out| WS
WS --> SPA
Components
Agent control plane. The intents Lambda shown in diagram 1. An intent is the unit of agent work: a title and prompt scoped to a space. On start, the Lambda compiles the space's workflow into an execution plan, snapshots space settings, and asynchronously invokes the durable orchestrator. It also owns the human-gate answer endpoint: answering a parked gate sends a durable callback (SendDurableExecutionCallbackSuccess) that resumes the suspended run.
Durable orchestrator. v2-orchestrator is a Lambda-based durable execution that drives one intent end to end. It walks the plan's stages in order; parallel construction sections fan out into per-unit lanes over the methodology's unit-of-work DAG, scheduled deterministically (no LLM dispatcher). Stages are invoked asynchronously: the orchestrator creates a durable callback, a short dispatch call starts the stage as a background job in the AgentCore container, and the execution suspends at zero compute until the container completes the callback with the stage verdict. This matters because a stage regularly outlives both the Lambda timeout and AgentCore's synchronous request window.
AgentCore runtime. A Bedrock AgentCore runtime running an ARM64 container image, with a dedicated microVM and filesystem per session. Each stage spawns the headless CLI selected for that intent (Kiro, Claude Code, OpenCode, or Codex), whose only interface to the application is a stdio MCP server: business reads and writes go to Neptune as typed, provenance-stamped artifacts; questions, outputs, and metrics go to DynamoDB. The workspace holds the space's real git checkout, but all git operations — branch, commit, push, merge — are engine-owned and deterministic; the agent never runs git and never holds source-control credentials. After each stage, deterministic sensors verify the output before the run advances.
Built-in MCP through AgentCore Gateway (opt-in). With enable_mcp_gateway = true (requires network_mode = "VPC"), the runtime no longer starts the MCP server in the agent's microVM. It starts a stdio proxy that registers the same tools and forwards each call, SigV4-signed, to an AgentCore Gateway (AWS_IAM inbound) whose Lambda target (mcp-tools) runs the same graph and process handlers. The orchestrator and discussions Lambdas (and, with enable_engine_data, the intents Lambda) sign a short ES256 grant with a KMS key that only they may use; it names the space, intent, execution, stage lane and leg, mode and release-policy digest of the invocation. The runtime relays the grant without exposing it to command handlers or the agent CLI. A Gateway REQUEST interceptor (mcp-interceptor Lambda) verifies it on every request, initialize and tools/list included: it rejects session context outside the grant, re-reads the execution and stage row (a finished, cancelled or superseded leg is denied immediately) and enforces the role's tool catalog before the target is invoked. A denied request is answered by the Gateway with a JSON-RPC error and never reaches mcp-tools; the runtime proxy shows the agent the same denial text as the local server. An allowed request is forwarded with its original body and only the context the interceptor derived (x-aidlc-context, plus the signed release policy in x-aidlc-context-policy); mcp-tools validates that context strictly and acts on it, still parsing arguments, pinning a lane to its unit and leaving every process-table write behind its transactional ownership checks. The RESPONSE interceptor filters tools/list with the same rule. Every allow, deny and failure is logged with its scope by the interceptor, and every tool outcome by mcp-tools. Without a grant the runtime refuses to start the MCP rather than falling back to the local server. This changes where the built-in tools run and how they are authorized; it does not yet remove the runtime role's own data permissions, which other runtime commands still use. Executions started before the flag have no grants and would fail the next time they invoke the runtime, so deploy-terraform.sh refuses a plan that switches the runtime to the Gateway while any execution is started, running or parked, and lists them. Stop starting intents until the deployment has succeeded (retries included), let running executions park or finish, cancel the parked and queued ones, apply, then rewind each to its current stage (its first stage if it had not reached one), which relaunches it with grants (AIDLC_ALLOW_ACTIVE_EXECUTIONS=1 applies anyway). The check is in the deploy script; a direct terraform apply skips it.
Gateway trust boundary. The Gateway accepts calls signed with the runtime role (AWS_IAM), and its interceptor admits only those that also carry a valid grant. These are two checks, not two independent barriers: code in the runtime's microVM can read both the role's credentials and the grant. What the grant adds is that the runtime cannot widen its own scope: it cannot mint a grant for another space, execution or stage, and a superseded leg or run is refused on the next call. The tools Lambda does not re-verify the grant; it trusts the injected context because of two properties Terraform enforces and tests: only the Gateway role may invoke mcp-tools and the interceptor (the runtime role has no lambda:InvokeFunction on either), and the aidlc target forwards no request header except the two context headers, which the interceptor replaces on every request it allows (it never copies caller headers, Authorization and AWS tokens included). The interceptor is configured whenever the Gateway exists. The limits are explicit: all agents of a stage share one grant; the role inside the stage (author, reviewer, reader), the persona, attempt metadata and the checkpoint and question flags are asserted by the runtime in the unsigned session header and are marked as asserted in the context, and they never reach beyond the granted stage, lane and leg; nothing binds a grant to the caller that presents it; and the live checks are preflight, so a leg superseded after a request is admitted is refused by the process table's ownership checks on its writes, while graph writes made by an already-admitted call have no such fence. The native CUSTOM_JWT authorizer would replace only the Gateway's inbound check: the interceptor and its live checks stay.
Engine process state through engine-data (opt-in). With enable_engine_data = true (requires enable_mcp_gateway), the engine commands that run in the runtime (stage runs, workspace init, derivation, checkpoints, PR records, compose, quorum edits) read and write their process state and the knowledge graph through the engine-data Lambda instead of the process table and Neptune. Every one of those commands now receives a grant from the control plane (a stage run its stage grant, the others an execution-scoped grant, which is signed only while engine data is enabled), and each store call is checked against it: the method must be on a closed allowlist and match its argument schema, and the execution it names must be the grant's and belong to the grant's space and intent. There is no status check, so a grant keeps acting on its own execution only. Graph access uses named operations (graph-writer methods and a few composite operations such as artifact edits and versioning), never a generic query; every artifact, unit, stage or discussion id an operation names must belong to the grant's intent or execution. With engine-data enabled, inspect's cleanup and drop maintenance is refused. The same Lambda also serves the read-only methodology catalog (block bodies, scripts, release manifests and the conductor, by verified key only), the execution's own custom rules and intent attachments (named by filename or attachment id; keys and versions come from the execution record), checkpoint rule-version pins (a stored checkpoint may only reference version-pinned rules the execution record lists for the grant's space), and intent broadcasts (recipients are queried server-side from the grant's intent). Executions started before enable_engine_data receive no engine-data grant, so deploy-terraform.sh refuses a plan that switches the runtime to engine-data while any execution is started, running or parked, as it does for the Gateway. It refuses turning enable_engine_data off under the same conditions and with the same override, because the apply destroys the engine-data Lambda while a warm runtime session keeps the runtime version it started with (up to the 8 h maximum lifetime) and would keep calling it. To turn it off, drain the executions as for enabling, apply, then stop the remaining intent runtime sessions or wait until they idle out or reach their maximum lifetime.
The runtime role is unchanged in this release: it still holds its Neptune, DynamoDB, S3, websocket and MCP-secret SSM permissions. Credentials, MCP secrets and provider review operations move in a later release, after which those permissions are removed.
Human gates. When an agent calls the ask_question MCP tool — or the orchestrator opens an engine gate (walking-skeleton review, batch review, halt-and-ask) — the run parks on a durable callback. The question renders in the UI; the user's answer flows through the intents Lambda, which completes the callback and resumes the run exactly where it parked. No polling, no queue.
Pull requests. For PR-per-unit delivery, the orchestrator persists one durable callback when a unit is ready for review. A scheduled intents maintenance pass checks GitHub or GitLab while the durable execution remains suspended, waking it only when the PR merges or closes, a reviewed branch moves, or authenticated feedback is queued. The sparse process-table maintenance index also lets the same pass detect terminal durable executions before their local expiry. After every unit and shared stage succeeds, the orchestrator opens the final intent-to-base pull request through the same provider layer.
Auth. Bedrock and Kiro credentials live in SSM Parameter Store at personal, space, and platform scopes with personal > space > platform precedence. The control plane resolves the starting user's effective source and stores only an opaque binding with the intent; AgentCore reads that bound SecureString into an invocation-local environment, so long-lived sessions do not retain another user's secret. The binding never falls through after start: rotation at the same path is visible on the next invocation, while removal or invalidation produces an actionable credential failure. The runtime's IAM role deliberately has no Bedrock model-invocation permissions, so token auth is the only path. Git pushes use the starting user's provider token, injected only inside the engine's push/fetch windows and scrubbed from the checkout otherwise. None of these auth lookups appear in the diagram.
Realtime. Every relevant process write is persisted to DynamoDB and then broadcast directly to the intent's WebSocket channel (intent:<intentId>): both the container and the orchestrator fan out through the shared connection registry. DynamoDB is the source of truth; the broadcast is best-effort and never blocks a stage. There is no event bus in this path, which is why the application WebSocket fabric exists separately from the Yjs one.
Retired v1 runtime
Earlier releases ran agents on an ECS Fargate worker pool dispatched through a DynamoDB mailbox, with an EventBridge bus and a notify Lambda fanning agent events out to the browser. That runtime has been removed. The v1 sprint lifecycle is now read-only: no new sprints, agent runs, or edits — but its history stays viewable, including sprints, requirements, stories, tasks, code files, reviews, Q&A, agent transcripts, and discussions. The agents Lambda and the agent-questions / agent-outputs DynamoDB tables remain to serve that history.
Request to review: end-to-end data flow
The two diagrams above are static. The platform's working flow takes a request from a human user through to a reviewable result in five steps.
- Request. A signed-in user opens a space in the SPA and creates an intent with a title and prompt, then starts it. The
intentsLambda persists the intent, compiles the workflow plan, and asynchronously invokes the durable orchestrator. - Workspace. The orchestrator's first step checks the space's repositories out into the runtime workspace, creates the
Intentvertex in Neptune, and creates the intent branch. - Stages and gates. The orchestrator walks the plan. Each stage runs a headless CLI in the AgentCore runtime that reads prior artifacts and writes new ones to the graph through MCP; clarifying questions and approval gates park the run on durable callbacks until a human answers in the UI, then the run resumes where it left off.
- Parallel construction. Construction stages fan out into per-unit lanes: each lane runs in its own AgentCore session on its own branch, deterministic sensors verify every stage, and the engine merges completed lanes back into the intent branch with serialized
--no-ffmerges. Progress streams to the browser over the direct WebSocket fan-out throughout. - Output and review. When the execution succeeds, the orchestrator opens a pull request from the intent branch onto the base branch via the shared git providers. Humans review the PR alongside the intent's artifacts, outputs, and metrics in the UI.