coulomb/railiance-platform
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-platform/ArchitectureBlueprint.md

247 lines
12 KiB
Markdown
Raw Normal View History

Add ArchitectureBlueprint.md as the structural backbone Consolidates what this session established: the four orthogonal repo-family axes and the separation rule that keeps Forgejo orgs, State Hub domains and rapp contexts from being derived from each other; the stack levels plus the concerns that sit beside the stack; the self-evidencing thread and its two halves (evidence plane, now owned by railiance-telemetry, and the conformance loop, still unowned); verified repository status including the two superseded lineages; and the open placement decisions, each naming railiance-master as the decider rather than settling them here. Records that the railiance-forge retirement hypothesis was tested and rejected - it and helix-forge are different lineages, one operational and one methodological - so forge should be placed, not retired. Also notes for tooling that the bootstrap/cluster/hosts/infra repos have unrelated histories but near-identical content, so fleet inventories must deduplicate by origin URL rather than by directory. SCOPE.md gains the telemetry emission relationship and a pointer to the blueprint. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 21:57:36 +02:00
# 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 |
Update Gitea prose to Forgejo; place forge; record ArgoCD as an open decision Gitea has been replaced by Forgejo. Updates prose mentions in docs/ while deliberately preserving live names that a blind sweep would have broken: GITEA_BACKEND_TOKEN is a provisioned OpenBao field in CCR-2026-0002, GITEA_URL is a Makefile variable, and gitea-db is a running cnpg cluster. Capitalisation discriminates prose from identifiers. Archived workplans are left as historical record. Blueprint 5.2: forge placement decided - workload to rapp-forgejo, layer responsibility to S4 railiance-enablement, which already declares the handoff contract and gains its first concrete owned responsibility. Blueprint 5.6: whether Railiance should use ArgoCD at all is recorded as an open decision rather than acted on by removing mentions. S3 runs four live ArgoCD Applications plus AppProjects, and the two most recent commits here add more, so deleting the documentation would describe a system that does not exist. The question is real; it needs a decision and a migration, not a docs edit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:41:30 +02:00
| forge | `railiance-forge` | source hosting, registries, automation runners — **being placed** (§5.2): workload → `rapp-forgejo`, layer responsibility → S4 |
Add ArchitectureBlueprint.md as the structural backbone Consolidates what this session established: the four orthogonal repo-family axes and the separation rule that keeps Forgejo orgs, State Hub domains and rapp contexts from being derived from each other; the stack levels plus the concerns that sit beside the stack; the self-evidencing thread and its two halves (evidence plane, now owned by railiance-telemetry, and the conformance loop, still unowned); verified repository status including the two superseded lineages; and the open placement decisions, each naming railiance-master as the decider rather than settling them here. Records that the railiance-forge retirement hypothesis was tested and rejected - it and helix-forge are different lineages, one operational and one methodological - so forge should be placed, not retired. Also notes for tooling that the bootstrap/cluster/hosts/infra repos have unrelated histories but near-identical content, so fleet inventories must deduplicate by origin URL rather than by directory. SCOPE.md gains the telemetry emission relationship and a pointer to the blueprint. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 21:57:36 +02:00
### 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.
Update Gitea prose to Forgejo; place forge; record ArgoCD as an open decision Gitea has been replaced by Forgejo. Updates prose mentions in docs/ while deliberately preserving live names that a blind sweep would have broken: GITEA_BACKEND_TOKEN is a provisioned OpenBao field in CCR-2026-0002, GITEA_URL is a Makefile variable, and gitea-db is a running cnpg cluster. Capitalisation discriminates prose from identifiers. Archived workplans are left as historical record. Blueprint 5.2: forge placement decided - workload to rapp-forgejo, layer responsibility to S4 railiance-enablement, which already declares the handoff contract and gains its first concrete owned responsibility. Blueprint 5.6: whether Railiance should use ArgoCD at all is recorded as an open decision rather than acted on by removing mentions. S3 runs four live ArgoCD Applications plus AppProjects, and the two most recent commits here add more, so deleting the documentation would describe a system that does not exist. The question is real; it needs a decision and a migration, not a docs edit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:41:30 +02:00
### 5.2 Where does `railiance-forge` sit? → **DECIDED 2026-08-11**
Add ArchitectureBlueprint.md as the structural backbone Consolidates what this session established: the four orthogonal repo-family axes and the separation rule that keeps Forgejo orgs, State Hub domains and rapp contexts from being derived from each other; the stack levels plus the concerns that sit beside the stack; the self-evidencing thread and its two halves (evidence plane, now owned by railiance-telemetry, and the conformance loop, still unowned); verified repository status including the two superseded lineages; and the open placement decisions, each naming railiance-master as the decider rather than settling them here. Records that the railiance-forge retirement hypothesis was tested and rejected - it and helix-forge are different lineages, one operational and one methodological - so forge should be placed, not retired. Also notes for tooling that the bootstrap/cluster/hosts/infra repos have unrelated histories but near-identical content, so fleet inventories must deduplicate by origin URL rather than by directory. SCOPE.md gains the telemetry emission relationship and a pointer to the blueprint. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 21:57:36 +02:00
Update Gitea prose to Forgejo; place forge; record ArgoCD as an open decision Gitea has been replaced by Forgejo. Updates prose mentions in docs/ while deliberately preserving live names that a blind sweep would have broken: GITEA_BACKEND_TOKEN is a provisioned OpenBao field in CCR-2026-0002, GITEA_URL is a Makefile variable, and gitea-db is a running cnpg cluster. Capitalisation discriminates prose from identifiers. Archived workplans are left as historical record. Blueprint 5.2: forge placement decided - workload to rapp-forgejo, layer responsibility to S4 railiance-enablement, which already declares the handoff contract and gains its first concrete owned responsibility. Blueprint 5.6: whether Railiance should use ArgoCD at all is recorded as an open decision rather than acted on by removing mentions. S3 runs four live ArgoCD Applications plus AppProjects, and the two most recent commits here add more, so deleting the documentation would describe a system that does not exist. The question is real; it needs a decision and a migration, not a docs edit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:41:30 +02:00
**Place it, do not retire it.** Operator decision:
Add ArchitectureBlueprint.md as the structural backbone Consolidates what this session established: the four orthogonal repo-family axes and the separation rule that keeps Forgejo orgs, State Hub domains and rapp contexts from being derived from each other; the stack levels plus the concerns that sit beside the stack; the self-evidencing thread and its two halves (evidence plane, now owned by railiance-telemetry, and the conformance loop, still unowned); verified repository status including the two superseded lineages; and the open placement decisions, each naming railiance-master as the decider rather than settling them here. Records that the railiance-forge retirement hypothesis was tested and rejected - it and helix-forge are different lineages, one operational and one methodological - so forge should be placed, not retired. Also notes for tooling that the bootstrap/cluster/hosts/infra repos have unrelated histories but near-identical content, so fleet inventories must deduplicate by origin URL rather than by directory. SCOPE.md gains the telemetry emission relationship and a pointer to the blueprint. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 21:57:36 +02:00
Update Gitea prose to Forgejo; place forge; record ArgoCD as an open decision Gitea has been replaced by Forgejo. Updates prose mentions in docs/ while deliberately preserving live names that a blind sweep would have broken: GITEA_BACKEND_TOKEN is a provisioned OpenBao field in CCR-2026-0002, GITEA_URL is a Makefile variable, and gitea-db is a running cnpg cluster. Capitalisation discriminates prose from identifiers. Archived workplans are left as historical record. Blueprint 5.2: forge placement decided - workload to rapp-forgejo, layer responsibility to S4 railiance-enablement, which already declares the handoff contract and gains its first concrete owned responsibility. Blueprint 5.6: whether Railiance should use ArgoCD at all is recorded as an open decision rather than acted on by removing mentions. S3 runs four live ArgoCD Applications plus AppProjects, and the two most recent commits here add more, so deleting the documentation would describe a system that does not exist. The question is real; it needs a decision and a migration, not a docs edit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:41:30 +02:00
- 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`
Add ArchitectureBlueprint.md as the structural backbone Consolidates what this session established: the four orthogonal repo-family axes and the separation rule that keeps Forgejo orgs, State Hub domains and rapp contexts from being derived from each other; the stack levels plus the concerns that sit beside the stack; the self-evidencing thread and its two halves (evidence plane, now owned by railiance-telemetry, and the conformance loop, still unowned); verified repository status including the two superseded lineages; and the open placement decisions, each naming railiance-master as the decider rather than settling them here. Records that the railiance-forge retirement hypothesis was tested and rejected - it and helix-forge are different lineages, one operational and one methodological - so forge should be placed, not retired. Also notes for tooling that the bootstrap/cluster/hosts/infra repos have unrelated histories but near-identical content, so fleet inventories must deduplicate by origin URL rather than by directory. SCOPE.md gains the telemetry emission relationship and a pointer to the blueprint. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 21:57:36 +02:00
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`
Update Gitea prose to Forgejo; place forge; record ArgoCD as an open decision Gitea has been replaced by Forgejo. Updates prose mentions in docs/ while deliberately preserving live names that a blind sweep would have broken: GITEA_BACKEND_TOKEN is a provisioned OpenBao field in CCR-2026-0002, GITEA_URL is a Makefile variable, and gitea-db is a running cnpg cluster. Capitalisation discriminates prose from identifiers. Archived workplans are left as historical record. Blueprint 5.2: forge placement decided - workload to rapp-forgejo, layer responsibility to S4 railiance-enablement, which already declares the handoff contract and gains its first concrete owned responsibility. Blueprint 5.6: whether Railiance should use ArgoCD at all is recorded as an open decision rather than acted on by removing mentions. S3 runs four live ArgoCD Applications plus AppProjects, and the two most recent commits here add more, so deleting the documentation would describe a system that does not exist. The question is real; it needs a decision and a migration, not a docs edit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:41:30 +02:00
### 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.
Add ArchitectureBlueprint.md as the structural backbone Consolidates what this session established: the four orthogonal repo-family axes and the separation rule that keeps Forgejo orgs, State Hub domains and rapp contexts from being derived from each other; the stack levels plus the concerns that sit beside the stack; the self-evidencing thread and its two halves (evidence plane, now owned by railiance-telemetry, and the conformance loop, still unowned); verified repository status including the two superseded lineages; and the open placement decisions, each naming railiance-master as the decider rather than settling them here. Records that the railiance-forge retirement hypothesis was tested and rejected - it and helix-forge are different lineages, one operational and one methodological - so forge should be placed, not retired. Also notes for tooling that the bootstrap/cluster/hosts/infra repos have unrelated histories but near-identical content, so fleet inventories must deduplicate by origin URL rather than by directory. SCOPE.md gains the telemetry emission relationship and a pointer to the blueprint. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 21:57:36 +02:00
### 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)
Reference in a new issue Copy permalink