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