<divclass="wrap"><header><divclass="eyebrow"><span>RMASTER-ADR-0001</span><spanclass="stat">accepted · accepted-1</span><span>railiance-master</span><span>reviewed 2026-07-25</span><span>generated from canonical source — do not edit</span></div><h1>Repository Prefix Architecture</h1><pclass="sub">Source: <code>railiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · 5ffd7d1b40d56249f490a318e728047fd3517c4c</code></p><pclass="sub">Review due: 2027-01-25</p></header><divclass="layout"><navclass="rail"aria-label="Sections"><ol><li><ahref="#context"><spanclass="n">·</span>Context</a></li><li><ahref="#decision"><spanclass="n">·</span>Decision</a></li><li><ahref="#meaning-of-each-family"><spanclass="n">·</span>Meaning Of Each Family</a></li><li><ahref="#consequences"><spanclass="n">·</span>Consequences</a></li><li><ahref="#current-interpretation-for-existing-repos"><spanclass="n">·</span>Current Interpretation For Existing Repos</a></li><li><ahref="#notes"><spanclass="n">·</span>Notes</a></li></ol></nav><main><p>Date: 2026-07-25 Status: Accepted</p>
<p>Railiance already has a meaningful set of ownership repos such as <code>railiance-infra</code>, <code>railiance-cluster</code>, <code>railiance-platform</code>, <code>railiance-enablement</code>, <code>railiance-apps</code>, <code>railiance-forge</code>, and <code>railiance-fabric</code>.</p>
<p>That structure is useful, but it does not by itself capture all of the dimensions Railiance now needs.</p>
<p>In particular, the architecture needs clear source-controlled homes for:</p>
<ul><li>workload execution contracts across different operations architectures,</li><li>managed workload packages as first-class repos,</li><li>and concrete substrate boundaries such as named servers, workstations, or grouped environments.</li></ul>
<p>Without that separation, Kubernetes-specific workload semantics remain mixed into <code>railiance-cluster</code>, workload wrappers remain mixed into ownership repos, and concrete substrates remain under-described.</p>
<p>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.</p>
</section>
<sectionid="decision"><h2>Decision</h2>
<p>Railiance adopts four canonical repository families:</p>
<ol><li><code>railiance-*</code> for ownership and responsibility areas</li><li><code>rail-*</code> for workload execution contracts</li><li><code>rapp-*</code> for Railiance-managed workload packages</li><li><code>reef-*</code> for durable substrate boundaries</li></ol>
<p>The current implementation wave is explicitly centered on <code>rail-kubernetes</code> 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.</p>
<p><code>rail-knative</code> is the first expected follow-on rail, motivated by the need to support <code>qonto-assistent</code>, but it should follow the <code>rail-kubernetes</code> boundary cleanup rather than bypass it.</p>
</section>
<sectionid="meaning-of-each-family"><h2>Meaning Of Each Family</h2>
<h3><code>railiance-*</code></h3>
<p>Owns major architectural responsibilities, shared policies, and durable layer boundaries.</p>
<h3><code>rail-*</code></h3>
<p>Owns how workloads run on a specific execution architecture such as Kubernetes, Knative, KEDA, Fission, or Nuclio.</p>
<p>In the current phase, <code>rail-kubernetes</code> is the default path for platform services and managed applications.</p>
<h3><code>rapp-*</code></h3>
<p>Owns the managed workload package for one service or application, whether it is an internal workload or a wrapped upstream product.</p>
<p>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.</p>
<h3><code>reef-*</code></h3>
<p>Owns the concrete substrate reality where rails and <code>rapp</code>s are bound, such as a named server, cluster, workstation, or grouped substrate class.</p>
<p>A reef is about purpose-bound compute resources, not merely about individual machines.</p>
</section>
<sectionid="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>Ownership, execution, workload identity, and substrate identity become separate concerns.</li><li>Railiance can support multiple execution architectures without forcing all workload semantics into <code>railiance-cluster</code>.</li><li>Platform services and applications can both become first-class managed workload packages where appropriate.</li><li>Concrete substrates gain a clear architectural home without overloading the ownership repos.</li><li>The framework gains a disciplined default path for introducing new rails instead of proliferating them speculatively.</li></ul>
<h3>Required Follow-On Work</h3>
<ul><li>Define the initial <code>rail-*</code> contracts, starting with <code>rail-kubernetes</code>.</li><li>Evolve the current <code>railiance/app.toml</code> and overlay pattern into a rail-aware, eventually rail-neutral workload packaging contract.</li><li>Identify which current workloads should become <code>rapp-*</code> repos.</li><li>Extend <code>railiance-fabric</code> so rails, <code>rapp</code>s, and reefs become graph-native.</li><li>Define when mixed-rail reefs are acceptable and when clearer substrate separation should be preferred.</li></ul>
<h3>Constraints</h3>
<ul><li><code>reef-*</code> must not become a default one-repo-per-machine pattern.</li><li>Generic logic stays in the appropriate ownership repo.</li><li>A named machine gets its own reef only when that machine is itself a durable substrate boundary.</li><li><code>rapp-*</code> repos must not become shadow ownership repos.</li><li>Transitional substrate labels should not be canonized before the pattern is operationally stable.</li></ul>
</section>
<sectionid="current-interpretation-for-existing-repos"><h2>Current Interpretation For Existing Repos</h2>
<ul><li><code>railiance-*</code> repos remain the primary ownership axis.</li><li>Current workload-execution logic in <code>railiance-cluster</code> is a candidate to migrate into <code>rail-kubernetes</code>.</li><li>Current workload wrappers inside <code>railiance-apps</code>, <code>railiance-platform</code>, or <code>railiance-forge</code> may evolve into <code>rapp-*</code> repos over time.</li><li>Current named substrates such as COULOMBCORE, RAILIANCE01, and WORKSTATION may justify <code>reef-*</code> repos when they represent real operational boundaries.</li><li>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.</li></ul>
</section>
<sectionid="notes"><h2>Notes</h2>
<p>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.</p>
