ADR-0001: Atlas platform choice
ADR-0001 ACCEPTED 2026-09-20
Context
Section titled “Context”Murmur needs one documentation platform that produces two publications — public product docs (docs.murmurmusic.ai) and internal engineering docs (atlas.murmurmusic.ai) — from a shared design system, component library, and build pipeline, without becoming a bespoke CMS or introducing a database.
Decision
Section titled “Decision”Build Atlas on Astro + Starlight + MDX + TypeScript, statically generated,
deployable to Cloudflare. Enforce public/internal isolation by physically
staging only the requested audience’s content onto disk before Astro ever
runs (scripts/stage-content.mjs), rather than filtering routes or hiding
navigation — see ADR-0002.
Alternatives Considered
Section titled “Alternatives Considered”- Docusaurus — mature, React-based, but Starlight’s content-collections model maps more directly onto our frontmatter-schema requirements and ships a smaller default JS footprint.
- Contentful / a headless CMS — explicitly ruled out by the build brief (docs-as-code, no external source of truth, no database).
- Notion as source of truth — explicitly ruled out; Notion is fine for drafting, not for a build pipeline agents and CI can validate.
- Two separate repos/sites (one public, one internal) — rejected: it’s exactly the “disconnected documentation systems” the build brief asked Atlas to avoid. A shared theme and component library drift apart the moment they live in two build pipelines.
Consequences
Section titled “Consequences”- Every content page must declare
visibilityand match the directory it’s filed under (enforced byscripts/validate-frontmatter.mjs). - No CMS editing UI — contributors write MDX and open a PR, same as code.
- React is available inside MDX for genuinely interactive pieces (future
DSP visualizations) without becoming the default for every component —
most of
src/components/atlas/today is plain.astrowith zero client JS.