railiance-platform/ArchitectureBlueprint.md

# Railiance Architecture Blueprint

> The structural backbone of Railiance: the axes along which repositories are
> classified, the layers of the stack, and the rules that keep them from
> collapsing into each other.
>
> **Status:** working blueprint, established 2026-08-11. Structural claims here
> are verified; items marked **OPEN** are undecided and name their deciding
> repo. This file records structure, not runtime state — for what is currently
> deployed, see each repo's `SCOPE.md`.
>
> **Authority note:** `railiance-master` owns the repo-family model and
> `the-custodian` owns canon. This blueprint consolidates and applies them from
> the S3 perspective; where the two disagree, they win.

---

## 1. Four classification axes

Railiance classifies repositories along four **orthogonal** axes. They are
complementary, not competing — a workload has a position on all four.

| Prefix | Axis | Unit | Answers |
| --- | --- | --- | --- |
| `railiance-*` | ownership and responsibility | one architectural responsibility area | who owns this capability or layer? |
| `rail-*` | execution contract | one workload execution architecture | how does a workload run here? |
| `rapp-*` | managed workload package | one Railiance-managed workload | what exactly is packaged and operated? |
| `reef-*` | substrate boundary | one durable substrate reality | where does this run, and what is bound there? |

Source: `railiance-master/docs/repository-axes.md`.

### The separation rule

Independent perspectives stay in separate dimensions. This is **normative**,
not stylistic — OAS P1, `canon/standards/orthogonal-architecture_v1.0.md`:
*"Architecture descriptions MUST separate independent perspectives into
orthogonal dimensions."*

Three groupings are routinely confused and must not be derived from each other:

| Grouping | Answers | Cardinality to repos | Changes |
| --- | --- | --- | --- |
| Forgejo org | who may push; what is discoverable together | 1:many | slowly (renames break clone URLs, CI, GitOps sources) |
| State Hub domain | which strand of work, for attention and priority | 1:many | occasionally |
| **Rapp context** | what deploys, versions and rolls back together | **many:many** | often |

A repo lives in exactly one Forgejo org — it is a path segment in the clone URL.
A repo may contribute to several rapps. **A many:many grouping cannot be derived
from a 1:many one.** Decision `d07ee5f9`.

**The cardinality that makes enforcement possible:** repos are many:many with
rapps, but **deployables are 1:1** — each running deployable has exactly one
rapp owning its rollout. That is what makes the coverage check well-formed:
*does every live deployable belong to exactly one rapp?*

---

## 2. The stack

The OAS Stack dimension defines five levels. Railiance implements them as
responsibility repos, plus cross-cutting and meta concerns that sit beside the
stack rather than inside it.

| Level | Repo | Owns |
| --- | --- | --- |
| S1 | `railiance-infra` | OS provisioning, hardening, server baseline, at-rest bootstrap secrets |
| S2 | `railiance-cluster` | k3s, Helm, ingress, CNI, admission controllers, operators, kubeconfig |
| S3 | `railiance-platform` | shared stateful services: data, cache, secrets, object storage, messaging |
| S4 | `railiance-enablement` | paved paths: CI/CD templates, SDKs, portal, promotion conventions |
| S5 | `railiance-apps` | user-facing application workloads and release operations |

| Beside the stack | Repo | Owns |
| --- | --- | --- |
| evidence plane | `railiance-telemetry` | metrics, logs, traces, alerting — the substrate other layers emit into (**OPEN** placement, §5.1) |
| architecture | `railiance-master` | repo taxonomy, framework ADRs, boundary rules, vocabulary |
| ecosystem graph | `railiance-fabric` | repo → service → capability → interface → dependency model |
| forge | `railiance-forge` | source hosting, registries, automation runners — **being placed** (§5.2): workload → `rapp-forgejo`, layer responsibility → S4 |

### The layering contract

Each layer hands the next a **verified** substrate and does not reach past its
neighbours. The handoffs are declared from both sides — S4 names its forge
contract for runner labels and registry endpoints; S5 names backup and
data-ownership handoffs with S3. Preserve this property when editing any
`INTENT.md`: a handoff stated by only one side is a latent boundary dispute.

