# AWP Canonical Architecture Baseline **Date:** 2026-08-19 **Status:** **Canonical architecture decision baseline — architecture review complete** **Purpose:** Provide one current architecture snapshot after the planning review, FOSS minimalism pass, day-one ARC decision, and three-plane deployment-topology decision. ## 1. Authority and document hierarchy Use this order when architecture documents disagree: ```text owner intent docs/VISION.md current architecture decisions this file AWP-DEPLOYMENT-TOPOLOGY.md AWP-FOSS-DECISIONS.md implementation readiness STEP-0-PREPARATION-DEPENDENCIES.md implementation source of truth, once created docs/specs/** ``` `AWP-PLANNING-ARCHITECTURE-REVIEW.md` is the completed review/evidence document that produced this baseline. It contains historical recommendations and open questions that have since been resolved. It is no longer the place to infer current provider choices when this baseline or the binding FOSS decision register says otherwise. The broad FOSS research documents remain evidence/history. `AWP-FOSS-DECISIONS.md` is authoritative for current provider dispositions. ## 2. Product classification and ownership law AWP is an **Agentic Software Delivery Control Plane**. AWP owns: ```text intent planning and work semantics policy and final authorization authoritative lifecycle state relationships and provenance configuration semantics approvals and decisions CI/CD meaning and progression business events and audit operator UX ``` Providers/adapters own replaceable mechanics. Coding agents write, review, test and fix code. They do not own workspace lifecycle, publication, merge progression, release/deployment progression, approval disposition, or product policy. ## 3. Day-one runtime topology The architecture is intentionally asymmetric: ```text INTERNET | v EDGE / GATEWAY PLANE +----------------------------+ | Web UI / static assets | | public Hono API gateway | | auth/session ingress | | webhooks | | realtime fan-out | +-------------+--------------+ | v AWP CONTROL PLANE +----------------------------+ | application/domain | | final authorization/policy | | DBOS durable workflows | | business events / audit | | PostgreSQL / Drizzle | +-------------+--------------+ | v EXECUTION PLANE +----------------------------+ | K3s / Kubernetes | | Agents / Workspaces | | Fabro | | GitHub Actions + ARC | | CI workloads | +----------------------------+ ``` This is a logical and code/deployment boundary from day 1 even if all three planes are initially hosted in one K3s cluster. The gateway is designed for cheap portability. The control plane is a normal long-lived Node/PostgreSQL application. The execution plane is deliberately Kubernetes-specific. ## 4. Code and dependency boundaries Initial repository shape should preserve these deployable targets and dependency directions: ```text apps/ gateway/ # Hono; public/edge-safe transport control-plane/ # Hono on Node; DBOS; domain/application/providers web/ # React/Astryx packages/ contracts/ # runtime-neutral DTO/schema/event contracts domain/ # product semantics application/ # commands/queries/use cases providers/ # provider interfaces adapters/ # provider implementations, where shared placement makes sense ``` Exact names may change. The dependency rules may not: ```text gateway -> contracts web -> contracts control -> contracts + application + domain + providers control adapters -> PostgreSQL / DBOS / Kubernetes / GitHub / Fabro / Subrouter gateway -X-> DBOS gateway -X-> Kubernetes gateway -X-> control-plane repositories domain -X-> Hono domain -X-> Cloudflare/vendor edge APIs domain -X-> Kubernetes/GitHub/Fabro SDK types ``` Hono is a transport, not the AWP module/container architecture. ## 5. Selected small baseline ### Control plane ```text TypeScript / Node / ESM / pnpm Hono PostgreSQL + Drizzle DBOS TypeScript library @platform-modules/* where accepted ``` Exact runtime/package versions are dependency/ADR pins, not domain architecture. ### UI ```text React Astryx Pragmatic Drag and Drop React Flow Chart.js ``` Existing `deck-ui` is reference/source only. Anything ported becomes AWP-owned and AWP-named. ### Execution plane ```text K3s / Kubernetes native Pod/PVC/ServiceAccount/NetworkPolicy WorkspaceProvider gVisor RuntimeClass for untrusted AgentRuns where compatible Development Container standard/CLI + project-native environment definitions Fabro as primary FactoryProvider ACP where supported, with native AgentProvider escape hatches ``` ### CI ```text GitHub Actions = initial CI provider ARC on K3s = day-one runner infrastructure ephemeral runner pods = default runner lifecycle AWP CIExecution / CIResult = authoritative product representation ``` Project `.github/workflows/*` remain project-owned. Direct checks in AgentRun workspaces are preflight/ad-hoc mechanics, not a replacement CI control plane. ### Delivery/evidence ```text Helm-rendered manifests + Kubernetes Server-Side Apply Trivy Cosign ORAS CloudEvents at external event boundaries OpenTelemetry-compatible instrumentation/export ``` Flux is optional only when a deployment requires continuous GitOps reconciliation independent of AWP. ### Externalized stateful services ```text normal PostgreSQL endpoint external S3-compatible object storage GHCR initially ``` Self-host profiles are optional: CloudNativePG+Barman for in-Kubernetes production Postgres, SeaweedFS for local S3-compatible storage, zot for local OCI registry. ## 6. Domain and primitive model A concept becomes a first-class primitive when it has meaningful independent identity, state/lifecycle, relationships, policy/configuration, and events. Core families: ```text Product/work Project, Repository, Plan, WorkItem, Wave, Phase, Task Execution Workflow, FactoryRun, Agent, AgentRun, Workspace, Attempt AI/provider Provider, Model, Account, AccountSelectionPolicy Source/change ChangeSet, Commit, Review CI CIExecution, CIExecutionPlan, Check, CIInvariant, CIResult Delivery Artifact, Release, Environment, Deployment Infrastructure Cluster, Machine, MachineCapability, Workload, PlacementDecision Governance Policy, Approval, Decision, Principal, Role, Permission, CredentialReference Operations Incident, Resolver, ResolutionAttempt, ResolutionRecipe Communication CommunicationEndpoint, Notification ``` Provider-native IDs never become the sole identity of an AWP primitive. ## 7. Authoritative state and transactions PostgreSQL is authoritative for AWP product state. A lifecycle-changing command follows the pattern: ```text load authoritative state -> authenticate/resolve Principal -> authorize -> evaluate guard/policy -> write new domain state -> write required business event/audit/outbox atomically -> commit ``` Backend lifecycle state uses small typed AWP transition tables/functions. XState is not the authoritative backend model. Kubernetes state, GitHub check state, Fabro state and provider state are observed/external mechanics that are normalized into AWP state. ## 8. Durable orchestration `DurableWorkflowProvider` defaults to **DBOS + PostgreSQL**. DBOS owns workflow checkpoint/recovery mechanics. AWP owns workflow meaning, authorization, domain IDs, lifecycle state, business events, audit and provider coordination. Do not create a second general durable-workflow authority beside DBOS. Re-open the provider only if a demonstrated HA/operations requirement cannot be met cleanly. Not every asynchronous operation needs a hand-written AWP lease implementation. Explicit ownership/attempt/cancellation/idempotency semantics are still required where AWP dispatches external work such as AgentRuns, FactoryRuns, CI, Git publication or deployments. ## 9. Workspace and execution durability `Workspace` is the domain abstraction; native Kubernetes Pod/PVC mechanics are the baseline implementation. Disposable compute must not imply disposable WIP. Before real agent execution, tests must cover process crash, pod deletion/replacement, AWP restart, cancel/retry and recoverable node interruption. The resolved `ExecutionProfile` is an immutable run input containing the project toolchain/environment, service attachments and provenance. Prefer existing `.devcontainer`, Docker/Compose, mise/Devbox and project language/tool declarations before generating AWP configuration. ## 10. Security and trust boundaries ### Principals ```text Principal = Human | Agent | System ``` Every meaningful state-changing action is attributable to a Principal. ### Gateway -> control-plane trust The gateway may parse/verify credentials and reject invalid traffic, but it never makes final authorization decisions. The control plane must authenticate the gateway/internal caller and independently resolve or verify the Principal context. Forwarded identity claims are not trusted merely because they arrived from an HTTP header. The control-plane service should not require direct public Internet exposure in the normal topology. ### Credentials Secret material lives behind `SecretStore`; product state stores `CredentialReference` values. Provider credentials are never copied into ordinary configuration/run records. Agents and CI workloads must not receive reusable forge publication credentials. Publication/merge is a trusted control-plane operation with ref restrictions, attempt-bound authorization, ChangeSet fidelity and post-operation verification. ### CI runner trust tiers ARC runners execute repository-controlled code and must be treated as execution-plane workloads, not trusted control-plane processes. Day-one runner architecture requires at least: ```text ephemeral runners no reusable control-plane/Git publication credentials separate runner groups/scale sets when trust or privilege differs no privileged/host access as a universal default untrusted/fork PR jobs receive no protected secrets resource limits + namespace/network isolation runner pod cleanup after each job ``` Use gVisor for CI runner workloads where compatible. If a workflow requires privileged container-building mechanics, isolate that capability into an explicitly trusted runner profile rather than weakening every runner. ## 11. CI architecture GitHub Actions is the initial execution provider; ARC is the day-one K3s runner manager. AWP owns: ```text why CI runs Project / WorkItem / ChangeSet correlation required-check/invariant policy approval/progression policy normalized CIExecution and CIResult operator UX/history resolver/optimizer policy ``` GitHub Actions owns workflow/job execution semantics. ARC owns registration, scale-set/listener mechanics, runner pod lifecycle and cleanup. AWP may perform change-impact analysis and recommend/require checks, but it must reconcile that policy against actual GitHub workflow/check execution rather than pretending ARC itself is a CI engine. ## 12. Deployment architecture The baseline Kubernetes deployment provider is: ```text release/deployment intent -> render Helm/manifests -> server-side dry-run/diff -> approval/policy -> Kubernetes Server-Side Apply with AWP field manager -> observe rollout/health -> persist result -> rollback to previous known-good release when policy requires ``` AWP owns Deployment state and rollback policy. Kubernetes owns apply/rollout mechanics. Flux is added only for explicit continuous GitOps reconciliation requirements; Flagger only for explicit progressive delivery requirements. ## 13. Events, audit, realtime and telemetry Keep four concepts separate: ```text Business events = durable lifecycle facts Audit = who did what to what Realtime = non-authoritative projection/fan-out Telemetry = logs, metrics, traces ``` Business events and audit are product data. Realtime clients recover from authoritative control-plane state after disconnect. OpenTelemetry is the instrumentation/export boundary; a Collector and persistent telemetry stack are optional deployment infrastructure. External event envelopes use CloudEvents where a standard envelope is useful. Provider-specific event vocabularies are adapters. ## 14. Configuration and autonomy Configuration hierarchy: ```text System -> Project -> Plan -> Task -> Run ``` Ordinary configuration can override according to schema. Security/capability ceilings narrow downstream and cannot self-broaden. AWP owns a typed policy/data model for autonomy and human-in-the-loop behavior. The 0–100 UX is a preset/editor over actual rules; no generic external policy engine is a baseline dependency. ## 15. Portability target Portability is selective: ```text Gateway highly portable; Web Standards/Hono; potentially edge/serverless Control plane portable across normal Node + PostgreSQL environments: K3s, Kubernetes, VM, managed container service Execution plane intentionally Kubernetes-specific ``` Do not weaken the control/execution architecture to make the whole product serverless-compatible. ## 16. Intentionally deferred additions These are not architecture gaps: ```text Kubernetes Agent Sandbox Kata Kueue Dagger as an AWP baseline Flux/Flagger unless required Cilium/Hubble Kyverno runtime-detection stack OpenBao/ESO SPIFFE/SPIRE vCluster Crossplane Harbor mandatory OTel Collector/telemetry backend stack service mesh / Redis / Kafka / NATS ``` Each has an explicit trigger in `AWP-FOSS-DECISIONS.md`. ## 17. Architecture risks that specs must enforce 1. **Gateway leakage:** edge code gains direct DB/Kubernetes/domain authority. 2. **Provider leakage:** GitHub/Kubernetes/Fabro/DBOS types become domain types. 3. **Dual lifecycle authority:** provider state competes with persisted AWP state. 4. **Runner privilege creep:** CI convenience creates workstation-like broad authority inside K3s. 5. **Publication credential leakage:** agents/runners gain reusable merge/push credentials. 6. **WIP loss:** ephemeral pods destroy recoverable changes. 7. **Spec duplication:** architecture/domain/workflow/UI documents restate conflicting rules. 8. **Observability retrofit:** events/audit are postponed until UI work. 9. **Configuration/secret mixing:** secret material becomes ordinary editable config. 10. **Premature infrastructure:** optional controllers become structural without a demonstrated requirement. ## 18. Architecture review closure The architecture review is **decision-complete enough to stop architecture exploration and enter specification work**. What is complete: ```text product boundary and classification three-plane runtime topology modular-monolith control plane provider ownership law core primitive/relationship direction persistence authority Hono transport choice DBOS durable-workflow choice K3s workspace/execution baseline Fabro + ACP factory/agent direction GitHub Actions + ARC day-one CI direction Helm + Server-Side Apply deployment direction security/config/event/observability principles FOSS baseline and trigger-only additions ``` What is **not** complete is implementation-grade specification. `docs/specs/` currently contains only its index. The next phase is not another broad architecture review; it is writing the architecture foundation specs and ADRs that freeze these decisions into machine- and implementation-legible contracts. ## 19. Required next specification set Before substantive product implementation, create: ```text docs/specs/architecture/ principles.md deployment-topology.md domain-model.md module-boundaries.md transport-and-contracts.md persistence-and-transactions.md durable-execution.md event-audit-realtime.md security-and-trust.md configuration-and-policy.md workspace-execution.md adapter-contracts.md ci-and-runner-boundary.md docs/specs/adr/ control-plane-and-three-plane-topology modular-monolith Hono transport PostgreSQL + Drizzle DBOS durable workflows native Kubernetes WorkspaceProvider GitHub Actions + ARC day-one CI Helm + Server-Side Apply deployment ``` After that foundation set, specify the first Project -> Plan -> WorkItem -> FactoryRun -> AgentRun -> ChangeSet -> Review -> Merge vertical slice.