railiance-apps/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

S5 Workloads & Experience layer of the Railiance OAS Stack — owns application Helm releases and Kubernetes manifests for user-facing services (Gitea, coulomb services, web frontends).

---

## Core Idea

Railiance is structured as five independent repos, one per OAS (Open Application Stack) layer. This repo is S5 — the top layer. It owns application-level deployments: Helm values and manifests for Gitea, coulomb services, APIs, and web portals. It depends on S1–S4 being operational before it can do anything.

---

## In Scope

- Application Helm releases: Gitea, coulomb services, web portals, APIs
- Kubernetes manifests for user-facing workloads
- Application-level configuration and deployment orchestration

---

## Out of Scope

- OS-level concerns → railiance-infra (S1)
- Kubernetes runtime → railiance-cluster (S2)
- Platform services (PostgreSQL, caches, storage) → railiance-platform (S3)
- Developer tooling (CI/CD, portals) → railiance-enablement (S4)
- No re-configuration of lower layers from this repo

---

## Relevant When

- Deploying or updating user-facing applications in the Railiance stack
- S1–S4 are all operational and it's time to deploy workloads

---

## Not Relevant When

- S1–S4 are not yet operational (pre-conditions not met)
- Infrastructure, cluster, or platform work needed (wrong layer)
- No user-facing applications to deploy

---

## Current State

- Status: active (Gitea Helm values now owned by S5; boundary violation resolved)
- Implementation: Gitea is deployed and operational. Helm values (`helm/gitea-values.sops.yaml`) are now managed from this repo (S5) — moved from railiance-cluster in RAIL-HO-WP-0004-T06. Gitea uses an external cnpg database (`gitea-db` in the `databases` namespace) and standalone Valkey.
- Stability: Gitea stable; S5 layer now owns the Gitea deployment lifecycle
- Usage: Gitea serves as the git hosting platform for all Railiance and Custodian repos

---

## How It Fits

- Upstream dependencies: railiance-infra (S1) → railiance-cluster (S2) → railiance-platform (S3) → railiance-enablement (S4) → this repo (S5)
- Downstream consumers: end users accessing Gitea, coulomb services, web portals
- Often used with: railiance-platform (database/cache backends), net-kingdom (identity for apps)

---

## Terminology

- Preferred terms: OAS Stack Level S5, workloads, experience endpoints, boundary rule
- Potentially confusing terms: "S5" is a stack level designation, not a version

---

## Related / Overlapping

- `railiance-platform` (S3) — provides database, cache, identity services consumed by S5 apps
- `railiance-enablement` (S4) — provides CI/CD and templates that S5 uses
- `railiance-cluster` (S2) — Kubernetes runtime where S5 workloads run

---

## Provided Capabilities

```capability
type: infrastructure
title: Application workload deployment (Gitea, coulomb services)
description: Deploy and manage user-facing applications — Gitea, coulomb services, APIs, and web portals — as Helm releases on the Railiance Kubernetes cluster.
keywords: [gitea, coulomb, webapp, helm, application, deployment, workload]
```

---

## Getting Oriented

- Start with: `CLAUDE.md` (session protocol, boundary rules)
- Key files / directories: `workplans/` (currently empty), `Makefile`
- Pre-conditions: all four lower layers (S1–S4) must be converged and verified
- Key files: `helm/gitea-values.sops.yaml` (Gitea Helm values, SOPS-encrypted), `releases/gitea/values.yaml` (legacy plain values — superseded)