# Architecture Principles

**Status:** Approved target-state baseline  
**First realization:** I0  
**Authority:** `docs/VISION.md`, `AWP-ARCHITECTURE-BASELINE.md`, `AWP-FULL-SPECIFICATION-RATIFICATION.md`.

## Target State

AWP is an **Agentic Software Delivery Control Plane**. It owns software-delivery intent, authoritative lifecycle state, policy, relationships, provenance, approvals, decisions, configuration semantics, CI/CD progression, business events/audit and operator UX. Replaceable providers own execution mechanics.

```text
Human / agent intent
        ↓
AWP product semantics + authority
        ↓ adapters/providers
GitHub · Fabro · ACP/native agents · DBOS · PostgreSQL · K3s · ARC · Helm/SSA
```

AWP is a standalone product, not a continuation of the Overdeck workstation toolkit. Normal coding, review and CI execution happens in the execution plane, not on the user's workstation.

## Invariants From Day 1

1. **One authoritative product state.** PostgreSQL-backed AWP state wins over provider observations.
2. **Provider mechanics never become domain identity.** Provider IDs are mappings, not primary AWP identity.
3. **Agents code; AWP orchestrates.** Agents may write/review/fix/test code but do not own workspace lifecycle, publication, merge, release, deployment or policy authority.
4. **Control and execution are separate trust zones.** Untrusted agent/CI code never receives reusable publication/control-plane credentials.
5. **Every material state change is attributable.** `Principal = Human | Agent | System` is recorded with audit/business events.
6. **Configuration narrows downstream.** Security/capability ceilings cannot be broadened by lower scopes.
7. **Everything material is a primitive.** Identity/state/policy/events/relationships justify first-class domain objects; incidental implementation details do not.
8. **Durability before ephemerality.** Disposable pods/runners may die; recoverable WIP and authoritative lifecycle state may not.
9. **Business events, audit, realtime and telemetry are distinct.** None substitutes for another.
10. **Full target specification precedes implementation; realization remains incremental.** Later-increment seams are known early but not implemented early.
11. **High-fidelity design precedes user-facing implementation.** JSX/CSS does not become accidental product design.
12. **FOSS/provider reuse is preferred over rebuilding mechanics.** AWP remains a thin product/control layer where mature infrastructure already exists.

## Architecture Decision Heuristics

When choosing between designs, prefer in this order:

```text
standard/protocol
  -> small library/native primitive
  -> adapter around established tool
  -> controller/service stack only when justified
  -> custom machinery last
```

Prefer the least complex design that preserves target seams, security and future increment compatibility. Avoid optional infrastructure becoming structural merely because it is powerful.

## Primitive Qualification

A concept becomes first class when it has meaningful independent:

- identity;
- lifecycle/state;
- relationships;
- policy/configuration;
- durable events/audit;
- user/operator meaning.

Examples: `Project`, `Plan`, `Task`, `FactoryRun`, `AgentRun`, `Attempt`, `ChangeSet`, `Review`, `Decision`, `Approval`, `CIExecution`, `Artifact`, `Release`, `Deployment`, `Cluster`, `Incident`.

Routine helper functions, temporary UI state and provider-specific request objects are not primitives.

## Dependency and Authority Law

```text
domain        -> no transport/provider SDKs
application   -> domain + provider interfaces
adapters      -> provider SDKs + infrastructure
control-plane -> domain/application/providers/adapters
gateway       -> runtime-neutral contracts only
web           -> runtime-neutral contracts only
```

The gateway may reject obviously invalid requests but final authorization belongs to the control plane.

## Increment Realization

| Increment | Principle realization |
|---|---|
| I0 | Three-plane skeleton, module boundaries, persistence, DBOS, adapters, K3s execution, secrets/config skeleton, audit/events, architecture fitness checks. |
| I1 | First complete Project -> Plan -> Task -> FactoryRun -> AgentRun -> ChangeSet -> Review -> Merge lifecycle proves authority and isolation. |
| I2 | Rich Planning, project defaults and delivery recommendations consume the same primitives. |
| I3 | Generic Decision/Approval/autonomy productization. |
| I4 | Rich Factory observability over existing event/state seams. |
| I5 | CI control plane and VerificationAuthority activate without replacing I1 evidence identity. |
| I6 | Artifact/Release/Environment/Deployment activate on pre-specified delivery seams. |
| I7 | Cluster management productizes the K3s substrate. |
| I8 | Generic incident/resolver productization. |
| I9 | External/enterprise concerns and formal reliability/SLO machinery activate. |

## Current Implementation State

Specification/design phase. Architecture choices are ratified; substantive AWP product implementation is not yet the authority.

## Deferred Realization

Later capabilities are specified but remain operationally bounded by the Increment Realization Matrix. Their presence in specs does not authorize early implementation.

## Temporary Dogfood Behavior

Dogfood shortcuts must be explicit, preserve final identity/authority seams, and name the increment that removes/deepens them. No hidden temporary domain model is allowed.

## Decisions / ADRs

See ADRs for three-plane topology, modular monolith, Hono, PostgreSQL/Drizzle, DBOS, Kubernetes workspaces, GitHub Actions/ARC, and Helm/Server-Side Apply. Material changes supersede an accepted Decision before code changes the architecture.