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 is structured as five independent repos per OAS Stack layer. This repo is S3 — the platform services that multiple applications share. The active migration is from Bitnami postgresql-ha (repmgr + pgpool, currently a Gitea subchart in S2) to CloudNative PG (cnpg operator, already deployed in the cnpg-system namespace) as the canonical database operator. Valkey cluster is also in scope for S3 extraction from S2.

---

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
• 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 (per ADR-003)

• OS-level concerns → railiance-infra (S1)
• Kubernetes runtime → railiance-cluster (S2)
• Developer tooling, CI/CD → railiance-enablement (S4)
• Application deployments → railiance-apps (S5)
• 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

---

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: active / emerging
• Implementation: CloudNative PG operator (cnpg) deployed; databases namespace active; Valkey + legacy postgresql-ha extraction from S2 in progress (RAIL-PL-WP-0001)
• Stability: emerging — cnpg deployed but database cluster definitions not yet migrated from S2
• Usage: will be the shared database and cache layer; currently cnpg-system + databases namespaces are live

---

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)

---

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

---

Related / Overlapping Repositories

• 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: Shared Redis-compatible cache service (Valkey) for all applications in the Railiance stack.
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]

---

Getting Oriented

• Start with: CLAUDE.md (session protocol, boundary rules)
• Key files / directories: workplans/RAIL-PL-WP-0001-platform-baseline.md, helm/ (platform Helm charts), Makefile
• Pre-conditions: railiance-cluster (S2) converged with k3s running; cluster backup verified before migration steps (sudo make backup in railiance-cluster)