254 lines
8.3 KiB
Markdown
254 lines
8.3 KiB
Markdown
# 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 `rapp`s
|
|
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 `rapp`s 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 `rapp`s 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, `rapp`s, 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.
|