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)