2026-03-17 23:11:38 +01:00
# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.
---
## One-liner
S3 Platform Services layer of the Railiance OAS Stack — owns shared cluster services: PostgreSQL HA, Valkey cache, secret management, identity integration, and object storage.
---
## Core Idea
Coherence review: Railiance uses one of six OAS dimensions
The central finding. OAS defines six canonical dimensions and states that each
architecture description MUST use them. Railiance has modelled itself almost
entirely on Stack. Everything that did not fit a stack level was treated as an
anomaly - "unplaced", "beside the stack" - and accumulated as exceptions.
They were never anomalies. They are concerns on dimensions Railiance was not
using, and the Quality dimension's sub-levels map almost one-to-one onto the
capability gaps this review found independently: Q2 Observability is
railiance-telemetry, named in canon in exactly those words; Q7 Governance is
the conformance loop; Q3 is restore proof; Q6 is cost attribution. The
self-evidencing thread across five stack layers is five Stack repos each
independently asking for Q2 and Q7 - what a missing dimension looks like from
inside the one you are using.
Also records four contradictions (C1-C4), of which C1 is actionable here: the
hub attributes ~11 capabilities to this repo including Terraform, Ansible, k3s,
CI/CD and app deployment, which S3 does not own. SCOPE.md declares four, all
correctly S3, and is authoritative.
ArgoCD decision closed: keep it, documentation stays accurate; relocating GitOps
to Helix Forge noted as possible future cleanup.
SCOPE.md: corrects the "five independent repos per OAS Stack layer" claim,
records the ArgoCD deployment path, the telemetry emission relationship, and the
hub capability drift.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:53:15 +02:00
Railiance classifies repos along four orthogonal axes — `railiance-*`
(ownership), `rail-*` (execution contract), `rapp-*` (managed workload package),
`reef-*` (substrate boundary). This repo is `railiance-*` , at **S3** on the OAS
Stack dimension: the platform services that multiple applications share. Five
repos cover S1– `railiance-*` repos sit on other OAS dimensions rather
than on the stack. See `ArchitectureBlueprint.md` for the full backbone.
2026-08-15 14:43:44 +02:00
The database operator is CloudNative PG. Bitnami postgresql-ha is retired
(no live release; `make pg-deploy` fail-closed, `RAILIANCE-WP-0016` item 14).
Valkey is a declared capability with no live instance and nothing left in S2
to extract; `make valkey-deploy` is gated until a consumer rapp exists.
2026-07-25 11:22:50 +02:00
OpenBao is a platform capability in this repo, but not every OpenBao-related
2026-07-26 10:39:40 +02:00
file belongs in the long-term S3 ownership home. The deployable package surface
now has a wave-1 repo home in `rapp-openbao` , while this repo retains custody,
policy, and lane governance.
2026-03-17 23:11:38 +01:00
---
## In Scope
2026-03-27 03:06:23 +01:00
- PostgreSQL via CloudNative PG operator (cnpg) — operator deployed, `databases` namespace active
- Valkey / Redis-compatible cache as a standalone Helm release (to be extracted from S2)
2026-05-18 11:53:59 +02:00
- Secret management infrastructure (OpenBao as the platform service,
SOPS/age for Git-at-rest bootstrap material)
2026-03-17 23:11:38 +01:00
- Identity services integration point (with net-kingdom)
- Message brokers (RabbitMQ, similar)
- Object storage (MinIO / S3-compatible)
- Backup and recovery services for platform data
---
2026-05-01 12:35:31 +02:00
## Out of Scope
2026-03-17 23:11:38 +01:00
- OS-level concerns → railiance-infra (S1)
- Kubernetes runtime → railiance-cluster (S2)
- Developer tooling, CI/CD → railiance-enablement (S4)
- Application deployments → railiance-apps (S5)
2026-07-26 10:39:40 +02:00
- Standalone workload-package ownership for OpenBao deployment assets -> `rapp-openbao` , while S3 retains secrets custody and policy
2026-03-17 23:11:38 +01:00
- No re-configuration of S1/S2 concerns from this repo
---
## Relevant When
- Deploying or managing shared services that multiple S5 applications depend on
- Extracting platform services from application Helm subcharts (boundary enforcement)
- S2 cluster is operational and platform layer can now be established
2026-07-25 11:22:50 +02:00
- Defining which OpenBao concerns are workload package assets versus retained platform governance
2026-03-17 23:11:38 +01:00
---
## Not Relevant When
- S2 (cluster runtime) is not yet operational (pre-condition not met)
- Application-specific database schemas or migrations (those belong in S5 apps)
- Infrastructure or cluster work (wrong layer)
---
## Current State
2026-07-26 10:39:40 +02:00
- Status: maintained / emerging
2026-08-15 14:43:44 +02:00
- Implementation: CloudNative PG operator live; `databases` namespace holds the platform clusters; OpenBao is the S3 secrets service. Bitnami postgresql-ha is retired. Valkey is undeployed.
- Stability: emerging — CNPG clusters are live; cache and in-cluster object storage are not
- Usage: shared database and secrets layer; cnpg-system, databases, and openbao namespaces are live
Coherence review: Railiance uses one of six OAS dimensions
The central finding. OAS defines six canonical dimensions and states that each
architecture description MUST use them. Railiance has modelled itself almost
entirely on Stack. Everything that did not fit a stack level was treated as an
anomaly - "unplaced", "beside the stack" - and accumulated as exceptions.
They were never anomalies. They are concerns on dimensions Railiance was not
using, and the Quality dimension's sub-levels map almost one-to-one onto the
capability gaps this review found independently: Q2 Observability is
railiance-telemetry, named in canon in exactly those words; Q7 Governance is
the conformance loop; Q3 is restore proof; Q6 is cost attribution. The
self-evidencing thread across five stack layers is five Stack repos each
independently asking for Q2 and Q7 - what a missing dimension looks like from
inside the one you are using.
Also records four contradictions (C1-C4), of which C1 is actionable here: the
hub attributes ~11 capabilities to this repo including Terraform, Ansible, k3s,
CI/CD and app deployment, which S3 does not own. SCOPE.md declares four, all
correctly S3, and is authoritative.
ArgoCD decision closed: keep it, documentation stays accurate; relocating GitOps
to Helix Forge noted as possible future cleanup.
SCOPE.md: corrects the "five independent repos per OAS Stack layer" claim,
records the ArgoCD deployment path, the telemetry emission relationship, and the
hub capability drift.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:53:15 +02:00
- Deploys via ArgoCD: four Applications (`external-secrets` , `issue-core` ,
`openbao-secretstore` , `target-revenue` ) plus AppProjects under
`argocd/bootstrap/` ; see `docs/argocd-gitops.md`
- Emits to `railiance-telemetry` (Q2 Observability) once the evidence plane
exists — seeded 2026-08-11, not yet implemented
2026-08-15 14:43:44 +02:00
- Open work: Valkey remains a declared-but-unbuilt cache; MinIO is likewise
declared, not deployed. OpenBao package boundary and PAT cutover are
closed. Platform rapp declarations conform (`RAILIANCE-WP-0015` ).
Versioned consumer interfaces: `docs/s3-consumer-interfaces.md` .
2026-08-17 21:57:56 +02:00
Tenancy posture and database placement policy are declared
(`docs/tenancy-posture.md` , `docs/placement-policy.md` , `RPF-WP-0018` ).
Two open items they surfaced: `apps-pg` has no backup configured, and
both shared clusters owe a declared consumer ceiling before their third
consumer. Decisions are now recorded as ADRs in `docs/adr/` (ADR-0003).
Coherence review: Railiance uses one of six OAS dimensions
The central finding. OAS defines six canonical dimensions and states that each
architecture description MUST use them. Railiance has modelled itself almost
entirely on Stack. Everything that did not fit a stack level was treated as an
anomaly - "unplaced", "beside the stack" - and accumulated as exceptions.
They were never anomalies. They are concerns on dimensions Railiance was not
using, and the Quality dimension's sub-levels map almost one-to-one onto the
capability gaps this review found independently: Q2 Observability is
railiance-telemetry, named in canon in exactly those words; Q7 Governance is
the conformance loop; Q3 is restore proof; Q6 is cost attribution. The
self-evidencing thread across five stack layers is five Stack repos each
independently asking for Q2 and Q7 - what a missing dimension looks like from
inside the one you are using.
Also records four contradictions (C1-C4), of which C1 is actionable here: the
hub attributes ~11 capabilities to this repo including Terraform, Ansible, k3s,
CI/CD and app deployment, which S3 does not own. SCOPE.md declares four, all
correctly S3, and is authoritative.
ArgoCD decision closed: keep it, documentation stays accurate; relocating GitOps
to Helix Forge noted as possible future cleanup.
SCOPE.md: corrects the "five independent repos per OAS Stack layer" claim,
records the ArgoCD deployment path, the telemetry emission relationship, and the
hub capability drift.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:53:15 +02:00
- Known drift: State Hub attributes ~11 capabilities to this repo, including
S1/S2/S4/S5 concerns it does not own. The four `capability` blocks in this
file are authoritative; the hub carries stale pre-split attributions
(`ArchitectureBlueprint.md` C1)
2026-03-17 23:11:38 +01:00
---
## How It Fits
- Upstream dependencies: railiance-cluster (S2) — k3s running, Helm available, smoke tests passing
- Downstream consumers: railiance-enablement (S4), railiance-apps (S5) — all depend on platform services
- Often used with: net-kingdom (identity services integration), railiance-cluster (prior layer)
2026-08-11 21:57:36 +02:00
- Emits to: railiance-telemetry (evidence plane) — S3 services are expected to
emit health and readiness through the standard emission contract rather than
per-service bespoke integrations
- Structural backbone: `ArchitectureBlueprint.md` in this repo records the four
repo-family axes, the stack, repository status, and the open placement
decisions that `railiance-master` owns
2026-03-17 23:11:38 +01:00
---
## Terminology
- Preferred terms: OAS Stack Level S3, platform services, boundary rule, migration (extracting from S2 subcharts)
2026-07-26 10:39:40 +02:00
- Potentially confusing terms: "migration" here means moving Helm releases between layers, not database schema migration; `rapp-openbao` packages OpenBao, but it does not own platform custody or policy
2026-03-17 23:11:38 +01:00
---
2026-05-01 12:35:31 +02:00
## Related / Overlapping
2026-03-17 23:11:38 +01:00
- `railiance-cluster` (S2) — pre-condition; PostgreSQL was previously managed here (being extracted to S3)
- `railiance-apps` (S5) — consumes database and cache services from S3
- `net-kingdom` — identity services integration point at the platform layer
---
2026-03-20 23:45:30 +01:00
## Provided Capabilities
```capability
type: infrastructure
2026-03-27 03:06:23 +01:00
title: PostgreSQL via CloudNative PG (cnpg)
description: PostgreSQL database clusters managed by the CloudNative PG operator — shared database service for all platform applications. Operator deployed in cnpg-system namespace; database clusters defined in the databases namespace.
keywords: [postgresql, postgres, cnpg, cloudnative-pg, operator, database, kubernetes]
2026-03-20 23:45:30 +01:00
```
```capability
type: infrastructure
title: Valkey / Redis-compatible cache
2026-08-15 14:43:44 +02:00
description: Declared shared Redis-compatible cache. Not deployed on railiance01 as of 2026-08-15; no S2 instance remains to extract.
2026-03-20 23:45:30 +01:00
keywords: [valkey, redis, cache, shared, session, queue]
```
```capability
type: data
title: Object storage (MinIO / S3-compatible)
description: S3-compatible object storage service (MinIO) for artifact storage, backups, and large file handling across platform applications.
keywords: [minio, s3, object-storage, storage, artifacts, backup]
```
2026-05-18 11:53:59 +02:00
```capability
type: security
title: OpenBao platform secrets service
description: Canonical S3 secrets service for runtime secrets, dynamic credentials, audit, and future workload integrations. SOPS/age remains the bootstrap mechanism for Git-at-rest secrets.
keywords: [openbao, secrets, vault-compatible, secret-management, dynamic-credentials, audit, kubernetes-auth]
```
2026-03-20 23:45:30 +01:00
---
2026-03-17 23:11:38 +01:00
## Getting Oriented
- Start with: `CLAUDE.md` (session protocol, boundary rules)
2026-05-18 11:53:59 +02:00
- Key files / directories: `workplans/RAIL-PL-WP-0001-platform-baseline.md` , `workplans/RAIL-PL-WP-0002-openbao-platform-secrets-service.md` , `helm/` (platform Helm charts), `docs/openbao.md` , `Makefile`
2026-03-27 03:06:23 +01:00
- Pre-conditions: railiance-cluster (S2) converged with k3s running; cluster backup verified before migration steps (`sudo make backup` in railiance-cluster)