---

## 3. The self-evidencing thread

Five layers independently declare the same aspiration in their
`Direction of Evolution`:

- S1 — "self-evidencing, auditable provisioning"
- S2 — "self-evidencing, auditable runtime state"
- S3 — "self-healing and observable platform services"
- S5 — "self-evidencing, reviewable application readiness"
- forge — "self-evidencing forge health and readiness checks"

**This is the architectural through-line of Railiance**: the system should prove
its own state rather than be asserted correct. It reached five INTENT files
independently and was never named as a fleet-wide quality dimension.

It has two halves, and they belong to different repos:

| Half | Question | Home |
| --- | --- | --- |
| **Evidence plane** | is the running system behaving as expected? | `railiance-telemetry` |
| **Conformance loop** | do declarations match reality and each other? | **OPEN** (§5.3) |

Both are required. Observability without conformance checking finds outages but
not drift; conformance checking without observability finds drift but not
outages.

---

## 4. Repository status

Not every `railiance-*` directory is a canonical repository. Verified
2026-08-11 by comparing remotes, HEADs, and working trees.

| Repo | Status | Evidence |
| --- | --- | --- |
| `railiance-infra` | **canonical S1** | active; strict content superset of `hosts` |
| `railiance-hosts` | **superseded** | distinct remote, unrelated history, byte-identical `INTENT.md`, **zero unique files**; quiet since 2026-07-30 |
| `railiance-cluster` | **canonical S2** | active; has `install/` and rail-kubernetes extraction docs |
| `railiance-bootstrap` | **superseded as S2; repurpose candidate** | distinct remote, unrelated history, declares itself S2 verbatim; frozen 2026-07-08. Carries `QUICKSTART.md` (newcomer path) — candidate home for *seeding a new Railiance* |
| `railiance-platform` | canonical S3 | active |
| `railiance-enablement` | canonical S4, **aspiration-only** | 25 commits, 0 workplans; widest aspiration-to-reality gap in the family |
| `railiance-apps` | canonical S5 | active |
| `railiance-telemetry` | **seeded** 2026-08-11 | `INTENT.md`/`SCOPE.md` written; no implementation |
| `railiance-master` | canonical meta | active |
| `railiance-fabric` | canonical meta | quiet since 2026-07-30; non-standard `INTENT.md` format |
| `railiance-forge` | canonical, **unplaced** | active workplan; not on any stack level |

### The duplication pattern

`bootstrap`, `cluster`, `hosts`, `infra` have **mutually unrelated git
histories but near-identical content**. They were created by copying working
trees into fresh repos as the S1/S2 layering idea emerged — not by forking.
Two lineages, each with a frozen elder and an active successor.

Consequence for tooling: **fleet inventories built by scanning directories
overcount.** Deduplicate by origin URL, not by directory name.

---

## 5. Open decisions

Each names the repo that decides it. None should be settled in `railiance-platform`.

### 5.1 Where does `railiance-telemetry` sit? → `railiance-master`

Observability is cross-cutting: it draws signal from every level and is consumed
by all of them. Is it an S3 platform capability (it runs stateful services and
is consumed by others), or a Quality-dimension concern outside the Stack
dimension? Stated explicitly at seeding so it does not drift into §5.2's state.

### 5.2 Where does `railiance-forge` sit? → **DECIDED 2026-08-11**

**Place it, do not retire it.** Operator decision:

- the Forgejo **workload** becomes `rapp-forgejo` (a managed workload package)
- the **layer responsibility** — runner placement and labels, registry
  retention, artifact lifecycle, package credentials — folds into **S4
  `railiance-enablement`**, which already declares the handoff contract for
  exactly these concerns

This also gives S4, currently the widest aspiration-to-reality gap in the
family, its first concrete owned responsibility.

Implementation is `railiance-master` and `railiance-forge` territory; this
blueprint records the decision, not the migration.

