parking_solution/wiki/raw/parking-system-architecture.md

Parking Management System — Architecture & Design Notes

A working record of the architectural decisions, the reasoning behind them, and the alternatives that were considered and rejected. Written as a design reference, not a final spec — several items are still open and flagged as such.

---

1. System context

A parking management system delivered as a web application running on Linux, deployed on-site at the parking facility. Core characteristics:

• Offline-first. A park may have no internet connection, intermittent connectivity, or be fully air-gapped. Nothing in the core operation may depend on a network being present.
• Device-agnostic. It must discover and control local hardware — readers, barriers/relays, printers — through a clean abstraction so hardware can be swapped without touching business logic.
• Optional remote sync. Later, the local database may sync to our own private remote infrastructure. This is a deferred capability, not a runtime dependency.

The two forces that shape almost every decision below are offline operation and the physical-security reality of a machine sitting in an exposed parking booth.

---

2. Technology stack

Decisions

Layer	Choice	License
Monorepo	Turborepo	MIT
Backend	Node.js + Fastify	MIT
Frontend	React (SPA, Vite), served by Fastify	MIT
Local database	SQLite (better-sqlite3)	Public domain / BSD
ORM	Drizzle ORM + Drizzle Kit	Apache 2.0
Remote sync target	PostgreSQL (when implemented)	PostgreSQL License
Auth	Local JWT (@fastify/jwt) + bcrypt + roles	MIT

Rationale

Node.js + Fastify keeps the whole stack in one language, has a mature ecosystem for device I/O (serialport, node-hid, escpos, network protocols), and Fastify is lighter and faster than Express with a clean plugin/hook model. Hardware drivers live as isolated Fastify plugins emitting onto a shared internal event bus.

SQLite locally is the right call for a single-site, single-writer system. Its real limit is write concurrency (one writer at a time, mitigated by WAL mode), which a parking system never approaches. PostgreSQL is reserved for the remote sync target, where Drizzle's schema ports over with minimal change.

Alternatives considered and rejected

• Payload CMS — genuinely strong (free admin UI, built-in auth/RBAC, runs on Node so it can host device drivers via init hooks). Rejected primarily because of its v3 license shift to BSL (source-available, not open source). For a long-lived business system, a vendor that can change licensing terms underneath us is an unacceptable risk given a strong preference for vendor-agnostic, rug-pull-proof tooling. Secondary concerns: it's a CMS at heart, weaker on real-time/event-driven workloads, and Next.js is heavier than needed here.
• Refine — a browser-only React framework (comparable to React+Vite, not Next.js). Dropped in favour of plain React; the operator UI is simple enough that an admin framework's abstractions cost more than they save.
• Logto / Zitadel / any OIDC-OAuth identity provider — ruled out by the offline-first constraint. An air-gapped park cannot depend on an external (or even self-hosted networked) identity provider. Auth is therefore local: @fastify/jwt signing with a local secret, a users table in SQLite with bcrypt password hashes, and a role column. Authorization is a simple preHandler role guard per route (admin / operator / cashier / readonly) — no Casbin or full RBAC engine needed at this scale.

---

3. Data security and the threat model

The key reframing

Early discussion focused on protecting the database at rest — SQLCipher (AES-256 file encryption), LUKS volume encryption, BitLocker, TPM-sealed keys. All of that defends against an outsider who steals the machine or boots from external media.

That is the wrong primary threat for a parking system. The most likely adversary is the legitimate operator sitting at the booth. While the application is running, the database is decrypted in memory and the operator has full, authorised access through the app. Encryption does nothing against the classic parking fraud: take the cash, then void or delete the entry/exit record so the books balance.

Consequences for design

The controls that actually address insider/operator fraud are different in kind:

• Append-only event model. Entry and exit events are never edited or deleted, only appended. A "void" is itself a recorded event, not an erasure.
• Tamper-evident chaining. Each event stores the hash of the previous event (a hash chain). Reordering or deleting breaks the chain visibly.
• Hardware-backed signing. An inexpensive secure element (ATECC608) holds a signing key that cannot be extracted, even by someone who owns the machine. Each event is signed. This is what makes the chain unforgeable rather than merely self-consistent.
• Reconciliation against an authority the operator can't alter. This is what the remote sync really is — a fraud-control mechanism, not just a backup.

Reconciliation when a park is offline

