diff --git a/docs/adr/ADR-002-repo-boundary-hosts-vs-bootstrap.md b/docs/adr/ADR-002-repo-boundary-hosts-vs-bootstrap.md index 4b1e740..a1f9a50 100644 --- a/docs/adr/ADR-002-repo-boundary-hosts-vs-bootstrap.md +++ b/docs/adr/ADR-002-repo-boundary-hosts-vs-bootstrap.md @@ -1,7 +1,8 @@ # ADR-002 — Repository Boundary: railiance-hosts vs railiance-bootstrap -**Status:** Accepted +**Status:** Superseded by ADR-003 **Date:** 2026-03-09 +**Superseded:** 2026-03-10 — see `ADR-003-railiance-5repo-stack-architecture.md` **Deciders:** Bernd Worsch --- diff --git a/docs/adr/ADR-003-railiance-5repo-stack-architecture.md b/docs/adr/ADR-003-railiance-5repo-stack-architecture.md new file mode 100644 index 0000000..1946b27 --- /dev/null +++ b/docs/adr/ADR-003-railiance-5repo-stack-architecture.md @@ -0,0 +1,103 @@ +# ADR-003 — Railiance 5-Repo Stack Architecture + +**Status:** Accepted +**Date:** 2026-03-10 +**Deciders:** Bernd Worsch +**Supersedes:** ADR-002 (repo-boundary-hosts-vs-bootstrap) + +--- + +## Context + +ADR-002 defined a two-repo boundary between `railiance-hosts` (OS baseline) +and `railiance-bootstrap` (Kubernetes layer). As the railiance tooling expands +to cover platform services, developer enablement, and application deployments, +a two-repo model is insufficient and the naming no longer signals stack position. + +The **Orthogonal Architecture Standard** (OAS v1.0, +`canon/standards/orthogonal-architecture_v1.0.md`) defines six canonical +dimensions. The Stack dimension (S1–S5) provides a natural, self-documenting +structure for the railiance tooling. + +--- + +## Decision + +### One repo per Stack level + +The railiance toolset is structured as five repositories, each owning exactly +one OAS Stack level: + +| OAS Level | Repository | Responsibility | +|-----------|------------|----------------| +| S1 Infrastructure Substrate | `railiance-infra` | OS provisioning, security hardening, Ansible roles, Goss spec + test suite, Terraform, inventory, secrets | +| S2 Cluster Runtime | `railiance-cluster` | k3s, Helm, ingress, CNI, admission controllers, operators, kubeconfig management | +| S3 Platform Services | `railiance-platform` | PostgreSQL HA, object storage, secret management, identity, message brokers, caches | +| S4 Developer Enablement | `railiance-enablement` | CI/CD pipelines, developer portal, platform templates, SDKs, buildpacks | +| S5 Workloads & Experience | `railiance-apps` | Application Helm releases, Kubernetes manifests for user-facing services (Gitea, coulomb apps) | + +### Naming rationale + +The name of each repo encodes its OAS Stack level. A reader seeing the repo +list immediately knows the stack position without reading documentation. +`railiance-enablement` is preferred over `railiance-dev` to avoid ambiguity +with "development environment." + +### Boundary rule + +> **Every file, playbook, and configuration belongs in exactly one repo, +> determined by the OAS Stack level of the concern it addresses.** + +The authoritative reference for whether a concern belongs at a given Stack +level is `canon/standards/orthogonal-architecture_v1.0.md` §5 (Stack +Dimension Specification). + +### Pre-condition chain + +Each layer depends on the layer below being converged and verified: + +``` +railiance-infra (make converge + make verify) + → railiance-cluster (k3s install + smoke test) + → railiance-platform (platform services deployed) + → railiance-enablement (CI/CD and tooling active) + → railiance-apps (application deployments) +``` + +No layer may re-configure concerns owned by a lower layer. + +--- + +## Content relocations from railiance-cluster + +The following items existed in `railiance-bootstrap` (now `railiance-cluster`) +but belong at other Stack levels and are relocated as part of this ADR: + +| Item | Relocated to | OAS Level | Reason | +|------|-------------|-----------|--------| +| `cloudinit/user-data.yaml` | `railiance-infra` | S1 | Cloud-init is node provisioning | +| `tools/cmd/railiance-plan-host` | `railiance-infra` | S1 | Host planning is infrastructure scope | +| `tools/cmd/railiance-backup` | `railiance-platform` | S3 | Backup is a platform service concern | + +--- + +## Consequences + +- `railiance-infra` and `railiance-cluster` are renames; git history is + preserved. +- `railiance-platform`, `railiance-enablement`, and `railiance-apps` are new + repos, initially containing only scaffolding (CLAUDE.md, Makefile, workplans/). +- State Hub `ManagedRepo` slugs are updated from the old names to the new ones. +- All CLAUDE.md, Makefile, and workplan files in the renamed repos are updated + to reflect the new names. +- ADR-002 is superseded and should not be used as an authoritative reference. + Its boundary table is incorporated and extended here. + +--- + +## Superseded ADR + +ADR-002 (`ADR-002-repo-boundary-hosts-vs-bootstrap.md`) is superseded by +this document. Its core rule — that items defined in `spec/server-baseline.yaml` +must not be managed by `railiance-cluster` — remains in force and is +generalised here: no layer may manage concerns owned by a layer below it.