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.
|