The retirement hypothesis was **tested and rejected**: `railiance-forge`
and `helix-forge` are different lineages. `helix-forge` is methodological
(capability-first ecosystem, OAS dimensions, VSM vocabulary); `railiance-forge`
is operational (`helm/`, `manifests/`, `releases/`, `runner/`, live workplan on
Forgejo resource economics). Retiring it would orphan runner placement, registry
retention, and artifact lifecycle. **Place it, do not retire it.** The likely
resolution: the Forgejo *workload* becomes `rapp-forgejo`; the *layer*
responsibility folds into S4, which already declares the handoff contract.

### 5.3 Who owns the conformance loop? → `railiance-master`

Candidates: S4 (the paved-path layer), `railiance-master` (the definition home),
or a new responsibility repo. Related: the family declaration validator proposed
to `railiance-master` (`04c776c4`, amended `f88f938d`).

### 5.4 Retirement and repurposing → `railiance-master`, then the repos

- retire `railiance-hosts` (content-safe; **check git history before deletion**,
  and move its live hub goal "Secure Single-Server Bootstrap at HostEurope" to
  `railiance-infra` first, or it resurfaces as unstarted S1 work)
- repurpose `railiance-bootstrap` as the seed-a-new-Railiance repo, consolidating
  the newcomer path that currently exists in both it and `railiance-cluster`
- delete the local `~/railiance-bootstrap` directory, which is a mis-cloned copy
  of `railiance-cluster.git`

### 5.6 Does Railiance use ArgoCD at all? → **OPEN**, `railiance-master`

Raised by the operator 2026-08-11: GitOps-by-ArgoCD may be Helix Forge tooling
rather than a Railiance concern, or may not be needed at all.

**This cannot be resolved by editing documentation.** S3 currently runs ArgoCD
as its live deployment mechanism: four Application manifests
(`external-secrets`, `issue-core`, `openbao-secretstore`, `target-revenue`),
AppProjects under `argocd/bootstrap/`, `docs/argocd-gitops.md`, and the two most
recent commits in this repo add ArgoCD Applications. Removing mentions while the
Applications remain would make the documentation describe a system that does not
exist.

The real question is an architecture decision — *should S3 deploy via ArgoCD?* —
with a migration attached if the answer is no. Until it is taken, mentions stay
because they are accurate.

### 5.5 Rapp granularity and composition → decided, implementation open

Grouped by bounded context; members declared explicitly; grouping legitimate
only where members share rollout and rollback fate (`7a1f7a7e`). A rapp declares
a **composition**: first-party member repos plus pinned upstream components plus
a stated purpose.

---

## 6. Known capability gaps

| Gap | State |
| --- | --- |
| Verification substrate | evidence half now owned by `railiance-telemetry` (seeded); conformance half **unowned** (§5.3) |
| Observability | home created 2026-08-11; **no implementation**, no monitoring namespace in-cluster |
| End-to-end restore proof | split across S1, S3, S5; no single owner; backing object-storage decision escalated and unresolved (`9c21c0e0`) |
| Cost and resource attribution | `resource-control` and `fin-hub` hold it; no `railiance-*` INTENT declares the boundary |
| Identity dependency declaration | `net-kingdom` referenced in prose; rarely declared structurally. `railiance-fabric` exists to fix this |

---

## 7. Sources

- `railiance-master/docs/repository-axes.md` — the four families
- `railiance-master/docs/repo-family-bootstrap-contract.md` — required declarations
- `railiance-master/docs/rapp-first-wave-candidates.md` — extraction criteria and sequencing
- `the-custodian/canon/standards/orthogonal-architecture_v1.0.md` — OAS, P1
- `railiance-platform/docs/rapp-platform-service-pattern.md` — S3 platform-service pattern
- `railiance-platform/history/2026-08-11-railiance-architecture-in-aspiration.md` — the INTENT-based assessment behind this blueprint
- decisions `7a1f7a7e` (rapp granularity), `d07ee5f9` (dimensional separation)