# 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, 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. App Workloads, Forge Consumers

Applications consume forge artifacts without owning forge runtime state. Early
application releases 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 consumption of **forge-owned artifacts and evidence** from app
  release runbooks
* 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?**