Architecture Decision Records

Capability-scoped architectural decisions for the Self-Hosted Application Platform, in MADR 4.0.0 format. Each ADR cites the TR-NN it addresses and records the options that were weighed and rejected.

Capability-scoped ADRs for the Self-Hosted Application Platform. Numbering is local to this capability (starting at 0001). Each ADR moves proposed → accepted → (later) superseded; plan-tech-design refuses to compose the tech design until every ADR is accepted.


[0001] Cross-Environment Topology

The platform inherits the existing three-tier shape — Internet-facing edge → public-cloud anchor → secure tunnel → private home-lab — with tenant workloads hostable in either environment, all end-user traffic entering through the edge, and the tunnel reserved for platform operations/maintenance.

[0002] Tenant Workload Placement Policy

A tenant’s hosting environment is resolved mechanically from the resource needs it already declares, matched against each environment’s offering inventory, with the public-cloud anchor as the default when both qualify and an operator override that must be recorded. Placement is an operator-internal detail, not part of the platform contract.

[0003] Definitions Repository & Tracked-Changes Substrate

Platform state lives across two git repositories with a decided seam — public reusable modules, docs, and tenant declarations in Zaba505/infra; private per-environment bindings, values, and apply workflows in Zaba505/homelab — joined by a module reference that becomes a tracked definition rather than a hand-typed dispatch input, so the private repository’s main is a single reference sufficient to reproduce the platform.

[0004] Rebuild Orchestrator & Phase Model

The rebuild’s phase model, ordering, teardown contract, and drill-vs-live parameterization live in a Dagger module written in Go in the public repository; the forge is a thin invoker that supplies the target and hosts the operator checkpoints. Phase ordering is reordered so the operations tunnel precedes home-lab bare metal, iPXE chainloads from a stable cloud-hosted endpoint rather than a LAN appliance, drills exercise the home-lab phase against virtual hosts on the home-lab LAN, and phase 4 exposes an idempotent canary teardown whose failure is a readiness failure.