# Deployment Topology

**Status:** Approved target-state baseline  
**First realization:** I0

## Target State

AWP uses three logical planes from day one. They may initially share one physical K3s cluster, but their code, authority and trust boundaries remain distinct.

```text
                    Internet
                       |
                       v
+----------------------------------------------+
| EDGE / GATEWAY PLANE                         |
| Web/static assets · public Hono API          |
| auth/session ingress · webhooks · realtime   |
+----------------------+-----------------------+
                       | authenticated internal request
                       v
+----------------------------------------------+
| CONTROL PLANE                                |
| domain/application · final authorization     |
| DBOS workflows · PostgreSQL/Drizzle          |
| business events · audit · provider control   |
+----------------------+-----------------------+
                       | constrained provider operations
                       v
+----------------------------------------------+
| EXECUTION PLANE (K3s/Kubernetes)             |
| AgentRun workspaces · Fabro · ARC runners    |
| CI jobs · later deployment workloads         |
+----------------------------------------------+
```

### Edge / gateway

Public ingress and realtime fan-out only. It is intentionally portable and must not gain direct repository, DBOS or Kubernetes authority.

### Control plane

Long-lived Node service and PostgreSQL-backed authority. It owns all lifecycle mutations, policies, provider coordination and durable audit.

### Execution plane

Kubernetes-specific, hostile-by-default compute zone for agent and repository-controlled workloads. Pods/runners are disposable. WIP and product state are not.

## Invariants From Day 1

- gateway never talks directly to Kubernetes, DBOS repositories or provider publication APIs;
- control plane is not normally public Internet-facing;
- forwarded identity is verified/resolved by the control plane rather than trusted from arbitrary headers;
- AgentRun/CI pods never contain reusable control-plane/Git publication credentials;
- namespaces/service accounts/network policies express trust tiers;
- execution may fail independently without losing authoritative state;
- control-plane restart does not abandon durable workflows;
- realtime disconnection recovers from authoritative state rather than treating the stream as truth.

## Deployment Units

Target deployables:

```text
apps/gateway
apps/control-plane
apps/web

execution controllers/providers
  WorkspaceProvider / FactoryProvider / CIProvider adapters
```

A monorepo does not imply one deployment image. Logical deployables may share packages while respecting dependency laws.

## Network and Trust Boundaries

1. Public clients -> gateway: public trust boundary; normal authentication/session rules.
2. Gateway -> control plane: authenticated internal caller + explicit Principal context.
3. Control plane -> Kubernetes/providers: service credentials scoped to required API/capabilities.
4. Execution workload -> external provider: attempt-scoped projection only where the workload requires it.
5. Execution workload -> control plane: narrow run protocol/event submission, never arbitrary privileged control access.

## Portability

```text
Gateway      highly portable: Web Standards/Hono, edge/serverless-capable
Control      portable: ordinary Node + PostgreSQL on K8s/VM/managed containers
Execution    intentionally Kubernetes-specific
```

Do not weaken the execution model merely to make the whole system serverless-compatible.

## State Placement

- PostgreSQL: authoritative product state, audit/business events/outbox, DBOS state.
- S3-compatible object storage: large artifacts, logs/checkpoints where appropriate.
- Kubernetes: observed workload state, not product truth.
- GHCR/OCI registry: images/artifacts where appropriate.
- browser/client: projection/cache only.

## Increment Realization

| Increment | Topology realization |
|---|---|
| I0 | Deploy/control skeleton, K3s execution substrate, gateway/control logical boundary, PostgreSQL, DBOS. |
| I1 | Live AgentRuns and ARC-backed repository checks prove execution/control separation. |
| I4 | Rich realtime Factory projections consume existing event topology. |
| I5 | CI control plane deepens runner/provider usage. |
| I6 | Deployment provider uses control-plane authority over target environments. |
| I7 | Cluster UI exposes execution-plane machines/capacity without changing topology. |
| I9 | Optional external/customer deployment profiles, HA and multi-tenant hardening. |

## Current Implementation State

No target topology change is implied by existing Overdeck tooling. AWP starts from the three-plane model.

## Deferred Realization

Separate physical clusters, advanced multi-region/HA, dedicated edge provider deployment and enterprise tenant isolation are later operational decisions behind the same plane boundaries.

## Temporary Dogfood Behavior

All planes may initially live in one K3s cluster. This is a hosting shortcut only; namespace/service-account/network/dependency rules must still preserve the logical boundaries.

## Decisions / ADRs

See ADR 0001. Any proposal to merge gateway/control authority or move normal agents back to the workstation requires an explicit superseding Decision.