railiance-infra/docs/adr/ADR-003-railiance-5repo-stack-architecture.md

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.