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

Repos that are not stack levels are not homeless — they belong to other OAS dimensions (§2.1):

Repo	Dimension	Owns
railiance-telemetry	Quality / Q2 Observability	metrics, logs, traces, alerting — the substrate other layers emit into
railiance-bootstrap	lifecycle (pre-stack)	the ignition sequence: bare VM → working Railiance, then handoff
railiance-master	the architecture description itself	repo taxonomy, framework ADRs, boundary rules, vocabulary
railiance-fabric	Capability	repo → service → capability → interface → dependency model
railiance-forge	being placed (§5.2)	workload → rapp-forgejo; layer responsibility → S4

2.1 Railiance uses one of six canonical dimensions

This is the central coherence finding of the 2026-08-11 review.

OAS defines six canonical architecture dimensions, and states that "Each architecture description MUST use these dimensions" (canon/standards/orthogonal-architecture_v1.0.md §4):

Dimension	Purpose	Railiance use
Stack	technical hosting substrate	used — S1–S5, the whole model to date
Logic	functional decomposition	unused
Plane	operational responsibility	unused
Quality	cross-cutting architecture properties	unused — and this is where the gaps are
Capability	stable capability modeling	partial (railiance-fabric, capability registry)
Intelligence	degree of intelligent automation	unused

Railiance has modelled itself almost entirely on the Stack dimension. Anything that did not fit a stack level was treated as an anomaly — "unplaced", "beside the stack", "cross-cutting" — and accumulated as exceptions.

They were never anomalies. They are concerns on dimensions Railiance was not using. The Quality dimension's sub-levels map almost one-to-one onto the capability gaps found independently by this review:

Quality sub-level	Canon definition	Railiance concern	State
Q1 Security and Compliance	—	credential custody, OpenBao lanes, CCR approval	implemented (S3), never named as Q1
Q2 Observability	"telemetry and monitoring: metrics, logs, traces"	railiance-telemetry	seeded 2026-08-11
Q3 Operability and Resilience	—	restore drills, rollback proof	split across S1/S3/S5, unowned
Q4 Isolation and Tenancy	—	rapp-postgres ADR-0001, tenant keying	implemented per-consumer, not modelled
Q5 Performance and Scalability	—	—	unaddressed
Q6 Cost and Efficiency	—	resource-control, fin-hub, cost attribution keys	outside the family, boundary undeclared
Q7 Governance and Change Management	"policies and architecture governance"	the conformance loop	unowned (§5.3)

Two consequences worth stating plainly:

1. railiance-telemetry is not an exception to the stack model — it is Q2 Observability, named in canon in exactly those words. Its placement question (§5.1) is effectively answered; railiance-master need only ratify it.
2. The conformance loop is Q7, not a missing stack layer. That reframes §5.3 from "invent a home" to "implement the Quality dimension."

The recurring "self-evidencing" aspiration across five stack layers (§3) is, in OAS terms, five Stack-dimension repos each independently asking for Q2 and Q7. That is what a missing dimension looks like from inside the one you are using.

2.2 The six dimensions, established

Railiance's position on each canonical dimension, with owners where they exist. Sub-levels are canon's, not invented here. Status is honest about what is implemented versus merely named.

Stack — technical hosting substrate · in use

S1 railiance-infra · S2 railiance-cluster · S3 railiance-platform · S4 railiance-enablement · S5 railiance-apps. See §2.

Quality — cross-cutting architecture properties · the priority

Sub-level	Railiance concern	Owner	Status
Q1 Security and Compliance	credential custody, OpenBao lanes, CCR approval, grant catalog	S3	implemented, never named Q1
Q2 Observability	metrics, logs, traces, alerting	railiance-telemetry	seeded 2026-08-11, no implementation
Q3 Operability and Resilience	restore drills, rollback proof, DR	—	split S1/S3/S5, unowned
Q4 Isolation and Tenancy	consumer isolation, tenant keying	rapp-postgres (per-consumer)	implemented, not modelled fleet-wide
Q5 Performance and Scalability	—	—	unaddressed
Q6 Cost and Efficiency	cost attribution, unit economics	resource-control, fin-hub	outside the family, boundary undeclared
Q7 Governance and Change Management	the conformance loop, policy enforcement	—	unowned (§5.3)

Q1 is worth dwelling on: S3 has been building a mature Q1 practice for months — approval gates, delegated apply, revocation semantics, front-door readiness — without ever naming the dimension. That is evidence the dimensions describe real structure rather than imposing vocabulary.

Plane — operational responsibility · implicit, unnamed

Sub-level	Railiance reality
P1 Workload Plane	rapp-* packages and the workloads they run
P2 Control Plane	ArgoCD, CNPG operator, External Secrets, cert-manager
P3 Management Plane	State Hub, railiance-master, workplans, decisions

Railiance already operates all three; none is declared. This is the dimension most likely to clarify the rapp-* / rail-* relationship, since a rail is essentially a P1 contract.

Capability — stable capability modeling · partial

C1 Capability Model / C2 Contract / C3 Realization / C4 Shared Platform Capabilities / C5 Business Capabilities.

railiance-fabric models C1–C3; the per-repo registry/capabilities/ declarations and reuse-surface federation cover C4. C5 is unaddressed and is where the boundary with resource-control / fin-hub (and Q6) belongs. Contradiction C1 lives here: the hub's capability attributions do not match repo declarations.

