Skip to main content

Developer Portal — Docusaurus IA refocus (design spec, 2026-06-21)

Brainstormed + approved 2026-06-21. Refocus the Docusaurus site at developer.eldr-labs.duckdns.org from "mostly the test gallery + embedded Widgetbook" into an intent-organized developer portal with a real front door.

Goal​

A developer-focused portal with three top-level sections — Developer, Design System, Test Gallery — plus a landing page, where the Developer section is organized by reader INTENT (Diátaxis: learn → do → understand → reference), not by source file.

Why (the principle)​

The current site is one autogenerated sidebar over docs/design-system/ (Widgetbook pages) + docs/gallery/ (flow goldens). Organizing a dev site by where content comes from (CLAUDE.md vs docs/ vs goldens) buries what a reader is trying to do. The portal leads with orientation (a landing + Getting Started) and groups the rest by intent.

Information architecture​

Landing page (src/pages/index or a docs intro) — the front door: what Rewhaven is, the architecture in a paragraph, "run it / test it" quick-start, and three cards into the sections.

1. Developer (docs/developer/) — intent-ordered:

  • Getting Started — clone, FVM (fvm flutter), run, test, codegen. AUTHORED (a concise distilled page, not a CLAUDE.md dump).
  • Architecture & Concepts — inside/outside, the Bloc → Repository → Client (facade) → Service → Adapter data path, the SDK construction rules, the load-bearing invariants. AUTHORED, distilled from rewhaven/CLAUDE.md's architecture sections (+ a diagram).
  • Guides (How-to) — task recipes: add a repository, add a bloc/page, write a flow test, regenerate goldens, run graphify. AUTHORED, distilled from the "how" parts of CLAUDE.md.
  • Decisions (ADRs) — the docs/decisions/*.md log. GENERATED (copied from the repo at build time → stays in sync).
  • Specs & Plans — docs/superpowers/specs/* + plans/* + rebuild-spec.md (project design history). GENERATED (copied from the repo).

2. Design System (docs/design-system/) — component reference: the existing Widgetbook component pages (atoms/molecules/templates/foundations), a prominent "Open the live Widgetbook" link to /design_system/, and the design-system tokens/decisions.

3. Test Gallery (docs/gallery/) — flow/visual reference: the flow-test goldens by feature (unchanged generation).

Authored vs generated (the clean seam)​

  • GENERATED at build (build_test_gallery.mjs, stays in sync with the repo): docs/gallery/** + docs/design-system/** (today), PLUS new docs/developer/decisions/** (← repo docs/decisions/) and docs/developer/specs-and-plans/** (← repo docs/superpowers/ + rebuild-spec.md). The script adds _category_.json (label + order) per generated dir and normalizes front-matter (a title, strip stray H1 duplication).
  • AUTHORED, committed source under app/test-gallery/docs/developer/: getting-started.md, architecture.md, guides/*.md (the curated, intent-shaped pages distilled from rewhaven/CLAUDE.md). The build MUST NOT clobber these — build_test_gallery.mjs regenerates ONLY its generated subdirs (gallery/, design-system/, developer/decisions/, developer/specs-and-plans/), never the authored ones.

Wiring​

  • docusaurus.config.js navbar → 3 items: Developer · Design System · Test Gallery (each a docSidebar to its sidebar), plus the landing as the site home (/).
  • sidebars.js → three sidebars (developerSidebar, designSystemSidebar, gallerySidebar), each an autogenerated over its docs/<section>/ subtree (replacing today's single combined gallerySidebar). Section + page order via _category_.json + sidebar_position front-matter.
  • The landing page links to the three sections + /design_system/.

Build / deploy​

  • Extend app/test-gallery/scripts/build_test_gallery.mjs (currently 261 lines) with a generateDeveloperDocs() step: copy the repo docs/decisions/*, docs/superpowers/specs/*, docs/superpowers/plans/*, docs/rebuild-spec.md into docs/developer/{decisions,specs-and-plans}/, writing _category_.json + light front-matter. Idempotent; safe to re-run.
  • Rebuild + redeploy via the existing scripts/deploy-developer-gallery.sh (npm run build → serve build/ on :8002 → live at the subdomain). No Caddy change.

Testing / verify​

  • npm run build succeeds with onBrokenLinks: 'warn' (no hard failures); the three sidebars render; the Developer section shows Getting Started / Architecture / Guides / Decisions / Specs & Plans; the landing renders.
  • After deploy-developer-gallery.sh: https://developer.eldr-labs.duckdns.org/ shows the new portal, the three navbar sections resolve, and /design_system/ (Widgetbook) still serves.
  • A guard: re-running build_test_gallery.mjs does NOT delete the authored developer pages (getting-started/architecture/guides).

Out of scope​

  • Rewriting doc content beyond the curated distillation of CLAUDE.md into the authored pages (the rest is ingested as-is, lightly normalized).
  • The flow-gallery + Widgetbook generation logic (untouched).
  • Search, versioning, theming beyond what Docusaurus ships.
  • Auto-syncing CLAUDE.md → the authored pages (they're hand-curated; if CLAUDE.md changes materially, refresh them manually).

Sequencing (for the plan)​

  1. Build pipeline: extend build_test_gallery.mjs with generateDeveloperDocs() (copy repo docs → docs/developer/{decisions,specs-and-plans} + categories) + ensure it never clobbers authored pages.
  2. Authored developer pages: getting-started.md, architecture.md (+ a data-path diagram), guides/*.md distilled from CLAUDE.md.
  3. IA wiring: the landing page, the 3-item navbar, the 3 sidebars + _category_.json ordering.
  4. Build + deploy + verify (the three sections live at the subdomain).