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. PostgreSQL HA (repmgr + pgpool) and Valkey (Redis-compatible cache) are the first services being extracted here, moved from the Gitea subchart in S2 into standalone Helm releases under S3 so the boundary rule is properly enforced.

---

## In Scope

- PostgreSQL HA (repmgr + pgpool) as a standalone Helm release
- Valkey / Redis-compatible cache as a standalone Helm release
- 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: PostgreSQL HA + Valkey extraction from S2 in progress (RAIL-PL-WP-0001)
- Stability: emerging — first platform workplan active
- Usage: shared database and cache services for all S5 applications

---

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

```capability
type: infrastructure
title: PostgreSQL HA (repmgr + pgpool)
description: Highly available PostgreSQL cluster using repmgr for replication and pgpool for connection pooling — shared database service for all platform applications.
keywords: [postgresql, postgres, ha, repmgr, pgpool, database, replication]
```

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

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

---

## 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; active backup on Nextcloud before migration steps