ADR-0001: Monorepo Stack Selection

ADR-0001: Monorepo Stack Selection

Status: Accepted
Date: 2026-01-01

Context

Cosella needs a frontend platform that supports:

• A web dashboard, an admin panel, an Electron overlay, a marketing site, and engineering docs — all sharing design tokens, domain types, and UI components.
• Strict type safety everywhere (exactOptionalPropertyTypes, noUncheckedIndexedAccess).
• Fast CI and local iteration via caching.

Decision

Concern	Choice	Rationale
Workspace	pnpm workspaces + catalog	Single version source; faster installs than npm/yarn
Task runner	Turborepo	Remote caching; incremental builds
Bundler	Vite	Sub-second HMR; native ESM
Router	TanStack Router	Full type-safe routes; file-based codegen
Data fetching	TanStack Query	Industry standard; great devtools
Styling	Tailwind CSS v4	CSS-first @theme; no JS config file
Component primitives	Radix UI (owned copies)	Accessible; unstyled; no breaking upgrades
API types	openapi-typescript + openapi-fetch	Single source of truth from OpenAPI spec
Realtime	WebSocket with backoff reconnect	Works in browser + Electron; no STUN/TURN complexity
Testing	Vitest + Testing Library + MSW v2	Fast; no Jest config churn

Consequences

• All packages must use the pnpm catalog versions.
• tsconfig extends must use relative paths (Windows junction limitation).
• Apps may only depend on packages, never on sibling apps.