150 lines
3.5 KiB
Markdown
150 lines
3.5 KiB
Markdown
---
|
||
id: railiance-architecture
|
||
title: "Railiance architecture"
|
||
status: proposed
|
||
owner: railiance-master
|
||
revision: "draft-2"
|
||
version: "0.1"
|
||
last_reviewed: "2026-08-19"
|
||
review_interval: 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
|
||
|
||
1. Reviewable boundary decisions.
|
||
2. Private-by-default exposure until admission.
|
||
3. 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. |
|