tegwick
a680fb51af
ADR-003 formalises the 5-repo structure aligned with OAS Stack S1-S5: railiance-infra, railiance-cluster, railiance-platform, railiance-enablement, railiance-apps. Defines boundary rule, pre-condition chain, and content relocation table. ADR-002 marked superseded. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# 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.
|