Skip to content

ADR-000: Docs site and ADR convention

Status

Accepted

Context

The FE repo had a growing docs/ tree (architecture, standards, design-system, testing, per-module plans) but no rendered site. The BE already runs a MkDocs Material site at mkdocs.yml with an ADR-as-blog convention, and both repos share a single team; cognitive load is lower when reading both feels identical.

We also had no convention for capturing significant frontend architectural decisions in a durable, dated, reviewable form. The reasoning that lives in CLAUDE.md and docs/standards.md covers the "what" and the "how", but not the "why we chose this over the alternative" — which is what an ADR is for.

Decision

  • Stand up a MkDocs Material site mirroring BE (mkdocs.yml at repo root, same theme palette, same validation gates, same markdown extensions minus BE-only API-reference plugins).
  • Adopt BE's ADR convention: blog plugin configured against docs/adr/, posts in docs/adr/posts/ with numbered prefixes, a sibling docs/adr-template.md to copy from, and an index that links to the template.

Consequences

Positive

  • Single visual + structural convention for both repos' docs sites.
  • ADRs are dated, ordered, and rendered chronologically without manual nav curation (the blog plugin handles it).
  • The template enforces a consistent shape (status, context, decision, consequences, alternatives) so reviewers know where to look.

Negative

  • The Python-tooled MkDocs is a second toolchain alongside pnpm — docs/requirements.txt and pip install are how it runs. Trade-off is acceptable: it matches BE and the team already knows it.

Neutral

  • ADRs are additive — existing standards / architecture docs stay as the day-to-day reference. ADRs answer "why this and not X" once, not "how do I do Y" every time.

Alternatives Considered

Option Pros Cons Why not chosen
Docusaurus / Astro Starlight (Node-tooled) Same language as the rest of the FE; faster local rebuild Different stack from BE; team would maintain two docs toolchains Cross-repo parity beats single-stack purity.
No ADRs — capture decisions in commit messages and PR bodies Zero overhead Decisions get scattered across the PR archive and decay with rotation Doesn't scale past a couple of people.
ADRs as flat docs/adr/NNN-foo.md (no blog plugin) Simpler — no plugin Manual nav curation, no chronological view, no author/date metadata Diverges from BE.