Establish Railiance architecture home
This commit is contained in:
codex
parent
dd54aee0da
commit
8022665b35
22 changed files with 2925 additions and 1 deletions
254
docs/repository-axes.md
Normal file
254
docs/repository-axes.md
Normal file
|
|
@ -0,0 +1,254 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue