99 lines
5.2 KiB
Markdown
99 lines
5.2 KiB
Markdown
# 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).
|