Offline-first does not mean "no reconciliation." It means deferred, intermittent reconciliation. A manager visiting weekly with a USB stick, a phone hotspot once a day, or a monthly export all provide a path to compare local records against something outside the operator's reach. Only design for "never, by anyone" if that is genuinely true — and if it is, the network-free controls are: the signed hash-chained log (above), physically pre-numbered ticket stock, end-of-shift signed Z-reports, and CCTV/LPR footage as an independent record.

Disk / OS hardening (still worthwhile, just not the main event)

Physical-access attacks on Windows are trivial (boot media + password reset tools), so a dedicated Linux machine is the correct platform, not Windows or WSL:

• LUKS full-disk encryption (defeats boot-from-USB)
• GRUB password + Secure Boot (prevents boot-parameter tampering / unsigned loaders)
• No desktop environment; single-purpose appliance
• Key-based SSH only

With LUKS in place, SQLCipher becomes optional defence-in-depth rather than the critical layer.

---

4. SQLite limits (for reference)

The official limits are far beyond anything a parking system reaches:

• Max database size ~281 TB; rows per table effectively unlimited (disk-bound)
• 32,767 columns per table; 1 GB per text/blob cell
• The only practical limit is write concurrency: one writer at a time. WAL mode allows many concurrent readers plus one writer. A single-site parking workload is nowhere near this.

You would only outgrow SQLite with multiple machines writing to the same database (never do this over a network share) or sustained high-frequency concurrent writes. Neither applies. The move to remote PostgreSQL is a business/durability decision, not a capacity one.

---

5. Device architecture

Device-agnostic adapter pattern

Business logic talks only to interfaces, never to a device SDK. Each physical device is an adapter implementing one of these:

interface CardReaderDevice {
  connect(): Promise<void>
  onCardRead(cb: (cardNumber: string, door: number) => void): void
  disconnect(): Promise<void>
}

interface PrinterDevice {
  printTicket(data: TicketData): Promise<void>
  checkStatus(): Promise<'ready' | 'offline' | 'paper_out'>
}

interface RelayDevice {
  pulseOpen(doorId: number): Promise<void>   // see safety note below
  getDoorStatus(doorId: number): Promise<'open' | 'closed'>
}

Swapping hardware means writing a new adapter; nothing else changes.

Safety principle: a barrier is not a door

A vehicle barrier must not be driven as a timed "door open for N ms" by the application — a timed auto-close can drop a boom on a vehicle or person. Physical safety lives in the barrier operator's own firmware (induction loops, anti-crush, auto-reverse). The application and any relay board only ever express intent ("open"); they never time or force a close against a vehicle. This separation holds regardless of which relay device is used.

The core fork: where is the trust boundary?

Two valid architectures, chosen per deployment (and mixable per lane):

• Trust boundary = the network. Use an off-the-shelf controller (UHPPOTE/ZKTeco) and contain its weaknesses by network isolation. Auditable.
• Trust boundary = the device. Use a custom controller whose firmware enforces authentication. Unforgeable, but you own the firmware.

---

6. Access control: UHPPOTE (current choice)

The starting hardware is a UHPPOTE Wiegand 26/34 network controller (4-door). It is a reasonable, cheap reader-plus-relay frontend provided you understand its limits.

The protocol weakness

UHPPOTE communicates over UDP (port 60000) with no authentication and no encryption. Anyone who can place a packet on that LAN can send an "open" command to any door. This is the security issue — not safety (safety is handled by the barrier operator if wired correctly).

Mitigation: network isolation is mandatory. The control devices go on their own VLAN with no route to the booth/office network and no wireless bridge. The security boundary is the network, because it cannot be the device.

Firmware is not changeable

The open-source uhppoted ecosystem is protocol reverse-engineering only — clients that speak the existing UDP protocol. There is no source, SDK, schematic, or toolchain to build and flash custom firmware. The controllers accept firmware updates, but only the manufacturer's official images — not your own authenticated firmware. You cannot configure or patch your way to authentication on this hardware.

The event log — confirmed, and useful

Verified against the official protocol reference:

• The controller stores an indexed event log. get-events returns the stored range plus a current index; each get-event record contains event ID, timestamp, card number, door, access-granted flag, and a reason code.
• At the record level it is effectively append-only — there is no command to edit or delete an individual event.

But it is not tamper-proof over UDP

Several unauthenticated commands undermine the log without touching individual records:

