# AWP Deployment Topology

**Date:** 2026-08-19  
**Status:** Canonical architecture boundary  
**Purpose:** Preserve a day-one separation between internet-facing stateless delivery, the authoritative AWP control plane, and the Kubernetes execution plane so future deployment changes do not require architectural reversal.

## 1. Canonical topology

```text
                    INTERNET

                       |
                       v
              EDGE / GATEWAY PLANE
          +----------------------------+
          | Web UI / static assets     |
          | public API gateway         |
          | auth/session ingress       |
          | webhooks                   |
          | realtime fan-out           |
          +-------------+--------------+
                        |
                        v
                AWP CONTROL PLANE
          +----------------------------+
          | application/domain         |
          | policy / authorization     |
          | durable workflow           |
          | business events / audit    |
          | PostgreSQL                 |
          +-------------+--------------+
                        |
                        v
                EXECUTION PLANE
          +----------------------------+
          | K3s / Kubernetes           |
          | Agents / Workspaces        |
          | GitHub Actions ARC runners |
          | CI workloads               |
          +----------------------------+
```

This is a logical boundary from day 1. It does **not** require Cloudflare, another edge vendor, or a serverless runtime on day 1.

The initial deployment may run both the gateway and control-plane processes in K3s or on ordinary servers. They must still remain separate build/deployment targets with explicit contracts so the gateway can later move to Cloudflare Workers, another edge runtime, a container platform, or a conventional reverse-proxy host without moving the authoritative control-plane state.

## 2. Ownership rules

### Edge / gateway plane

Allowed responsibilities:

```text
serve UI/static assets
terminate public HTTP
route/version public API requests
basic request normalization
rate limiting / abuse controls
credential/session parsing and verification where portable
receive and validate webhook envelopes
proxy/stream realtime traffic
fan out non-authoritative realtime updates
```

Forbidden responsibilities:

```text
authoritative domain state
business lifecycle transitions
final authorization/policy decisions
DBOS durable workflow execution
Kubernetes control
Git publication authority
CI lifecycle authority
release/deployment authority
direct ownership of PostgreSQL schema/state
```

The edge may reject obviously invalid/unauthenticated traffic, but authoritative authorization remains in the control plane.

### AWP control plane

Owns:

```text
Project / Plan / WorkItem / FactoryRun / AgentRun semantics
policy and final authorization
durable workflows
business events and audit
CIExecution / Release / Deployment state
provider coordination
PostgreSQL persistence
GitHub/VCS provider coordination
Kubernetes execution requests
```

The control plane is the stateful product core. It may run on K3s, a VM, managed containers, or another long-lived Node-compatible environment. It is not required to be edge/serverless compatible.

### Execution plane

Owns replaceable mechanics only:

```text
K3s scheduling/runtime
agent pods
workspace pods/PVCs
build/test workloads
gVisor RuntimeClass where selected
GitHub Actions runner pods through ARC
service dependencies for ExecutionProfiles
```

The execution plane never becomes the authoritative source for AWP lifecycle meaning.

## 3. Day-one code/package boundary

Use separate deployable applications even if initially hosted in the same cluster:

```text
apps/
  gateway/         # Hono, public/edge-safe transport
  control-plane/   # Hono on Node, DBOS, domain modules, providers
  web/             # React/Astryx UI

packages/
  contracts/       # runtime-neutral DTOs, schemas, public API/event contracts
  domain/          # AWP domain semantics; no Hono/Cloudflare/Kubernetes types
  application/     # commands/queries/use cases
  providers/       # provider interfaces
  ...
```

Exact filesystem names may change, but the dependency direction is binding:

```text
gateway -> contracts
web     -> contracts
control -> contracts + application + domain + providers

control -> DBOS/PostgreSQL/Kubernetes/GitHub adapters

gateway -X-> DBOS
gateway -X-> Kubernetes
gateway -X-> control-plane database repositories
domain  -X-> Hono/Cloudflare/Kubernetes/GitHub SDK types
```

## 4. Hono rule

Hono is selected for both gateway and control-plane HTTP transport because it gives AWP a small Web-Standards transport layer without making the domain depend on a Node-specific server framework.

The same domain/application code is **not** required to run on an edge runtime. Only the gateway/public transport package must remain edge-portable.

