Skip to content

Architecture Decision Records

ADRs document the significant frontend architectural decisions made for GrinSystem, along with their context and consequences. They mirror the BE's ADR convention so reasoning is captured in the same shape on both sides of the wire.

The list below is generated chronologically by the blog plugin. For new ADRs, copy the template into posts/ with a numbered prefix (e.g. 001-router-tanstack.md).

  • 2 min read

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.