8.4 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 authoritative source for Railiance framework architecture — turning evolving repo families, workload models, and substrate realities into coherent, reviewable, and permanently publishable boundary decisions.
Why This Exists
As Railiance grows, implementation repos naturally solve immediate problems: infrastructure, cluster runtime, platform services, forge operations, application releases, and ecosystem modeling.
What those repos cannot safely do on their own is define the framework's shared meaning.
Without a canonical architecture home:
- the same terms drift across repos,
- new repo families appear without clear boundaries,
- execution models and workload wrappers get mixed into the wrong layers,
- and migrations happen by local habit rather than deliberate framework design.
This repository exists to define the shared architectural language of Railiance before that language hardens accidentally inside implementation repos.
Operating Context
Railiance does not exist in isolation.
It is part of a wider, coevolving ecosystem around Railiance, Net Kingdom, and the Helix Forge software factory. That ecosystem is intended to support the full path from:
- product ideation,
- discovery,
- delivery,
- operation,
- marketing,
- and monetization.
The architecture therefore has to work across experimental and production-grade realities at the same time.
That matters because repo boundaries in Railiance are not only about code organization. They shape how humans and agents coordinate responsibilities, reason about workload placement, and evolve operating models without losing the ability to scale into more mature security and delivery expectations.
Railiance also participates in two wider governance structures:
- InfoTechCanon owns the general semantic models, standards, and repository conventions that Railiance adopts. This repository imports those concepts and applies them to Railiance; it does not redefine the canon by local usage.
policy-nexusowns permanent publication, addressing, history, and currency for estate policy. This repository remains the source and ratification home for its architecture decision records. Publication is generated downstream and never written back here.
That separation matters. Content authority, semantic canon, and publication infrastructure are related responsibilities, not one responsibility hidden in three repositories.
The Mission
Where we are going.
To become the canonical home for Railiance framework architecture — where repository taxonomy, architectural boundaries, execution-model concepts, managed workload patterns, substrate concepts, and migration direction are defined once, reviewed here, published durably when governing, and referenced everywhere else.
This means:
- Railiance vocabulary is defined through explicit architectural documents
- New repo families and framework terms are introduced through clear decisions
- Ownership, execution mode, workload identity, and substrate identity remain separate and composable
- Explorations mature into stable decisions before they spread across the wider repo landscape
- Governing ADRs carry enough ownership, revision, status, and review metadata to be published without a second source of truth
- The framework can support both early-stage experimentation and production-grade operation without collapsing those needs into one vague structure
Core Principles
1. Architecture Before Proliferation
New repo patterns should be named and bounded deliberately before they multiply across the ecosystem.
2. Shared Vocabulary Is Infrastructure
Terms such as railiance-*, rail-*, rapp-*, and reef-* are not cosmetic.
They shape ownership, tooling, and operator understanding.
3. Separate Axes Cleanly
Ownership, execution architecture, workload packaging, and substrate reality must not collapse into one ambiguous repo type.
4. Decisions Need A Canonical Home
Framework-level architecture decisions should live in one source-controlled place rather than being reconstructed from scattered repo-local assumptions.
5. Stable Meaning, Evolvable Model
The framework vocabulary should stay understandable over time even as specific rails, workloads, and substrates evolve.
6. Guide Implementation, Do Not Shadow It
This repo should define structure and direction, not absorb the operational content that belongs in the implementation repos themselves.
7. Stabilize The Default Path First
Railiance should not introduce multiple top-level rails speculatively.
The default path for platform services and managed applications is
rail-kubernetes until there is a concrete workload need and a sound argument
for a distinct rail.
8. Managed Packaging Is Not Ownership
rapp-* repos exist to wrap third-party or self-built workloads so they can be
run as fully managed Railiance workloads in the wider Railiance and Net Kingdom
context.
They do not replace the ownership repos that define why a capability exists.
9. Substrates Need Purpose, Not Just Names
reef-* repos should represent compute resources organized around a defined
purpose and operational boundary.
They should not be created merely because a named machine exists.
10. Import Canon; Own Railiance Semantics
General concepts such as intent, scope, demand, task, governance, evidence, and repository layout come from InfoTechCanon and estate conventions. This repo owns their Railiance-specific application: repo-family vocabulary, composition, admission, exposure, and cross-repo boundary decisions.
11. Author Here; Publish Downstream
Accepted framework ADRs are policy sources. They are authored, reviewed,
superseded, or withdrawn here and published by policy-nexus. Workplans,
evidence, runbooks, and general documentation remain working material rather
than becoming policy merely because they are useful.
12. Keep Intent, Scope, and Demand Distinct
INTENT.md describes the direction and stable purpose. SCOPE.md describes
what the repository currently owns and achieves. Consumer requests and incoming
proposals are demand signals until reviewed; they do not silently expand scope
or become committed work.
What This Is (Conceptually)
This repository is:
- an architecture-definition home
- a repository taxonomy authority
- a home for framework-level ADRs and conceptual models
- the source repository for Railiance framework ADRs published through
policy-nexus - a place to define how Railiance repos compose across multiple axes
- a migration map from current repo reality toward cleaner framework structure
What This Is Not
This repository is not:
- the infrastructure substrate
- the Kubernetes runtime or workload execution layer
- the shared platform-services layer
- the forge runtime
- the application release surface
- the implementation of the ecosystem graph registry
- the general semantic canon owned by InfoTechCanon
- the permanent policy publication surface owned by
policy-nexus - a policy CMS or a second copy of published policy
- a dumping ground for operational runbooks that belong elsewhere
It is the place where the framework explains itself.
Direction of Evolution
This repository is expected to evolve toward:
- clearer repository-family definitions and lifecycle rules
- stable rail, rapp, and reef contracts
- stronger boundary guidance for new repos and migrations
- better linkage between architecture decisions and
railiance-fabricdeclarations - publication-ready ADR lifecycle metadata and durable downstream policy links
- explicit, graded adoption of the InfoTechCanon repository-layout convention
- a repeatable path from exploration -> ADR -> adopted framework pattern
- a clear model for when experimental multi-rail substrates are acceptable and when production-grade separation is the better default
Guiding Question
How can Railiance define its own structure clearly enough that every new repo, rail, managed workload, and substrate increases capability without increasing ambiguity, even as the ecosystem grows from exploratory operation into production-grade responsibility?