Architecture

Hub and Spoke model

Each product keeps its documentation in its own repository (a Spoke). The Hub repository owns the Astro Starlight portal, Spoke registry, build pipeline, and staging deployment.

Spoke documentation is never committed into the Hub. The Hub fetches configured docs/ trees at exact SHAs during CI, validates them, then builds.

Registry

Enabled Spokes live in config/spokes.json. Each entry defines:

• id — unique route under /products/<id>/
• repository — GitHub owner/repo
• branch — trusted branch used for rebuilds (MVP: main)
• docsPath — directory to extract (MVP: docs)
• enabled — whether the Hub includes it in every build

Build flow

1. Trigger via repository_dispatch from a Spoke or manual workflow_dispatch.
2. Validate the triggering repository against the registry.
3. Resolve exact SHAs for all enabled Spokes.
4. Clean previously generated product content.
5. Fetch and extract only each Spoke’s configured docs directory.
6. Validate content, assets, links, routes, and security rules.
7. Write build-manifest.json with every Spoke SHA.
8. Run bun run build with broken-link validation.
9. Deploy the complete portal to staging (Cloudflare Pages).

Security boundaries

• Spokes hold DOCS_HUB_DISPATCH_TOKEN (Contents: Write on the Hub only) to send repository_dispatch.
• The Hub holds DOCS_SPOKES_READ_TOKEN (Contents: Read on private Spokes; no write).
• Hub workflows never write to Spoke repositories.
• Workflows use minimum contents: read / pull-requests: read unless deploying Pages.
• Fork PRs never receive dispatch or Spoke-read secrets.
• Spoke PR checks and dispatch workflows live in the Spoke (a few product repos; no Hub-hosted contract package). Hub fetch-spokes.mjs validates fetched docs before staging deploy and is the publish gate.