Repository Prefix Architecture

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