Platform Architecture

GloriousFlywheel is a self-hosted runner and cache platform organized in four layers.

Layer 1: FOSS Core Substrate

The shared infrastructure that works without any managed service dependency.

Components:

• Attic: Multi-tenant Nix binary cache backed by S3-compatible storage
• Bazel remote cache: Optional build acceleration via remote cache endpoint
• Runner images: docker, nix, nix-heavy, future hardware classes (gpu, kvm)
• Cluster substrate: Kubernetes + OpenTofu deployment surfaces
• Dashboard: SvelteKit operator UX with WebAuthn auth
• Operator tooling: Just recipes, health checks, MCP server

This layer deploys on any Kubernetes cluster. The reference deployment runs on an on-prem RKE2 cluster (honey) with Tailscale overlay networking.

Layer 2: Forge Adapters And Implementation Overlays

Each forge has its own runner registration, scope model, token handling, and event routing. The shared substrate stays the same; the adapter handles forge-specific enrollment.

Implementation overlays sit at this layer. They carry the owner-specific deployment facts that cannot live in the reusable core repo:

• GitHub App installation IDs and private keys
• owner or organization-specific registration URLs
• backend state settings
• private tfvars, endpoints, and access policy

A future implementation overlay can serve tinyland-inc, jesssullivan, or another operator tenant while pointing to the same backend cluster and cache substrate. That is an auth and configuration boundary, not a new runner taxonomy.

Layer 3: Managed Control Plane (Future)

Optional SaaS layer above the FOSS core for fleet enrollment UX, tenant and pool management, usage reporting, cache and runner observability, policy packs, and support diagnostics.

Not required for deploying the base platform, bootstrapping a cluster, using Attic or Bazel cache, or running GitHub ARC on a self-hosted cluster.

Layer 4: Compatibility Kit

Legacy Bzlmod overlay patterns, local_path_override development flows, downstream merge-and-modify examples, and transitional consumers.

This is not the primary adoption path. Do not confuse the legacy symlink-merge overlay machinery with the current implementation-overlay ownership boundary. See Adoption Quickstart for the recommended onboarding flow.

Multi-Org Enrollment Model

Runner enrollment is modeled along four dimensions:

1. Forge scope: GitHub repo/org/enterprise, GitLab project/group/instance, Forgejo repo/org/account
2. Operator tenant: team, org, enterprise, managed customer
3. Execution pool: docker, nix, nix-heavy, gpu, kvm
4. Cache/state plane: Attic tenant/cache view, Bazel cache namespace, state backend authority

Adopting GloriousFlywheel

1. Deploy the core substrate on your cluster
2. Enroll your forge using the appropriate adapter
3. Choose shared capability runner pools
4. Attach caches (Attic for Nix, Bazel remote for Bazel)
5. Customize runner images, placement, and policy

Put owner-specific auth media and deployment values in an implementation overlay. Keep shared capability labels in the core product contract.