# INTENT

> This file captures **why this repository exists**,
> the **direction it is moving toward**, and
> the **kind of system it is meant to become**.
> It is intentionally **aspirational and stable**, not a description of current implementation.

---

## One-liner

**The application workload layer - turning platform capabilities into reliable, user-facing Railiance services with repeatable release operations.**

---

## Why This Exists

A converged platform is not yet a useful experience for users.
Someone must take shared runtime, data, identity, registry, and enablement
capabilities and turn them into deployed workloads with clear release
configuration, operator runbooks, and app-level verification.

Without a disciplined application layer:

* deployment concerns scatter across source repos and live clusters,
* lower-layer boundaries blur when apps need "just one" platform tweak,
* operators rediscover the same ingress, secret, probe, and registry traps,
* and user-facing services become difficult to promote, debug, and recover.

This layer exists to make application releases **repeatable, bounded, and
operable**, so Railiance can add services without turning every deployment into
a new archaeology exercise.

---

## The Mission

> *Where we are going.*

To become the **canonical home for Railiance application workload releases** -
the Helm values, Kubernetes manifests, registry enablement, app-level runbooks,
smoke checks, and operator recipes that make user-facing services safe to ship
on top of the platform.

This means:

* Application deployments have **source-controlled release contracts**
* Operators can deploy, verify, and recover apps through **repeatable runbooks**
* Apps consume lower-layer capabilities through **stable handoff points**
* Source application repos remain responsible for their code, packages, and
  build artifacts
* The first-app lessons become **reusable patterns** for the next app

---

## Core Principles

### 1. Workloads, Not Runtime

Own the application releases that run on the platform. Do not own the
infrastructure, cluster runtime, or shared platform services beneath them.

### 2. Release Contracts over Source Internals

This repo should describe how an application is released and operated on
Railiance, not become the application's source-code repository.

### 3. Repeatable Operations

Deploys, upgrades, smoke tests, migrations, and emergency checks should be
codified as scripts, Make targets, and runbooks rather than remembered by
operators.

### 4. Clear Lower-Layer Handoffs

Applications consume databases, secrets, storage, identity, and runtime
capabilities through explicit contracts with S1-S4. This layer does not reach
down and mutate those layers to make an app work.

### 5. Evidence Before Confidence

An app release is healthy when probes, status checks, smoke tests, and operator
evidence say it is healthy, not merely because manifests applied successfully.

### 6. Current Workload, Future Path

Gitea and early application releases are current S5 workloads and learning
surfaces. Their lessons should leave behind reusable deployment patterns that
survive future forge and app migrations.

---

## What This Is (Conceptually)

This layer is:

* an **application workload release** layer
* a home for **Helm release configuration** and app-level manifests
* an **operator runbook** and deployment guardrail surface
* a bridge from shared platform capabilities to **user-facing services**
* a place where app deployment lessons become **reusable S5 patterns**

---

## What This Is Not

This layer is not:

* the infrastructure substrate beneath Railiance
* the Kubernetes runtime or cluster addon layer
* the shared platform-services layer for databases, secrets, cache, or storage
* the CI/CD and developer enablement layer
* the source-code home for deployed applications
* a secret custody authority

It is the **last-mile release and operations surface** for services users
actually touch.

---

## Direction of Evolution

This layer is expected to evolve toward:

* A reusable **new S5 app release checklist**
* Stronger **image and package promotion** patterns
* Clearer **backup, restore, and data ownership handoffs** with S3
* More complete **smoke, migration, rollback, and observability** recipes
* Cleaner separation between **current forge operation** and future forge
  migration paths
* Self-evidencing, reviewable **application readiness** before promotion

---

## Guiding Question

> **How can each Railiance application become easy to release, verify, operate, and recover without weakening the boundaries of the layers beneath it?**