From 37d8b6b47ead5ff104af4b8d8dae4d7a57cfe9c1 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Tue, 17 Mar 2026 23:11:38 +0100
Subject: [PATCH] docs: add SCOPE.md for rapid orientation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 SCOPE.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 SCOPE.md

diff --git a/SCOPE.md b/SCOPE.md
new file mode 100644
index 0000000..42d573e
--- /dev/null
+++ b/SCOPE.md
@@ -0,0 +1,95 @@
+# 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
+
+---
+
+## 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