SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

Architecture-definition home for Railiance: repository taxonomy, framework ADRs, cross-repo boundary rules, and cross-repo workplans for architecture changes.

Core Idea

railiance-master is the framework-level architecture repo for Railiance. It exists so shared concepts such as railiance-*, rail-*, rapp-*, and reef-* are defined once, with explicit boundaries, before they spread across implementation repos.

It also serves as the natural workplan home for changes that span multiple Railiance repos and cannot be owned cleanly by only one of them.

In Scope

Framework-level architecture documents for Railiance
Repository taxonomy and naming conventions
Architectural boundaries between ownership repos, rails, rapps, and reefs
Architecture decision records affecting multiple Railiance repos
Cross-repo Railiance workplans whose implementation spans multiple sibling repos

Out of Scope

OS provisioning and host hardening work owned by railiance-infra
Kubernetes runtime implementation owned by railiance-cluster
Platform-service implementation owned by railiance-platform
Application release implementation owned by railiance-apps
Forge runtime implementation owned by railiance-forge
Fabric graph implementation owned by railiance-fabric

Relevant When

Defining a new Railiance repo family or framework term
Clarifying boundaries between existing Railiance repos
Planning migrations that touch multiple Railiance repos
Recording a framework-level architecture decision

Not Relevant When

The work belongs entirely inside one implementation repo
The work is operational rather than architectural
The work is workload-specific rather than framework-wide

Current State

Status: active / evolving
Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave is now being coordinated from this repo
Stability: evolving
Usage: internal Railiance framework architecture home and handoff point for cross-repo planning

The repo now holds the canonical framework decisions and boundary documents for separating rail-*, rapp-*, and reef-* concerns out of the existing Railiance repos. It also now governs the first implementation wave that turns those repo families into concrete repos while downstream ownership repos retain their implementation responsibility.

How It Fits

Upstream dependencies: the-custodian canon and State Hub conventions
Downstream consumers: all railiance-*, future rail-*, future rapp-*, and future reef-* repos
Often used with: railiance-fabric, railiance-platform, railiance-cluster, state-hub

Terminology

Preferred terms: architecture home, repository axis, rail, rapp, reef, ownership repo
Also known as: framework architecture repo
Potentially confusing terms: this repo defines framework structure; it does not implement the lower-layer systems it describes

railiance-fabric — models the ecosystem graph; railiance-master defines framework taxonomy and boundaries
state-hub — indexes and coordinates work; railiance-master provides the framework architecture to be coordinated
repo-scoping — explains what repos are useful for; railiance-master defines how Railiance repo families fit together

Getting Oriented

Start with: README.md, INTENT.md
Key files / directories: docs/, history/, workplans/
Entry points: docs/repository-axes.md, docs/reef-substrate-model.md, docs/adr/

Provided Capabilities

type: documentation
title: Railiance repository taxonomy
description: Defines the canonical Railiance repo families and how ownership repos, rails, managed workloads, and substrate boundaries compose.
keywords: [railiance, architecture, taxonomy, rail, rapp, reef]

type: governance
title: Railiance framework architecture decisions
description: Records framework-level architecture decisions and boundary guidance for changes spanning multiple Railiance repos.
keywords: [architecture, adr, governance, boundaries, framework]

Notes

Use this repo for architecture that must stay shared. Push concrete implementation outward into the ownership repos once the framework boundary is clear.

4.5 KiB Raw Blame History