Logic — functional decomposition · unused

L1 Capability Domain / L2 Service Realization / L3 Composition and Integration / L4 Solution Layer. No Railiance repo is organised on this axis. Lowest priority: the Stack and Quality dimensions carry more weight for an operations framework, and Logic is likely more relevant to Helix Forge's capability-first model.

Intelligence — degree of intelligent automation · emerging, unnamed

I1 Deterministic Automation / I2 Language Interaction / I3 Knowledge and Reasoning / I4 Assisted Adaptation / I5 Agentic Delegation.

Already referenced in practice — qonto-assistant/docs/SecurityPractice.md cites an "I1 Reinforced minimum" isolation profile — and the whole agent operating model (autonomy lanes, Kaizen agents, /ralph-workplan) is I4–I5 territory. Declared nowhere in Railiance. Given how much of this fleet is agent-operated, leaving Intelligence unmodelled understates what the system actually is.

Establishing order

Recommended sequence, for railiance-master to ratify:

1. Quality first. It holds the most unowned concerns (Q3, Q7) and the already-built-but-unnamed ones (Q1, Q4). Q2 has a home as of 2026-08-11.
2. Plane second. Cheap — it is descriptive of what already runs, and it sharpens the rail-* contract.
3. Capability third. Requires resolving C1 (hub attribution drift) and C4 first, or the model is built on bad data.
4. Intelligence fourth. Needs a real decision about how much of the agent operating model belongs in Railiance versus the-custodian.
5. Logic last, or never, if Helix Forge owns functional decomposition.

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? → REOPENED 2026-08-12 on corrected evidence

Decided 2026-08-11 as "keep it", on the basis that S3 runs ArgoCD as its live deployment mechanism. That basis was wrong. Verified against both clusters once API access was restored:

Fact	Evidence
ArgoCD does not run on railiance01	namespace argocd NotFound
ArgoCD runs on CoulombCore	argocd namespace, Active 344d
The Applications target CoulombCore, not railiance01	all four declare server: https://kubernetes.default.svc — in-cluster
Their health is poor	issue-core Degraded, openbao-secretstore Degraded, target-revenue OutOfSync/Missing
The real workloads run on railiance01	target-revenue deploy 1/1 up 6d, openbao sts 1/1, external-secrets 3 deploys 1/1
Nothing on railiance01 is ArgoCD-managed	no namespace carries an argocd.argoproj.io/instance label

So the live S3 workloads are deployed outside GitOps, by Makefile and hand, while the ArgoCD Applications describe a deployment path into the frozen CoulombCore cluster — where target-revenue is registered but Missing, and two others are Degraded.

The earlier claim that removing ArgoCD documentation would "describe a system that does not exist" was backwards: the ArgoCD documentation already describes a deployment path that is largely not in effect.

This does not settle the question — it restates it honestly. Three real options:

1. Adopt properly — stand up ArgoCD on railiance01 and bring the live workloads under GitOps. The Applications become true.
2. Retire — remove the Applications and docs/argocd-gitops.md, and accept Makefile-driven deployment as the declared method.
3. Relocate — GitOps becomes Helix Forge tooling, as originally suspected.

Doing nothing is the one option with a cost: a stale control plane on a frozen cluster, showing Degraded, that no longer reflects how anything ships. Note this is the same defect class as RAIL-HO-WP-0009 — declared state and live state diverged, and nothing detected it.

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 gaps, mapped to dimensions

Read with §2.1: most of these are not scattered omissions but one unbuilt dimension.

Gap	Dimension	State
Observability	Q2	home created 2026-08-11; no implementation, no monitoring namespace in-cluster
Conformance loop	Q7	unowned (§5.3)
End-to-end restore proof	Q3	split across S1, S3, S5; no single owner; backing object-storage decision escalated and unresolved (9c21c0e0)
Cost and resource attribution	Q6	resource-control and fin-hub hold it; no railiance-* INTENT declares the boundary
Performance and scalability	Q5	unaddressed
Identity dependency declaration	Capability	net-kingdom referenced in prose; rarely declared structurally. railiance-fabric exists to fix this

6.1 Contradictions to resolve

Found by the 2026-08-11 coherence review. These are places where two parts of Railiance currently say different things.

#	Contradiction	Resolution
C1	Capability attribution crosses layer boundaries. State Hub attributes ~11 capabilities to railiance-platform, including Terraform server provisioning and Ansible hardening (S1), k3s provisioning and cluster addons (S2), CI/CD automation (S4), and application workload deployment (S5). SCOPE.md declares only four, all correctly S3, and the repo's boundary rule disowns the rest. These are pre-split attributions the hub never dropped.	SCOPE.md is source of truth; the hub needs reconciliation. Until then, hub capability data for this repo is not trustworthy for boundary reasoning.
C2	"Five independent repos per OAS Stack layer" — stated in SCOPE.md — contradicts the four-axis model and the current inventory (§4).	Corrected in SCOPE.md 2026-08-11.
C3	One dimension in use, six required by ratified canon (§2.1).	Route to railiance-master and the-custodian; implement Quality first.
C4	Ecosystem modelling is split four ways — railiance-fabric (graph), State Hub (read model), reuse-surface (capability federation), railiance-master (vocabulary). Fabric draws the boundary crisply in prose but does not mention reuse-surface.	Needs an explicit statement of who owns what; railiance-master and railiance-fabric territory.

---

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)