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`.
- 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

```capability
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]
```

```capability
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]
```

```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]
```

```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]
```

---

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