Vector	Command	Effect
Blinding	record-special-events false	Stops logging door open/close/button events going forward
Wipe	restore-default-parameters	Factory reset — clears config and event state
Rollover	(generate events / fall behind)	Finite circular buffer; old events overwritten and lost
Time skew	set-time	Corrupts/ backdates event timestamps
Index desync	set-event-index	Moves the retrieval pointer (a user-managed convenience value, not auto-managed) — naive ingestion skips events

Ingestion design that makes the log trustworthy

• Track your own last-ingested index on the host — do not rely on the controller's current-index pointer (it's user-managed and settable by anyone).
• Walk absolute indices with get-event <id>; treat three things as alarms: a gap in the sequence, an "event has been overwritten" error (you fell behind — data loss), and any door-open event the host never requested.
• Use set-listener auto-push for low latency, but always reconcile by index (UDP pushes can drop).
• Size polling cadence against the busiest lane's event rate so unread events never roll off.
• Land every event in the host's signed append-only chain (the ATECC608 log from §3).

Net result

Tamper-evident, behind network isolation. The same unauthenticated UDP that opens a gate can also blind the log, reset the device, or skew the clock — so the log is only trustworthy when only the host can reach the controller. Combined with host-side index tracking and the signed chain, it becomes a solid detection/audit layer. It does not become tamper-proof; that requires the custom controller (§7).

---

7. Custom ESP32 controller (the prevention alternative)

For device-level authentication — a control path that holds even against an attacker on the wire — a small custom controller is the right build, and the requirement is narrow enough to own safely.

Reframing the requirement

The threat is forged or replayed commands, not eavesdropping ("open lane 2" is not secret). So the essential requirement is authenticity + freshness (anti-replay); encryption is optional defence-in-depth. Building only authentication closes the actual hole.

The design: challenge–response with asymmetric signatures

