Design Decisions
This page summarizes the project’s Architecture Decision Records. Each one
is a full document under docs/decisions/ in the repository, indexed in
docs/DECISIONS.md; this page won’t always be exhaustive, so treat the
repository as the source of truth for the full reasoning and trade-offs.
| # | Decision | Summary |
|---|---|---|
| 001 | Monorepo layout | pnpm workspaces + Turborepo, packages split by responsibility (shared/core/browser/cli/mcp-server) |
| 002 | Collector interface | A single QACollector<T> shape (setup/onNavigate/teardown/toIssues) every runtime check implements |
| 003 | Browser engine | Playwright drives the browser; it’s a regular dependency, not a peer dependency |
| 004 | Local storage layout | Reports, screenshots, and HAR files live under .local/frontend-qa/runs/<runId>/ in the scanned project, never uploaded |
| 005 | npm packaging strategy | frontend-qa (unscoped) bundles core/browser/shared into one publishable tarball; internal packages stay private |
| 006 | ESM/CJS strategy | ESM-only, targeting a modern Node baseline (engines.node >=20) |
| 007 | Package name | frontend-qa, verified available (unpublished, 404) on npm as of 2026-08-11 |
| 008 | Dev-server auto-launch | Reuse a running dev server if found, else launch one; navigation settling is event-driven (waitForQuiet), not a fixed sleep |
| 009 | Phase 3 QA engines | a11y (axe-core), perf (Lighthouse over CDP), visual (pixelmatch), and bundle analysis, all opt-in except bundle’s own subcommand |
| 010 | Phase 4 code intelligence | ts-morph-based static analysis (analyzeStatic) — filesystem-only, no browser |
| 011 | Phase 5 MCP server | Five stdio MCP tools, thin wrappers over the same core/browser functions the CLI uses; no HTTP/SSE transport |
| 012 | Documentation website | Astro + Starlight for this site — see below |
ADR-012: documentation website stack
Section titled “ADR-012: documentation website stack”Recorded in docs/decisions/ADR-012-docs-website.md and indexed in
docs/DECISIONS.md. Summary:
Decision: Build the documentation/product site with
Astro + Starlight,
as a new apps/website package in the existing pnpm workspace.
Context: The project needed a documentation site explaining installation, usage, architecture, and API surface, built from real repository facts, with local search, dark/light mode, and SEO — without adding a paid search service or a framework mismatched to a docs-only static site.
Options considered:
- Docusaurus — mature, but heavier (React app framework) for a content-first site with no interactive-app requirements.
- Next.js + MDX (Nextra or hand-rolled) — the example apps in this repo already use Vite/React, and a docs site doesn’t need a full app framework or client-side routing.
- VitePress — Vue-based; would introduce a second UI framework into a TypeScript/React project for no functional benefit.
- Astro + Starlight — static-first, ships minimal JS, has Content Layer collections for MDX, built-in Pagefind local search (no paid service), built-in dark/light theme and sidebar/TOC/prev-next navigation.
Chosen: Astro + Starlight.
Why: Matches every stated constraint — TypeScript, static generation, MDX, local search, SEO primitives, and responsive layout — without hand- building navigation, search, or theming from scratch, and without pulling in a second frontend framework.
Trade-offs: Starlight’s visual design is opinionated (a conventional
docs-site layout); this project layers a small custom CSS override
(apps/website/src/styles/custom.css) for accent color rather than
overriding its structure, trading some visual distinctiveness for far less
custom layout code to maintain.