134 lines
4.5 KiB
Markdown
134 lines
4.5 KiB
Markdown
# SCOPE
|
|
|
|
> This file helps you quickly understand what this repository is about,
|
|
> when it is relevant, and when it is not.
|
|
> It is intentionally lightweight and may be incomplete.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
Architecture-definition home for Railiance: repository taxonomy, framework ADRs,
|
|
cross-repo boundary rules, and cross-repo workplans for architecture changes.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
`railiance-master` is the framework-level architecture repo for Railiance.
|
|
It exists so shared concepts such as `railiance-*`, `rail-*`, `rapp-*`, and
|
|
`reef-*` are defined once, with explicit boundaries, before they spread across
|
|
implementation repos.
|
|
|
|
It also serves as the natural workplan home for changes that span multiple
|
|
Railiance repos and cannot be owned cleanly by only one of them.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- Framework-level architecture documents for Railiance
|
|
- Repository taxonomy and naming conventions
|
|
- Architectural boundaries between ownership repos, rails, `rapp`s, and reefs
|
|
- Architecture decision records affecting multiple Railiance repos
|
|
- Cross-repo Railiance workplans whose implementation spans multiple sibling repos
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- OS provisioning and host hardening work owned by `railiance-infra`
|
|
- Kubernetes runtime implementation owned by `railiance-cluster`
|
|
- Platform-service implementation owned by `railiance-platform`
|
|
- Application release implementation owned by `railiance-apps`
|
|
- Forge runtime implementation owned by `railiance-forge`
|
|
- Fabric graph implementation owned by `railiance-fabric`
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- Defining a new Railiance repo family or framework term
|
|
- Clarifying boundaries between existing Railiance repos
|
|
- Planning migrations that touch multiple Railiance repos
|
|
- Recording a framework-level architecture decision
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- The work belongs entirely inside one implementation repo
|
|
- The work is operational rather than architectural
|
|
- The work is workload-specific rather than framework-wide
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: active / evolving
|
|
- Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave is now being coordinated from this repo
|
|
- Stability: evolving
|
|
- Usage: internal Railiance framework architecture home and handoff point for cross-repo planning
|
|
|
|
The repo now holds the canonical framework decisions and boundary documents for
|
|
separating `rail-*`, `rapp-*`, and `reef-*` concerns out of the existing
|
|
Railiance repos. It also now governs the first implementation wave that turns
|
|
those repo families into concrete repos while downstream ownership repos retain
|
|
their implementation responsibility.
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
- Upstream dependencies: `the-custodian` canon and State Hub conventions
|
|
- Downstream consumers: all `railiance-*`, future `rail-*`, future `rapp-*`, and future `reef-*` repos
|
|
- Often used with: `railiance-fabric`, `railiance-platform`, `railiance-cluster`, `state-hub`
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- Preferred terms: architecture home, repository axis, rail, `rapp`, reef, ownership repo
|
|
- Also known as: framework architecture repo
|
|
- Potentially confusing terms: this repo defines framework structure; it does not implement the lower-layer systems it describes
|
|
|
|
---
|
|
|
|
## Related / Overlapping Repositories
|
|
|
|
- `railiance-fabric` — models the ecosystem graph; `railiance-master` defines framework taxonomy and boundaries
|
|
- `state-hub` — indexes and coordinates work; `railiance-master` provides the framework architecture to be coordinated
|
|
- `repo-scoping` — explains what repos are useful for; `railiance-master` defines how Railiance repo families fit together
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `README.md`, `INTENT.md`
|
|
- Key files / directories: `docs/`, `history/`, `workplans/`
|
|
- Entry points: `docs/repository-axes.md`, `docs/reef-substrate-model.md`, `docs/adr/`
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: documentation
|
|
title: Railiance repository taxonomy
|
|
description: Defines the canonical Railiance repo families and how ownership repos, rails, managed workloads, and substrate boundaries compose.
|
|
keywords: [railiance, architecture, taxonomy, rail, rapp, reef]
|
|
```
|
|
|
|
```capability
|
|
type: governance
|
|
title: Railiance framework architecture decisions
|
|
description: Records framework-level architecture decisions and boundary guidance for changes spanning multiple Railiance repos.
|
|
keywords: [architecture, adr, governance, boundaries, framework]
|
|
```
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
Use this repo for architecture that must stay shared. Push concrete
|
|
implementation outward into the ownership repos once the framework boundary is clear.
|