5.1 KiB
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 developer enablement layer - turning Railiance platform capabilities into paved paths for building, testing, packaging, and promoting workloads.
Why This Exists
A healthy platform does not automatically make delivery easy. Developers and operators still need repeatable ways to build workloads, test them, package them, route them through review, and hand them to application release surfaces without inventing those paths from scratch each time.
Without a disciplined enablement layer:
- every workload invents a different pipeline,
- build and deployment templates drift,
- platform capabilities are hard to consume correctly,
- and application releases depend on undocumented operator memory.
This layer exists to provide paved delivery paths: shared automation, templates, SDKs, build conventions, and self-service workflows that let Railiance evolve faster without dissolving its layer boundaries.
The Mission
Where we are going.
To become the canonical home for developer and delivery enablement - CI/CD pipelines, GitOps workflows, workload templates, SDKs, buildpacks, developer portal surfaces, and promotion conventions that help source repos move safely toward S5 application releases while consuming forge-provided runners, registries, and artifact evidence.
This means:
- Common delivery paths are automated and reusable
- Build and deployment templates encode Railiance platform expectations
- Developers get fast feedback through standard checks and pipelines
- S5 can consume release artifacts through clear handoff contracts
- Forge runtime and runner substrate remain owned by railiance-forge
- Enablement improves delivery without taking ownership of app runtime operation
Core Principles
1. Paved Paths, Not One-Off Pipelines
The default way to build, test, package, and promote a workload should be shared, documented, and easy to reuse.
2. Enablement, Not Applications
This layer helps applications reach production; it does not own their source code, runtime configuration, or user-facing operations.
3. Platform-Aware Templates
Templates, SDKs, and buildpacks should encode the contracts exposed by S1-S3 so consumers do not need to rediscover platform assumptions.
4. Clear Handoff to S5
CI/CD and promotion flows should produce artifacts, metadata, and evidence that the application layer can deploy and verify without guessing.
5. Clear Handoff to Forge
Reusable workflows should state the forge capabilities they require: repository
events, runner labels, package credentials, registry endpoints, and artifact
evidence. This layer defines the reusable workflow shape; railiance-forge
owns the runtime and credentials behind it.
6. Fast Feedback
Developers should learn about broken builds, missing declarations, incompatible interfaces, and release-readiness gaps before those problems reach live application deployments.
7. Boundaries Preserve Velocity
Enablement should make the layered architecture easier to use, not become a shortcut for mutating infrastructure, cluster, platform, or application responsibilities.
What This Is (Conceptually)
This layer is:
- a developer enablement layer
- a home for CI/CD and GitOps workflow patterns
- a source of workload templates, SDKs, and buildpacks
- a promotion handoff surface between source repos and S5 deployments
- a future developer portal and self-service entry point
- a place to codify delivery knowledge into repeatable automation
What This Is Not
This layer is not:
- the infrastructure substrate
- the Kubernetes runtime
- the shared platform-services layer
- the application deployment and operations layer
- the source forge, package/container registry, or runner substrate layer
- the source-code home for business workloads
- a replacement for repo-owned workplans, ADRs, or implementation decisions
It is the delivery machinery that helps the rest of Railiance change safely and repeatedly.
Direction of Evolution
This layer is expected to evolve toward:
- Standard pipeline templates for Railiance workloads
- Reusable build and image promotion conventions
- GitOps workflows with clear review and rollback expectations
- Handoff contracts with
railiance-forgefor runner labels, package credentials, registry endpoints, and artifact evidence - Reusable templates that cite the forge-owned runner/GitOps ownership contract before depending on privileged labels or credentials
- Developer-facing self-service templates and portal entry points
- SDKs and examples that make platform capabilities easy to consume correctly
- Release evidence that S5 can use for deployment readiness
Guiding Question
How can Railiance make the correct delivery path the easiest path, so workloads can move from source to production with speed, evidence, and clear ownership?