---
type: concept
tags: [parking, domain, business, reporting]
sources: []
updated: 2026-07-05
status: open
---

# Reporting & Analytics

Turning the signed event log into the numbers an owner runs the business on. All reports are
**projections over the [[append-only-event-chain]]** — the chain is the single source, reports are
derived and rebuildable, never a separate ledger.

## Built — admin Reports dashboard v1 (2026-06-22)

A first cut shipped: an admin **Reports** screen — a **top-level section** at **`/reports`** with its
own header nav entry (not nested under Setup), gated on `report:read` — an on-demand **dashboard**
(not a live feed). Server aggregates everything in **one call**
(`GET /api/reports/summary?from&to&bucket`) so the SPA only renders; `…/summary.csv` exports the
per-bucket series. Code: `apps/server/src/reports.ts` (+ `routes/reports.ts`), `apps/web/src/Reports.tsx`.

- **Ledger-first** (decision 2026-06-22). Entry/exit **counts** and all **money** are summed
  straight from the signed `ledger_events` — the SAME source the `shift_z_report` reconciles, so a
  chart total always ties out to the drawer. The revenue **split** (transient ticket /
  subscription sale / out-of-window window-charge) mirrors the Z-report's split exactly
  (`subscriptionSale` / `subscriptionWindowCharge` payload flags). Duration/occupancy stats are the
  one exception: read from the derived `sessions` cache (pairing each entry with its exit on the
  chain by hand is awkward) — flagged as a cache, not the financial truth.
- **Site-timezone bucketing.** A "day"/"hour" bucket is **local wall-clock** in `siteConfig.timezone`
  (reuses `siteTz()`), so a 23:30Z entry lands on the right local date and the peak-hour histogram
  reads in wall-clock. Bucket grain: hour / day / month, with date-range presets (today / 7d / 30d / 90d).
- **Views:** KPI cards (entries, exits, revenue, payments, avg stay, current subscribers); entry/exit
  line; revenue bar (per bucket) + cash/card split; revenue-mix pie; **peak-hours** histogram
  (entries by local hour-of-day); a numeric breakdown (cash/card, the 3-way revenue split, closed
  sessions, avg/median stay, active subs + cars covered); subscription status counts + currently-valid
  coverage as of the range end. Charts via **Recharts** (MIT), **lazy-loaded** into its own bundle
  chunk so the booth never downloads it. Tested: `reports.test.ts` (10) pin the sums, the tz bucketing,
  the money split, duration stats, and subscription counts.

**Not yet** (deferred from the list below): anomalies/voids reporting, per-operator takings, the
plate/entry search (next section), PDF export, and a live dashboard. The `report:read` permission
already existed for "events feed, occupancy, future reports" — this is its first real consumer
beyond the feed.

## Reports (driven by the events already designed)

- **Revenue** — by day/week/shift, by tender (cash vs. card), gross vs. discounts vs. net. Source:
  `payment` events + [[validation-discounts|discount]] events + `shift_z_report` ([[shift]]).
- **Occupancy** — current ([[capacity-occupancy]]) and historical curve; peak times; turnover.
- **Stay analytics** — average/median duration, distribution; transient vs. [[subscription]] split.
- **Permit usage** — active permits, utilisation, concurrency vs. `maxConcurrent`.
- **Anomalies** — out-of-band opens, never-exited sessions, occupancy drift, over-validation —
  the `anomaly` events + reconciliation findings ([[reconciliation]]).

## Plate / entry search (admin lookup) — user-requested 2026-06-15

The admin can **search for an entry/session by licence plate** — *if the plate was captured* (by
the [[opencv-anpr-service|vision service]] or an LPR read; a pure-ticket transient has no plate).
Returns the matching session(s): entry/exit times, fee, payment, snapshot image. Useful for
disputes ("I was charged for a car that left earlier"), lost-ticket lookup, and incident review.

- Search keys: plate (when captured), ticket id, session id, time range.
- Read-only over the chain; surfaces the linked snapshot ([[lpr-camera]] `imageRef`) as evidence.
- Honest limit: **no plate → no plate-search hit.** The UI must say "not captured", not "no such
  car", so the absence isn't mistaken for a missing record.

## Properties

- **Offline** ([[offline-first]]): all computed locally from the local DB; no cloud BI dependency.
- **Reproducible**: a report run twice over the same chain gives the same answer; figures trace to
  signed events.
- **Export** for [[reconciliation]] / accounting (CSV/PDF) — the periodic external-authority path
  ([[open-questions]] #4).

## As-built additions (2026-07-05) — the parking-shaped graphics

Operator ask: "check /reports for improvements and meaningful graphics." The dashboard (Recharts,
ledger-first aggregation in `apps/server/src/reports.ts`) gained the three views that are
parking-specific rather than generic BI, plus fraud counters:

- **Occupancy curve** — cars-inside step-area over the range with the configured capacity as a
  red reference line. `occupancyStart` folds the ENTIRE prior ledger (voided entries excluded,
  clamped ≥0); each series point carries `occupancyEnd`. The at-a-glance answer to "when are we
  near full" — the input for capacity and dynamic-window decisions.
- **Entries heatmap (hour × day-of-week)** — 7×24 matrix (`entriesByDowHour`, row 0 = Monday,
  site-tz), rendered as a pure CSS-grid amber-intensity map. Shows weekday-vs-weekend and
  morning/evening patterns — the direct evidence for tariff windows (night rates, weekend cards,
  early-bird — see [[tariff-industry-survey]]). Replaces the flat entries-by-hour bar (strictly
  contains it).
- **Stay-duration histogram** — closed sessions bucketed at 30m/1h/2h/4h/8h/24h/tail
  (`stayHistogram`): where the ladder/up-to breakpoints should sit.
- **Look-closer counters** — voids + anomalies in range as KPI cards (accented when >0): a spike
  is exactly what the signed chain exists to surface (the operator is the threat model).
- Revenue bars now **stack cash vs card** per bucket (`cashMinor`/`cardMinor` on each point —
  the drawer's money vs the bank's); peak-occupancy KPI (`peak / capacity`); CSV export gained
  cash, card, occupancy_end columns. `localParts` now caches its Intl formatter per tz (was one
  `new Intl.DateTimeFormat` per ledger row).

## Open

- Which reports matter at launch vs. later; the export format/cadence.
- Dashboard (live) vs. on-demand reports.