Glossary

Standardized terminology for the Chaverim ALPR Platform. All documentation, code, and communications should use these terms consistently.

For reviewers: During /review-docs, verify terminology against this glossary.

Core Domain Terms

Term	Definition	Usage	Avoid
Detection	A single license plate recognition instance captured by a camera	detection, detections, Detection model	event, read, capture, hit, scan
Edge	Physical Raspberry Pi device deployed at a site	edge, edge device	node, sensor, Pi (in formal docs)
Collector	Software service running on an edge device that gathers detections from cameras and uploads to central	collector, Collector model	agent, daemon
Watchlist	Named group of license plates to monitor for alerts	watchlist, Watchlist model	alert list, watch group, plate list
Alert	Notification generated when a detection matches a watchlist entry	alert, Alert model	notification (use for delivery mechanism), warning
Subscription	User's registration to receive alerts for specific plates or watchlists	subscription	follow, watch

Technical Terms

Term	Definition
Heartbeat	Periodic status check from collector to central server (default: 60s interval). Also delivers pending commands.
Command	Configuration instruction sent from central to collector, delivered via heartbeat response.
Plate crop	Zoomed image of just the license plate region (~10-30KB).
Full scene	Complete camera view image at time of detection (~50-80KB).
Adapter	Camera vendor-specific integration module (e.g., Hikvision adapter, Unifi adapter).

System Components

Term	Definition	Avoid
Central server	Main server running FastAPI, PostgreSQL, MinIO	backend, hub, main server
Edge	Physical Raspberry Pi device at a deployment site	edge node, Pi, sensor
Collector	Software service on edge that interfaces with cameras	-
Ingest Service	Unified application that handles camera detection ingestion. Runs in edge mode (on Raspberry Pi with local buffering) or central mode (on central server for direct camera pushes, no buffering).	-
Web UI	Browser-based user interface (HTMX + Alpine.js)	frontend, dashboard (unless specific)
Local UI	Minimal Flask interface on collector for diagnostics	edge UI, setup interface

User Roles

Role	Description
Admin	Full system access including user management and system configuration
Operator	Can manage watchlists, view all detections, configure alerts
Viewer	Read-only access to detections and alerts

API Terminology

Term	Endpoint Pattern	Notes
Detection upload	POST /api/v1/detections/batch	Primary endpoint for collector uploads
Single detection	GET /api/v1/detections/{id}	Retrieve individual detection
Heartbeat	POST /api/v1/heartbeat	Collector status + command polling
Command ack	POST /api/v1/commands/{id}/ack	Collector confirms command applied

Abbreviations

Abbreviation	Meaning
ALPR	Automatic License Plate Recognition
ISAPI	Intelligent Security API (Hikvision protocol)
MVP	Minimum Viable Product
PRP	Project Reference Pattern
RBAC	Role-Based Access Control
WAL	Write-Ahead Logging (SQLite mode)

Why This Matters

"Detection" over "event": The term "detection" is domain-specific and immediately conveys what the data represents (a license plate recognition). "Event" is too generic and could mean anything (login event, error event, etc.).

"Edge" vs "Collector": "Edge" refers to the physical Raspberry Pi hardware deployed at a site. "Collector" is the software service running on the edge that interfaces with cameras and uploads detections. This distinction matters: you deploy an edge device, but you configure the collector software.

"Watchlist" over "alert list": Matches common ALPR industry terminology and distinguishes the list itself from the alerts it generates.

Adding New Terms

When introducing new domain concepts:

1. Check this glossary first - the term may already be defined
2. If new, propose the term with definition and rationale
3. Add to this glossary before using in code/docs
4. Avoid generic terms when domain-specific alternatives exist