Host (private key)                         ESP32 controller (host's PUBLIC key only)
  │── "open lane 2" ───────────────────────▶│ generates fresh random nonce
  │◀──────────── nonce ──────────────────────│
  │ sign(nonce ‖ command ‖ timestamp) ──────▶│ verify against stored public key
  │                                          │ check nonce fresh + unused → pulse relay

The elegant property: the controller stores only a public key. Physically compromising the ESP32 (popping the cabinet, dumping flash) yields nothing usable for forging commands. The fresh per-command nonce defeats replay without counter-persistence headaches. A shared-secret/encrypted channel would not have this property (the secret sits on both ends).

Hardware

• Olimex ESP32-POE (wired Ethernet + PoE, open-source hardware) or ESP32-S3 + W5500.
• ATECC608 secure element holding the key(s); generated on-chip, non-extractable.
• Opto-isolated relay between GPIO and the barrier operator's dry-contact open input.
• Enable ESP32 flash encryption + secure boot regardless.
• Transport: Ethernet (keeps one network paradigm on the existing managed switch). RS-485 multidrop is a robust alternative for long/noisy runs, with the same scheme layered on top.

Fail-state and safety (treat as seriously as the crypto)

• Define behaviour on power/network/host loss: entry fails closed, exit fails open (never trap a vehicle — often a legal egress requirement).
• Hardware manual override (key switch/button) that opens the barrier with the ESP32 dead.
• Watchdog with a defined safe default.
• The barrier operator still owns physical safety — the ESP32 only signals intent.

Honest trade-offs

You take on firmware reliability, EMC/surge protection (TVS diodes, isolation, grounding, Ethernet surge arrestor on outdoor runs), and field maintenance. Mitigate by keeping the firmware tiny and auditable — verify a signed, fresh command and pulse a relay, with a watchdog and safe state, and nothing more. The moment it grows "smart," reliability drops. All parking logic stays on the host.

---

8. Entry / exit readers

There are two populations, and they map to two integration paths:

• Permit holders / subscribers — want hands-free or quick entry. Best served by reads that reach the controller directly (Wiegand), so the controller can decide autonomously.
• Casual / transient — printed ticket, pay-on-exit, or plate recognition. These are inherently host-side identity sources.

How reads reach the system

Reader type	Who sees the read	Decision made by	Offline autonomy
Wiegand reader → UHPPOTE port	The controller	Controller (onboard card list)	Yes — works if host is down
Pure TCP/IP reader (no Wiegand out)	Host only	Host, then commands relay via UDP open	No — host on critical path
LPR camera / QR ticket scanner	Host only	Host	No

Key points

• Pure network readers are invisible to the UHPPOTE. The board only generates events for its own terminals (Wiegand reads, door sensors, buttons, remote opens). So for a pure-TCP reader, only the host can listen, the host decides, and the host commands the relay. The controller is demoted to a commanded relay for that lane (and its onboard card DB / offline autonomy is bypassed).
• Check for a Wiegand output first. Many "network" readers (e.g. Nedap/UHF units) have both a network interface and a Wiegand output. Wire the Wiegand output into the UHPPOTE reader port and you keep autonomous decisioning and the native event log, with the network port available for other uses. This sidesteps the host dependency entirely.
• Both models can share one relay. A UHPPOTE door relay opens on either a valid Wiegand read on its reader port or a host open command (when door control mode = "controlled"). So one lane can serve permit holders via Wiegand (autonomous) and casual/LPR via host command, on the same relay.
• Host-in-the-loop is good for fraud detection. When the host decides and commands the open, you get two independent records — the host's signed log entry (reader/plate/card identity) and the UHPPOTE remote-open event. They should reconcile one-to-one; any mismatch is an anomaly to flag.

Note on autonomy: if remote-host control is enabled on the controller, it expects the host to communicate at least every ~30 s or it reverts to local (onboard-card) control. Relevant only to Wiegand-on-board lanes.

---

9. Recommended devices (reference BOM)

Models to verify for local availability (Albania/EU); the payment terminal is dictated by the acquiring bank.

Subsystem	Recommendation	Why
Barrier operator	Magnetic Autocontrol / FAAC / CAME / Nice	Owns physical safety in firmware
Induction loops	Feig / BEA / EMX	Safety + free-exit detection
Access controller	UHPPOTE now → ZKTeco later	Reader + relay; isolate the VLAN
Permit readers	Nedap/Kathrein UHF, or Mifare → Wiegand	Hands-free, or autonomous offline decisions
Casual identity	Milesight LPR (edge AI, offline-capable)	Plate = ticket + independent record
Ticket dispenser	Custom VKP80	Parking-grade thermal/ESC-POS
Booth printer	Epson TM / Citizen (USB or network)	ESC/POS; same adapter covers both transports
Payment	Bank-certified P2PE standalone terminal + cash drawer	Keeps the app out of PCI-DSS scope
Host machine	Fanless industrial PC + UPS + ATECC608	Reliability, power-loss safety, offline signing
Network	Managed VLAN switch, PoE+	Isolate the open control protocol

LPR note: edge-AI LPR cameras run recognition on-device and keep working with no internet, which fits the offline-first constraint. Mount within ~15° of vehicle travel at a controlled chokepoint for best reads.

---

10. Open decisions / next steps

These are not yet decided and should be settled before procurement, because they drive everything else:

1. Lane topology. One host per lane, or one central host driving networked devices in each lane? This decides how many controllers, printers, UPSs, and SQLite instances exist, and the failure blast radius. (A single central host is a single point of failure for all lanes.)
2. Failure modes. Define per direction what happens to barriers on host/power/network loss — particularly fail-open on exit for egress safety. Currently unaddressed.
3. Payment subsystem. Manned booth (P2PE terminal + cash drawer) vs unmanned pay station; confirm PCI scope is kept out of the application via a standalone certified terminal.
4. Reconciliation channel. Even if "offline," establish some periodic path (USB, hotspot, manager visit) to reconcile the signed log against an external authority — this is the real anti-fraud control.
5. Durability/backup. Backup strategy for the SQLite database and a recovery plan; "sync later" currently leaves a disk failure as total revenue-history loss.
6. Secure-element integration. Confirm ATECC608 wiring/usage on both the host (event signing) and, if pursued, the custom controller (command authentication).

---

Summary of standing decisions

• Stack: Turborepo · Fastify (Node) · React/Vite SPA · SQLite + Drizzle · local JWT auth. All MIT/Apache/BSD — no vendor lock, no rug-pull risk.
• Platform: dedicated, hardened Linux appliance (LUKS + GRUB password + Secure Boot), not Windows/WSL.
• Integrity: append-only, hash-chained, ATECC608-signed event log; reconciliation is the anti-fraud control, encryption protects only at-rest.
• Access control: UHPPOTE for now, on an isolated VLAN; event log used as a tamper-evident audit source with host-side index tracking. Custom ESP32 controller documented as the prevention-grade upgrade path.
• Readers: prefer Wiegand-into-controller for permit holders (autonomous); host-in-the-loop for LPR/QR/pure-network readers; both can share a relay.