About this document
First-wave arc42 for the Railiance runtime substrate. Deeper chapters belong to follow-on work in this repo. Chapter 9 lists the ADRs this repo already publishes; it does not paste them.
01Introduction and Goals
Railiance-master is the authoritative source for Railiance framework architecture: repo families, workload models, and substrate boundaries that implementation repos must not invent locally.
1.1 Requirements Overview
- Name the rails, reefs, and rApps and who owns each boundary.
- Keep those decisions in
docs/adr/with publication-grade metadata. - Consume platform packages; do not fork identity or tenancy.
1.2 Quality Goals
- Reviewable boundary decisions.
- Private-by-default exposure until admission.
- Derived rails compose; they do not fork policy.
1.3 Stakeholders
| Role | Concern |
|---|---|
| railiance-master | Framework language and first-wave rApp set. |
| railiance-platform | S3, placement, substrate services. |
| railiance-apps | Production digest bindings. |
| NetKingdom | Identity and tenancy posture of workloads. |
02Architecture Constraints
N/A for this stub.
03System Scope and Context
In: rails, reefs, rApp packaging, admission, exposure defaults. Out: tenant identity semantics (NetKingdom), publication of policy (policy-nexus), OS baseline (railiance-hosts).
3.1 Business Context
Implementation repos solve immediate cluster problems. This system holds the shared meaning so those repos do not drift.
3.2 Technical Context
Neighbours: railiance-platform, railiance-apps, rapp-* packages, the reef (Traefik, cert-manager), Forgejo, NetKingdom, policy-nexus.
04Solution Strategy
N/A for this stub — repository-prefix architecture and rapp-first wave are already in the ADRs in §9.
05Building Block View
5.1 Level 1 – System/Top-Level
N/A for this stub.
06Runtime View
N/A for this stub.
07Deployment View
N/A for this stub.
08Cross-Cutting Concepts
N/A for this stub.
09Architecture Decisions
Published on policy.coulomb.social from this repo:
| Id | Status | Decision |
|---|---|---|
RMASTER-ADR-0001 | accepted | Repository prefix architecture |
RMASTER-ADR-0002 | accepted | Wave 1 rail-kubernetes boundary |
RMASTER-ADR-0003 | accepted | First-wave rapp selection |
RMASTER-ADR-0004 | accepted | First-wave reef rollout |
RMASTER-ADR-0005 | accepted | Derived rail composition |
RMASTER-ADR-0006 | accepted | Reef production admission |
RMASTER-ADR-0007 | accepted | Rapp declaration contract |
RMASTER-ADR-0008 | accepted | Private-by-default exposure |
Also published from railiance-platform: RPLAT-ADR-0001 (S3 platform services), RPLAT-ADR-0002 (placement rule), RPLAT-ADR-0003 (decisions live in the repo).
Unresolved: identical accepted ADR-003/004 copies in railiance-hosts and railiance-infra. Not listed as current here until those owners rule.
10Quality Requirements
N/A for this stub.
11Risks and Technical Debt
N/A for this stub.
12Glossary
| Term | Meaning |
|---|---|
| Rail | A composed runtime path. |
| Reef | The production admission environment. |
| rApp | A packaged workload bound by a declaration contract. |