Do not import Node-only APIs into `gateway` or shared runtime-neutral `contracts` packages.

## 5. PostgreSQL and DBOS rule

PostgreSQL and DBOS belong to the control plane.

```text
Gateway
   |
   | HTTP / realtime contract
   v
Control Plane
   +-- PostgreSQL
   +-- DBOS
```

Do not design the gateway around direct database access. This preserves deployment freedom and avoids turning a future edge platform into part of AWP's persistence contract.

DBOS workflow code may use Node/runtime facilities through control-plane adapters and does not need to be bundle-compatible with the gateway target.

## 6. Authentication and authorization split

```text
Gateway
  credential/session parsing
  signature verification where portable
  coarse ingress rejection
       |
       v
Control Plane
  Principal resolution
  role/permission checks
  project/run policy
  approval requirements
  final authorization
```

No edge vendor identity product becomes mandatory for AWP. Edge-specific auth may be an adapter.

## 7. Webhooks

Public provider webhooks terminate at the gateway when one is deployed.

```text
GitHub/provider
      |
      v
Gateway
  verify envelope/signature
  normalize ingress metadata
      |
      v
Control Plane
  idempotency
  provider event mapping
  business transition
  durable event/audit
```

Webhook delivery is input, not lifecycle authority.

## 8. Realtime

Realtime transport and durable truth are separate.

```text
Control Plane business state/events
        |
        v
realtime projection/stream
        |
        v
Gateway fan-out
        |
        v
browser/client
```

The gateway may later use a vendor-specific fan-out mechanism, but reconnecting clients must be able to recover authoritative state from the control plane.

## 9. CI from day 1: GitHub Actions Runner Controller on K3s

K3s-hosted GitHub Actions runners are a **day-one requirement**, not a customer-triggered optional feature.

```text
GitHub Actions
      |
      | scale-set/job protocol
      v
ARC controller/listener in K3s
      |
      v
ephemeral runner pods
      |
      v
project workflow jobs
```

AWP does not maintain standalone GitHub runner daemons independently on each machine.

ARC owns runner registration, scale-set mechanics, runner pod lifecycle and cleanup. AWP owns CI policy, correlation to Project/WorkItem/ChangeSet, check interpretation, approvals, progression, result persistence and operator UX.

Initial CI provider model:

```text
CiProvider
  initial provider: GitHub Actions

RunnerInfrastructure
  baseline: ARC on K3s

AWP
  authoritative CIExecution/CIResult representation
```

Project-native `.github/workflows/*` remain usable. AWP may also run preflight/ad-hoc checks inside AgentRun workspaces, but that does not replace the day-one GitHub Actions + ARC CI path.

## 10. Portability rule

Prefer cheap portable boundaries where they do not compromise the product:

```text
public HTTP      Fetch/Web Standards + Hono
public contracts runtime-neutral TypeScript/schema definitions
state            PostgreSQL
object storage   S3-compatible API
artifacts        OCI
execution        Kubernetes API
agent wire       ACP where supported
external events  CloudEvents
```

This is **not** a requirement that all AWP components become serverless-compatible.

The objective is narrower: a future deployment can move the stateless public plane independently, and can move the control plane between K3s/VM/container environments, without rewriting product semantics or the execution plane.

## 11. Architecture invariants

```text
TOP-001 Gateway is stateless with respect to authoritative AWP product state.
TOP-002 Gateway never imports DBOS, Kubernetes control adapters, or control-plane repositories.
TOP-003 Control plane owns final authorization and all lifecycle transitions.
TOP-004 PostgreSQL is reached through the control plane, not directly from public clients/gateway code.
TOP-005 Execution workloads are replaceable mechanics; K3s state is not AWP domain truth.
TOP-006 Realtime is a projection of durable control-plane state, not a separate source of truth.
TOP-007 Public/provider webhooks are idempotent inputs to durable control-plane processing.
TOP-008 Hono types stop at transport adapters; domain/application layers remain transport-neutral.
TOP-009 Edge-vendor features are adapters, never mandatory domain dependencies.
TOP-010 GitHub Actions runners are K3s-hosted through ARC from day 1; no per-server runner administration model.
TOP-011 CI results are normalized into AWP-owned CIExecution/CIResult semantics regardless of provider.
TOP-012 The gateway and control plane are separate deployable targets even when co-located initially.
```