n-dashboard: Instructions file for Claude Code

CLAUDE.md

Notes for anyone — human or agent — working in this repository. README.md is the user-facing documentation; this file is the parts that are easy to break.

What this is

A personal dashboard for a trusted LAN. One idea carries the whole design: a widget is a TypeScript function on disk. The platform decides when to call it (clock, MQTT message, webhook), validates what it returns against a typed schema, and pushes the result to every open tab over SSE. There is no plugin format and no config-driven renderer path, so summing a field, joining two APIs and remembering what you already saw are all the same amount of work.

Widget code is trusted. Isolation exists to contain bugs, not attackers. There is one optional login, over /admin only (ADMIN_PASSWORD in .env) — it keeps the panel out of reach of whoever walks past the wall display, and it is not a hardening story. Multi-user is still out of scope; see the bottom.

Commands

npm run dev        # node --watch on :8080 + vite on :5273 (proxies /api)
npm test           # vitest; MQTT suites skip themselves without a broker
npm run typecheck  # both projects; run this, tsc catches what vitest can't
npm run build      # web bundle only — the server has no build step

docker compose -p n-dashboard-dev -f docker/compose.dev.yml up -d   # broker for tests

Repo map

.claude/skills/ write-widget — the widget-authoring workflow, for agents
src/shared/    ctx.d.ts (the widget API), kind schemas, duration parsing
src/server/    express, worker pool, scheduler, connections, ndjson store
src/web/       react — dashboard (kept light) + admin (Monaco, lazy-loaded)
docker/        Dockerfile, both compose files, broker configs
docs/          the long-form guides linked from README.md, plus the Pages page
examples/      seeded into data/ disabled on first run
data/          runtime state, gitignored

Invariants

Break one of these and it usually fails somewhere far away from the change.