railiance-master/docs/adr/ADR-0001-repository-prefix-architecture.md

---
id: RMASTER-ADR-0001
title: "Repository Prefix Architecture"
status: accepted
revision: "accepted-1"
owner: railiance-master
last_reviewed: "2026-07-25"
review_interval: 6m
---

# ADR-0001: Repository Prefix Architecture

Date: 2026-07-25
Status: Accepted

## Context

Railiance already has a meaningful set of ownership repos such as
`railiance-infra`, `railiance-cluster`, `railiance-platform`,
`railiance-enablement`, `railiance-apps`, `railiance-forge`, and
`railiance-fabric`.

That structure is useful, but it does not by itself capture all of the
dimensions Railiance now needs.

In particular, the architecture needs clear source-controlled homes for:

- workload execution contracts across different operations architectures,
- managed workload packages as first-class repos,
- and concrete substrate boundaries such as named servers, workstations, or
  grouped environments.

Without that separation, Kubernetes-specific workload semantics remain mixed
into `railiance-cluster`, workload wrappers remain mixed into ownership repos,
and concrete substrates remain under-described.

Railiance also operates inside a wider ecosystem around Railiance, Net Kingdom,
and the Helix Forge software factory. That wider context needs architecture
that can support both exploratory operation and production-grade evolution
without leaving key responsibilities ambiguous.

## Decision

Railiance adopts four canonical repository families:

1. `railiance-*` for ownership and responsibility areas
2. `rail-*` for workload execution contracts
3. `rapp-*` for Railiance-managed workload packages
4. `reef-*` for durable substrate boundaries

The current implementation wave is explicitly centered on `rail-kubernetes` as
the default base rail. Additional rails are introduced only when a concrete
workload has a sound reason to run on a distinct execution architecture.

`rail-knative` is the first expected follow-on rail, motivated by the need to
support `qonto-assistent`, but it should follow the `rail-kubernetes` boundary
cleanup rather than bypass it.

## Meaning Of Each Family

### `railiance-*`

Owns major architectural responsibilities, shared policies, and durable layer
boundaries.

### `rail-*`

Owns how workloads run on a specific execution architecture such as Kubernetes,
Knative, KEDA, Fission, or Nuclio.

In the current phase, `rail-kubernetes` is the default path for platform
services and managed applications.

### `rapp-*`

Owns the managed workload package for one service or application, whether it is
an internal workload or a wrapped upstream product.

Its role is to provide the managed wrapper and scaffolding needed to run that
workload in the Railiance and Net Kingdom context. It does not replace
responsibility ownership.

### `reef-*`

Owns the concrete substrate reality where rails and `rapp`s are bound, such as
a named server, cluster, workstation, or grouped substrate class.

A reef is about purpose-bound compute resources, not merely about individual
machines.

## Consequences

### Positive

- Ownership, execution, workload identity, and substrate identity become
  separate concerns.
- Railiance can support multiple execution architectures without forcing all
  workload semantics into `railiance-cluster`.
- Platform services and applications can both become first-class managed
  workload packages where appropriate.
- Concrete substrates gain a clear architectural home without overloading the
  ownership repos.
- The framework gains a disciplined default path for introducing new rails
  instead of proliferating them speculatively.

### Required Follow-On Work

- Define the initial `rail-*` contracts, starting with `rail-kubernetes`.
- Evolve the current `railiance/app.toml` and overlay pattern into a
  rail-aware, eventually rail-neutral workload packaging contract.
- Identify which current workloads should become `rapp-*` repos.
- Extend `railiance-fabric` so rails, `rapp`s, and reefs become graph-native.
- Define when mixed-rail reefs are acceptable and when clearer substrate
  separation should be preferred.

### Constraints

- `reef-*` must not become a default one-repo-per-machine pattern.
- Generic logic stays in the appropriate ownership repo.
- A named machine gets its own reef only when that machine is itself a durable
  substrate boundary.
- `rapp-*` repos must not become shadow ownership repos.
- Transitional substrate labels should not be canonized before the pattern is
  operationally stable.

## Current Interpretation For Existing Repos

- `railiance-*` repos remain the primary ownership axis.
- Current workload-execution logic in `railiance-cluster` is a candidate to
  migrate into `rail-kubernetes`.
- Current workload wrappers inside `railiance-apps`, `railiance-platform`, or
  `railiance-forge` may evolve into `rapp-*` repos over time.
- Current named substrates such as COULOMBCORE, RAILIANCE01, and WORKSTATION
  may justify `reef-*` repos when they represent real operational boundaries.
- A reef may host more than one rail in early or mixed environments, but
  production-critical substrates should prefer clearer purpose and primary-rail
  boundaries unless a mixed design is justified.

## Notes

This ADR defines the repository taxonomy. It does not yet mandate a full
migration or rename of existing repos. Migration should happen when it produces
clearer ownership and lower ambiguity, not merely for naming purity.