bigpowers Documentation Architecture

ONE docs/ root (specs/ dissolved) → build → published Astro/Starlight site

01 / docs/ — the one root 02 / Build & Aggregate 03 / Published Destinations Wave 1 GitHub-native — root + .github/ outside docs/ docs/* GoodDocs packs (12, minus 6 collisions) human prose docs/project/* ex specs/ — SDD content OKF source Direct Render Starlight — narrative, 1:1 zero transform Aggregator dashboards from data-OKF few generic views Content Pages Guides, Reference, Architecture, Requirements, Quality, Community browsable Dashboard Views Epic Board, Bug Registry, Metrics generated GitHub UI repo home, Security tab, Issue/PR forms not the site GitHub-native not on site 4 files mirrored build-time embed 12 packs direct render, zero transform ADRs, stories, bugs, audit narrative OKF = the page metrics, status, plan data OKF build static pages aggregate render few views, not one per file Legend primary data policy / PII async batch data store

docs/ — the single root (specs/ dissolved)

  • • docs/{concept, how-to, reference, tutorial, style-guide, user-personas, images}/ + 4 resolved collisions (readme, changelog+release-notes, glossary, troubleshooting) + AGENTS.md (CLAUDE.md/GEMINI.md symlinks)
  • • docs/project/{architecture, epics, bugs, audit, metrics, status}/ — the ex specs/ tree; status/ holds runtime state (state.yaml, execution-status.yaml)
  • • Wave 1 stays OUTSIDE docs/ at repo root + .github/ — GitHub's own rendering surface, not this build

T7 — folder collision list (26 candidates → 4 real collisions)

  • • 6 are sub-templates already nested in a parent (api-reference/api-getting-started/sdk-overview→reference/; installation-guide→how-to/; quickstart→tutorial/; terminology-system→glossary/) — no decision needed
  • • 8 are Wave-1 root files, not docs/ content (bug-report, code-of-conduct+3 records, contributing-guide, our-team, contact-support)
  • • 4 genuine collisions, working one-by-one in priority order: README (active — T8), changelog vs release-notes, glossary vs GLOSSARY.yaml, troubleshooting vs bug RCA

Published Site Sections

  • • Content pages: Start/Landing, Community, Guides, Reference, Architecture & Decisions, Requirements, Quality & Risk
  • • Dashboard views: Epic Status Board, Bug Registry, Metrics (BCP burndown, cycle-time, compliance %)
  • • GitHub Native UI stays a separate surface — repo homepage, Security tab, Issue/PR forms are not part of the docs site

Design Invariants

  • • No parallel *-wiki/ mirror folders — docs/project/ is the single source (specs/ dissolved into it)
  • • Narrative content IS the render — no separate per-document view template
  • • Data content (docs/project/status/) feeds a handful of generic dashboard views, never one page per file
  • • Only 4 of 9 Wave 1 files are mirrored onto the site; SECURITY.md and LICENSE stay GitHub-native-only
  • • llm-wiki is a file layout (index.md + log.md), not GitHub's Wiki feature — lives inside docs/, rendered by Pages

Data-flow diagram • Built with Archify • Press T for theme and E for export