## 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

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.

## 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
`RMASTER-ADR-0009` | accepted | NetKingdom security-layer interaction

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.