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