Capture hard-won dev knowledge that was only in commit messages:
- wsl-dev-networking: WSL2 NAT blocks UDP broadcast (device discovery can't
reach the LAN); fix is mirrored networking (.wslconfig, Win11 22H2+), plus the
gotchas that remained after — multiple interfaces, subnet-directed broadcast,
localhost->IPv6 stall. Alternatives for non-mirrored setups.
- local-dev-workflow: first-time setup, pnpm dev, and the gotchas (the
strip-types dev-server hang -> tsx, the 127.0.0.1 proxy fix, .env loading,
seeding into the right DB).
- device-discovery: corrected the old "broadcast permission (EACCES)" note — the
real cause was the lib not enabling SO_BROADCAST for global 255.255.255.255;
documented the three verified broadcast gotchas + I/O serialization.
- schema: add a `reference` page type; new "Dev environment" index section; log.
Links lint clean; both new pages well-connected.
Turborepo (pnpm workspaces) with all dependencies pinned to latest
mutually-compatible versions: turbo 2.9, TypeScript 6, Fastify 5,
React 19, Vite 8, better-sqlite3 12 + Drizzle ORM 0.45.
Layout:
- apps/server Fastify backend (local JWT auth + role guard, /health)
- apps/web React 19 + Vite 8 operator SPA
- packages/db Drizzle schema on SQLite/WAL; append-only events + users
- packages/devices reader/printer/relay adapter interfaces (intent-only relay)
- packages/shared shared domain types
Architecture constraints from the design wiki are encoded in the scaffold:
append-only hash-chained + signed event log, device-agnostic adapters,
"a barrier is not a door" (relay expresses intent only), fully-local
offline-first auth.
wiki/ is an LLM-maintained Obsidian knowledge base (28 pages) ingested
from the architecture & design notes, with its own maintenance schema.
Verified: pnpm install, full turbo build (5/5), server boots and serves
/health, drizzle-kit generates the initial migration.
julian