GloriousFlywheel Topology And Config Authority Strategy 2026-04-23

GloriousFlywheel Topology And Config Authority Strategy 2026-04-23

Snapshot date: 2026-04-23

Purpose

Capture the square-one answer to two related questions:

  1. what repo and topology strategy GloriousFlywheel is actually pursuing
  2. what config/organization.yaml is authoritative for today versus where it remains only partial centralization

This note is a strategy note, not the final internal live contract.

Current Topology Strategy

Main repo

tinyland-inc/GloriousFlywheel is the internal source of truth for:

  • platform architecture and product direction
  • OpenTofu modules and stacks
  • runner and cache tooling
  • operator-facing docs and runbooks
  • internal planning notes
  • the internal live contract once it is written

This repo is not currently a clean public projection.

Compatibility kit

Jesssullivan/bzl-cross-repo remains the bounded home for overlay/Bzlmod compatibility flows.

Its role is:

  • preserve transitional consumer mechanics
  • support local_path_override and merge-style downstream composition
  • hold compatibility-era examples that are still operationally useful

Its role is not:

  • define the main product identity
  • define default onboarding for new adopters
  • become the place where platform truth drifts away from the main repo

Downstream consumers and canaries

Owned downstream repos remain proof surfaces, not the platform source of truth.

They exist to validate:

  • runner contract
  • cache contract
  • hybrid-by-policy boundaries
  • advanced-runner proof floors

They should not become the place where the core platform contract is defined.

Future public surface

The future public surface should be:

  • extracted from internal truth
  • generated from internal truth
  • intentionally rewritten from internal truth

but not mixed directly into the same internal docs tree without boundary rules.

No specific extraction mechanism should be treated as decided yet.

Repo Responsibility Split

Surface Primary home now Notes
Internal platform definition GloriousFlywheel main repo owns north star and internal contract
Internal operator docs GloriousFlywheel includes topology, access, runbooks, repair paths
Internal planning/evidence GloriousFlywheel currently under docs/research/; may later move out of canonical docs hierarchy
Compatibility mechanics bzl-cross-repo plus bounded compatibility docs in GloriousFlywheel compatibility is real, but explicitly secondary
Future public docs/product surface not finalized should be a later projection, not the current mixed repo surface

Config Authority Today

What config/organization.yaml is authoritative for

Today it is the central source for:

  • organization identity
  • logical environment names
  • cluster/context mapping
  • domain and namespace mapping
  • network metadata such as private API server and MagicDNS zone
  • selected dashboard-generated environment metadata through app/scripts/generate-environments.ts

That is real authority and should be treated as such.

What config/organization.yaml is not yet authoritative for

It does not yet fully define:

  • the live endpoint contract by audience
  • the auth and mutation-authority contract
  • cache/publication boundary semantics
  • runner-class semantics in full
  • public versus internal docs projection
  • every generated artifact needed for docs/config parity

In other words, the repo has central configuration, but not yet full contract generation.

Strategy Implication

Do not describe the platform as fully generated from organization.yaml.

The truthful claim today is:

  • organization.yaml is the central deployment and environment config surface
  • some downstream config is generated from it
  • the wider platform contract is still partly hand-maintained and therefore can drift

That drift is exactly why the internal live contract must be written next.

Short term

  • keep GloriousFlywheel as the internal source of truth
  • keep compatibility bounded and secondary
  • stop implying full config parity where only partial generation exists
  • define the internal live contract before larger docs rewrites

Medium term

  • decide which public-facing surfaces can actually be generated from internal config and contract
  • decide which public-facing surfaces should be rewritten narrative docs instead
  • make the public projection depend on the internal live contract, not on scattered internal docs

Boundaries To Preserve

Do not let these distinctions collapse:

  • internal source repo vs future public projection
  • main product path vs compatibility path
  • central configuration authority vs full contract authority
  • canary proof surfaces vs product-definition surfaces

GloriousFlywheel