Establish Railiance architecture home

docs/rapp-first-wave-candidates.md

@@ -0,0 +1,169 @@
+# First-Wave `rapp-*` Candidates
+
+Date: 2026-07-25
+
+## Purpose
+
+Choose and order the first `rapp-*` candidates for Railiance.
+
+`rapp-*` repos are for managed workload packaging and scaffolding. They are not
+new ownership homes. The decision here is therefore not "which repos are
+important?" but "which workloads already have a strong enough package boundary
+to become first-class managed wrappers without weakening ownership?"
+
+## Selection Criteria
+
+The first-wave candidates should satisfy most of the following:
+
+- stable workload identity
+- clear upstream or source workload boundary
+- clear Kubernetes package surface already visible in Git
+- explicit runtime-secret and dependency handling
+- deploy, verify, and recover behavior already described
+- low ambiguity between packaging ownership and domain ownership
+- good demonstration value for later `rapp-*` extractions
+
+## Assessed Candidates
+
+### 1. OpenBao from `railiance-platform`
+
+Assessment: **choose first**
+
+Why it fits:
+
+- It is a clear third-party upstream product with durable identity.
+- The workload already has a substantial Railiance packaging surface:
+  `helm/openbao-values.yaml`, middleware, UI overlay assets, deploy/verify
+  scripts, and operator runbooks.
+- The repo already distinguishes between the OpenBao workload itself and the
+  wider S3 platform policy that consumes it.
+- It is important enough to prove that `rapp-*` is not only for user-facing
+  apps; platform services can also be managed workloads.
+
+What should move into `rapp-openbao`:
+
+- Helm values and Kubernetes-facing package assets for the OpenBao workload
+- UI overlay wrapper assets
+- generic deploy, verify, and workload-health runbooks
+- workload-specific smoke and recovery expectations
+
+What should remain in `railiance-platform`:
+
+- the S3 ownership of secrets custody as a platform capability
+- workload lane policy, credential approval, and platform-wide access models
+- cross-workload secret-delivery conventions consumed by many workloads
+
+Conclusion:
+
+`rapp-openbao` should be the first `rapp-*` extraction.
+
+### 2. Forge workload from `railiance-forge`
+
+Assessment: **defer from first wave**
+
+Why it is not first:
+
+- The current live workload is still Gitea on CoulombCore.
+- The intended production direction is Forgejo on Railiance01.
+- Packaging identity is therefore not stable enough yet: extracting now would
+  either enshrine a temporary Gitea compatibility package or pretend the
+  Forgejo cutover is already complete.
+- The runtime and migration story still spans current Gitea operation, future
+  Forgejo deployment, runner substrate, registries, and cutover sequencing.
+
+Decision:
+
+- Do **not** make the forge workload the first `rapp-*` extraction.
+- Prefer `rapp-forgejo` as the eventual target package once the production
+  direction is the real operating target.
+- Create `rapp-gitea` only if Railiance discovers it needs a long-lived
+  compatibility wrapper for the current workload rather than a short migration
+  bridge.
+
+What this means:
+
+- `railiance-forge` keeps runtime ownership for now.
+- The forge wrapper should follow after the current Gitea-versus-Forgejo
+  packaging identity stops moving.
+
+Conclusion:
+
+The forge workload is packaging-worthy, but it should not be first-wave
+`rapp-*`.
+
+### 3. User-facing S5 workload from `railiance-apps`
+
+Assessment: **choose `vergabe-teilnahme` for wave 1**
+
+Why `vergabe-teilnahme` wins the S5 slot:
+
+- It is clearly user-facing and already operates as one named workload package.
+- Its release surface is explicit: chart, values, ingress, deployment targets,
+  migration command, smoke checks, and operator runbook.
+- Secret handling is clear without being entangled with shared platform
+  semantics: app credentials are consumed from Kubernetes Secrets and the app
+  env secret is locally rebuilt by operator procedure.
+- It is simpler and more stable than the current Core Hub / Inter-Hub history
+  and more obviously user-facing than service-style workloads such as
+  `reuse-surface`.
+
+What should move into `rapp-vergabe-teilnahme`:
+
+- the chart and workload values
+- the ingress and app-specific release runbook
+- workload-specific rollout, migration, smoke, and rollback guidance
+- workload-specific secret consumption contract
+
+What should remain in `railiance-apps`:
+
+- S5 ownership of generic application release patterns
+- reusable onboarding and operator recipes
+- cross-app S5 guardrails that should not be duplicated per workload package
+
+Second-wave S5 note:
+
+- `reuse-surface` is the strongest follow-on self-built service candidate after
+  `vergabe-teilnahme`, because it already shows explicit OpenBao-backed runtime
+  secret lanes and a tidy single-workload chart surface.
+- `core-hub` and retired `inter-hub` should wait because their packaging
+  history is still entangled with cutover and legacy service evolution.
+
+Conclusion:
+
+`rapp-vergabe-teilnahme` should be the first user-facing S5 `rapp-*`.
+
+## First-Wave Order
+
+The recommended order is:
+
+1. `rapp-openbao`
+2. `rapp-vergabe-teilnahme`
+3. `rapp-forgejo` after the forge runtime target is stable enough to avoid
+   immediate rename or migration churn
+
+This order is intentional.
+
+- `rapp-openbao` proves the third-party platform-service wrapper model.
+- `rapp-vergabe-teilnahme` proves the self-built user-facing app wrapper model.
+- The forge wrapper then follows with a clearer target identity and after the
+  first two wrappers have established the pattern.
+
+## Risks To Watch
+
+- If `rapp-openbao` absorbs platform-wide policy and credential-governance
+  logic, the wrapper will become a shadow S3 repo.
+- If `rapp-vergabe-teilnahme` absorbs generic S5 onboarding or app recipes, it
+  will weaken `railiance-apps` as the shared S5 release home.
+- If the forge wrapper is extracted too early, Railiance will immediately face
+  a Gitea-versus-Forgejo package rename or parallel-wrapper problem.
+
+## Outcome
+
+Railiance now has a concrete first-wave `rapp-*` sequence:
+
+- first `rapp-openbao`
+- then `rapp-vergabe-teilnahme`
+- then the forge wrapper once the production package identity is stable
+
+That is enough to start repo-local extraction planning without pretending every
+workload needs its own `rapp` immediately.