3.5 KiB
| id | title | status | owner | revision | version | last_reviewed | review_interval |
|---|---|---|---|---|---|---|---|
| railiance-architecture | Railiance architecture | proposed | railiance-master | draft-2 | 0.1 | 2026-08-19 | 6m |
Railiance — Software Architecture Documentation (arc42)
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.
1. Introduction 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. |
2. Architecture Constraints
N/A for this stub.
3. System 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.
4. Solution Strategy
N/A for this stub — repository-prefix architecture and rapp-first wave are already in the ADRs in §9.
5. Building Block View
5.1 Level 1 – System/Top-Level
N/A for this stub.
6. Runtime View
N/A for this stub.
7. Deployment View
N/A for this stub.
8. Cross-Cutting Concepts
N/A for this stub.
9. Architecture 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.
10. Quality Requirements
N/A for this stub.
11. Risks and Technical Debt
N/A for this stub.
12. Glossary
| Term | Meaning |
|---|---|
| Rail | A composed runtime path. |
| Reef | The production admission environment. |
| rApp | A packaged workload bound by a declaration contract. |