railiance-platform/SCOPE.md

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

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–S5; other railiance-* repos sit on other OAS dimensions rather than on the stack. See ArchitectureBlueprint.md for the full backbone.

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.

OpenBao is a platform capability in this repo, but not every OpenBao-related 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.

---

In Scope

• 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)
• Secret management infrastructure (OpenBao as the platform service, SOPS/age for Git-at-rest bootstrap material)
• Identity services integration point (with net-kingdom)
• Message brokers (RabbitMQ, similar)
• Object storage (MinIO / S3-compatible)
• Backup and recovery services for platform data

---

Out of Scope

• OS-level concerns → railiance-infra (S1)
• Kubernetes runtime → railiance-cluster (S2)
• Developer tooling, CI/CD → railiance-enablement (S4)
• Application deployments → railiance-apps (S5)
• Standalone workload-package ownership for OpenBao deployment assets -> rapp-openbao, while S3 retains secrets custody and policy
• 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
• Defining which OpenBao concerns are workload package assets versus retained platform governance

---

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

• Status: maintained / emerging
• 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
• 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
• 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. 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).
• 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)

---

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)
• 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

---

Terminology

• Preferred terms: OAS Stack Level S3, platform services, boundary rule, migration (extracting from S2 subcharts)
• 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

---

Related / Overlapping

• 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

---

Provided Capabilities

type: infrastructure
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]

type: infrastructure
title: Valkey / Redis-compatible cache
description: Declared shared Redis-compatible cache. Not deployed on railiance01 as of 2026-08-15; no S2 instance remains to extract.
keywords: [valkey, redis, cache, shared, session, queue]

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]

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]

---

Getting Oriented

• Start with: CLAUDE.md (session protocol, boundary rules)
• 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
• Pre-conditions: railiance-cluster (S2) converged with k3s running; cluster backup verified before migration steps (sudo make backup in railiance-cluster)