Parking System — Project Guide

A parking-management system: a web app on a dedicated, hardened Linux appliance, deployed on-site at a parking facility. Two forces shape almost every decision: offline-first operation and a threat model whose primary adversary is the legitimate operator at the booth (not an outsider). Keep both front of mind.

Repository layout

This directory is a Turborepo monorepo. App code lives here; the knowledge base lives in wiki/.

parking-system/
├── CLAUDE.md         # this file — app development guide
├── package.json      # turborepo root
├── turbo.json
├── apps/
│   ├── server/       # Fastify backend (device drivers, API, auth); serves the SPA
│   └── web/          # React + Vite SPA (operator UI)
├── packages/
│   ├── db/           # Drizzle ORM schema + migrations (SQLite local; PostgreSQL sync target)
│   ├── devices/      # device adapters behind shared interfaces (reader/printer/relay)
│   └── shared/       # shared types/utils
└── wiki/             # LLM-maintained knowledge base (Obsidian vault) — see wiki/CLAUDE.md

Code layout above is the intended target; scaffold packages as the work reaches them rather than all up front.

The wiki is the knowledge base — consult it first

wiki/ is an LLM-maintained design knowledge base (the "LLM Wiki" pattern). It is not app code and has its own schema at wiki/CLAUDE.md. Before making architectural decisions or implementing a subsystem, read the relevant wiki pages for the rationale, rejected alternatives, and open questions:

Start at wiki/overview.md; catalog in wiki/index.md.
Settled decisions: wiki/decisions/standing-decisions.md.
Unsettled, procurement-driving items: wiki/decisions/open-questions.md — do not hard-code around these without flagging them.

When app work surfaces a new design fact, decision, or contradiction, update the wiki following wiki/CLAUDE.md (ingest/query/lint workflows). Source documents go in wiki/raw/.

Stack (settled)

All dependencies are MIT / Apache / BSD — a hard constraint to avoid vendor lock-in and license rug-pulls. See wiki/entities/technology-stack.md for the full table and rationale.

Layer	Choice
Monorepo	Turborepo
Backend	Node.js + Fastify
Frontend	React (SPA, Vite), served by Fastify
Local DB	SQLite (`better-sqlite3`) + Drizzle ORM (Drizzle Kit)
Remote sync target	PostgreSQL (deferred — not a runtime dependency)
Auth	Local JWT (`@fastify/jwt`) + bcrypt + role guard (admin/operator/cashier/readonly)

Architecture constraints that bind the code

These are not negotiable defaults — they come from the threat model and safety analysis:

Offline-first. Nothing in core operation may depend on a network. Auth, DB, and device decisions must work air-gapped. No external identity provider; no cloud runtime dependency.
Append-only, signed event log. Entry/exit events are never edited or deleted — a "void" is itself an appended event. Events are hash-chained (each stores the prior event's hash) and signed by an ATECC608 secure element. This is the core anti-fraud mechanism; don't add update/delete paths to event records.
Device-agnostic adapters. Business logic talks only to interfaces (reader/printer/relay), never to a device SDK. Hardware swaps = a new adapter in packages/devices, nothing else.
A barrier is not a door. Never drive a barrier as a timed "open for N ms" auto-close. Physical safety lives in the barrier operator's firmware; the app only ever expresses intent ("open"). Relay interfaces are pulseOpen, never timed close.
Fail-state. On power/network/host loss: entry fails closed, exit fails open (never trap a vehicle — often a legal egress requirement).
Network isolation for access controllers. The UHPPOTE controller speaks unauthenticated UDP; it must sit on an isolated VLAN reachable only by the host. Treat its event log as tamper-evident (host-side index tracking), not tamper-proof.
Keep PCI scope out of the app. Payments go through a standalone bank-certified P2PE terminal — the application must not handle card data.

For the full reasoning behind each, follow the links from wiki/overview.md.

Conventions

TypeScript throughout. Match the style of surrounding code.
Confirm before destructive or outward-facing actions. Commit/push only when asked.

graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

Rules:

For codebase questions, first run graphify query "<question>" when graphify-out/graph.json exists. Use graphify path "<A>" "<B>" for relationships and graphify explain "<concept>" for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
After modifying code, run graphify update . to keep the graph current (AST-only, no API cost).

5.2 KiB Raw Permalink Blame History