railiance-master/docs/repository-axes.md

Repository Axes In Railiance

Date: 2026-07-25

Purpose

Railiance needs more than one way to classify repositories.

The existing stack already expresses ownership and responsibility well, but it does not yet cleanly express:

• how workloads are executed on different operations architectures,
• how a managed workload package is represented as its own repo,
• and how a concrete substrate or deployment reality is represented.

This document defines the canonical repository axes for Railiance.

Current Architectural Stance

The taxonomy is intentionally broader than the current implementation wave.

For the current phase of Railiance:

• rail-kubernetes is the default and first-class base rail for platform services and managed applications.
• Additional rails should be introduced only when a concrete workload has a sound reason to run better on a different execution architecture.
• rail-knative is the first expected follow-on rail, driven by the need to run qonto-assistent, but it should follow the rail-kubernetes boundary cleanup rather than bypass it.

This means the repo model is intentionally ahead of the repo count.

The Four Repo Families

Prefix	Axis	Unit	Primary question answered
railiance-*	ownership and responsibility	one architectural responsibility area	who owns this capability or layer?
rail-*	execution contract	one workload execution architecture	how does a workload run here?
rapp-*	managed workload package	one Railiance-managed workload	what exactly is being packaged and operated?
reef-*	substrate boundary	one durable substrate reality	where does this run and what is bound there?

These families are complementary, not competing.

1. railiance-*: Responsibility Repos

railiance-* repos are the long-lived architectural homes for major responsibility areas.

Examples:

• railiance-infra
• railiance-cluster
• railiance-platform
• railiance-enablement
• railiance-apps
• railiance-forge
• railiance-fabric
• railiance-master

They answer questions such as:

• Which layer owns this concern?
• Where do the shared rules, runbooks, and contracts live?
• Which team or operator domain is responsible for correctness?

They should not be multiplied per host, per workload, or per execution mode.

2. rail-*: Execution-Contract Repos

rail-* repos define how Railiance-managed workloads run on a specific operations architecture.

Examples:

• rail-kubernetes
• rail-knative
• rail-keda
• rail-fission
• rail-nuclio

A rail owns the execution semantics for workloads on that architecture:

• packaging expectations
• deployment adapters
• autoscaling and traffic behavior
• health and observability contract
• promotion and rollback behavior
• rail-specific templates and compatibility rules

A rail is not the workload itself and not the substrate it runs on.

In the current Railiance model, rail-kubernetes is the default base rail. Other rails should be introduced only when their runtime semantics justify a distinct lifecycle, contract, or operator model.

That makes the first question for a new rail:

• does this workload truly need a different rail,
• or does it only need an adapter or profile on the current Kubernetes path?

3. rapp-*: Managed Workload Package Repos

rapp-* repos represent Railiance-managed workloads as first-class packages.

Examples:

• rapp-openbao
• rapp-forgejo
• rapp-vergabe-teilnahme

A rapp may wrap:

• an upstream third-party product,
• an internal service,
• a user-facing application,
• or a platform service operated as a workload.

Its purpose is to provide the scaffolding needed to run that workload as a fully managed component in the Railiance and Net Kingdom operating context, including the Helix Forge software-factory environment that produces and runs parts of that ecosystem.

A rapp owns:

• the Railiance packaging of the workload
• rail compatibility declarations
• workload-specific health checks and smoke checks
• workload-specific rollout and rollback expectations
• secret references, dependency declarations, and data handoff expectations

A rapp does not replace the responsibility repo that owns the broader domain. It is explicitly about managed wrapping, not ownership.

For example:

• railiance-platform may own why OpenBao exists as an S3 platform capability
• rapp-openbao may own how OpenBao is packaged and operated as a managed workload

4. reef-*: Substrate-Boundary Repos

reef-* repos represent concrete substrate realities where rails and rapps are bound.

Examples:

• reef-coulombcore
• reef-railiance01
• reef-workstation
• reef-ops-workstations

A reef answers questions such as:

• What is this substrate?
• Which hosts, clusters, namespaces, or operator machines compose it?
• Which rails are installed or allowed here?
• Which rapps are bound to it?
• Which access paths, overlays, and local runbooks apply here?

A reef does not replace railiance-infra, railiance-cluster, or railiance-platform. It composes them into a named operational reality.

In practice, a reef represents compute resources organized for a defined purpose.

One reef may host multiple rails in early-stage, experimental, prototyping, or preproduction situations. For production-grade or premium-security use, the better default is clearer substrate separation and an explicit primary rail per reef unless a mixed-rail design is deliberately justified.

How The Axes Compose

The same deployed reality may appear across all four axes for different reasons.

Example: OpenBao on COULOMBCORE

• railiance-platform owns the platform-service responsibility and policy
• rail-kubernetes defines the Kubernetes execution contract
• rapp-openbao defines the managed workload package
• reef-coulombcore records that this substrate offers that rail and binds that rapp

This separation reduces confusion between:

• ownership
• execution mode
• workload identity
• deployment location

Creation Rules

Use the following default rules.

Create or extend a railiance-* repo when:

• the concern is a stable responsibility area,
• multiple workloads share the same owner and policy boundary,
• or the repo must remain the canonical home for a layer or cross-cutting capability.

Create a rail-* repo when:

• a workload execution architecture has distinct runtime semantics,
• workloads need architecture-specific templates or promotion behavior,
• or the current railiance-cluster contract would become too Kubernetes-only.

Default bias:

• first stabilize rail-kubernetes
• then add another rail only when a concrete workload needs it

Create a rapp-* repo when:

• a workload should be managed as a first-class package,
• the workload has its own compatibility, rollout, or recovery contract,
• or wrapping logic should be kept separate from both the upstream source and the generic ownership repo.

Do not create a rapp merely to duplicate a responsibility home that already belongs in a railiance-* repo.

Create a reef-* repo when:

• there is a durable substrate boundary with its own lifecycle,
• rails and rapps need to be bound to a named operational reality,
• substrate-specific overlays or evidence must be tracked,
• or operators need a source-controlled home for that environment.

Do not create a reef only because a single machine happens to exist. The substrate needs a durable purpose.

Migration Direction From The Current Repo Set

The current Railiance repos already provide the ownership axis.

The likely next architecture moves are:

1. Move Kubernetes-specific workload execution contracts out of railiance-cluster into rail-kubernetes.
2. Split first-class workload wrappers out of railiance-apps, railiance-platform, and railiance-forge into rapp-* repos where the workload deserves an independent lifecycle.
3. Introduce reef-* repos only for real substrate boundaries, not as a default per-machine pattern.
4. Extend railiance-fabric so rails, rapps, and reefs become first-class graph objects rather than implicit naming conventions.

Open Discipline

Railiance should resist naming every observed pattern too early.

This especially applies to loosely associated or transitional compute resources. Terms for such substrates should stay descriptive until there is a stable operational pattern worth canonizing in the taxonomy.