ALPR Edge

1. How to use this document

The document is written in layers so different readers can stop at the depth they need.

Diagrams are interactive: click any diagram to enlarge it, click again to shrink. Every diagram is generated from text sources, so it can be updated together with the code. Names such as PersistWorker or api/app.py refer to real classes and files in src/alpr_edge/, so any statement here can be traced to source.

2. Solution at a glance

2.1 The problem it solves

At a weighbridge or plant gate the client needs to know which vehicle is on the bridge, automatically, so the weight ticket is tied to a verified plate without a person typing it. ALPR Edge does this with cameras at the lane, a small GPU computer at the gate, and an API the client's software calls.

2.2 What happens, in one paragraph

An IR sensor sees a vehicle. The controller sends a line over USB-serial to the edge node (or the client's software calls POST /api/v1/webhook/verify). The node grabs the latest frame from the front, rear and top cameras, finds the plate in each image with an object-detection model, reads the characters with an OCR model, cleans and validates the text against the Indian plate format, compares the front and rear reads, decides PASS / FAIL, stores everything, and pushes the result to the client's WMS. When the WMS finishes weighing it posts the outcome back and the node pulses the boom controller with an RST frame. If a vehicle skips the weighment, the controller raises an alarm and the node forwards a SKIP alert to the WMS.

2.3 Design principles (why the code looks the way it does)

• Never block the caller. Trigger endpoints return 202 immediately; results are polled or pushed. Inference happens on background threads.
• Pre-warmed hardware. Cameras stay open and keep a rolling buffer, so a trigger just "dips" the latest frame instead of re-opening a device.
• One node, one lane. One process plus one SQLite file per site/lane. Simple to deploy and reason about; scale by adding nodes.
• Fail closed, never guess. Two different plates on front and rear are a forced FAIL. Short or malformed reads cannot report a high confidence.
• Everything is configurable at runtime where it is operational. Delays, camera sources, UART parsing strings, Bridge endpoints are operator settings stored in SQLite; models and security are YAML / environment only.
• Durable outcomes. A finished verification is always written to SQLite (a metadata-only "stub" row if the full write fails) so the poll always has a terminal answer.

2.4 Technology stack

3. Feature catalogue

4. The flows we have

The service contains several distinct flows that share the same recognition core. This table is the map; each flow is detailed in its own section.

4.1 The complete action workflow (one vehicle, end to end)

This is the whole story of a truck crossing the weighbridge in the UART-driven booth configuration: the IR / boom controller is wired to the edge node by USB-serial, the edge node pushes results to the WMS, and the WMS acknowledges the weighment back to the boom controller through the edge node.

%%{init: {"sequence": {"width": 260, "height": 46, "actorMargin": 70, "messageMargin": 34, "boxMargin": 8, "noteMargin": 10, "wrap": true, "useMaxWidth": true}}}%%
sequenceDiagram
  autonumber
  participant SITE as Site (IR sensors, boom controller)
  participant EDGE as ALPR Edge node
  participant WMS as Client WMS
  SITE->>EDGE: ENTRY line (vehicle at entry sensor)
  Note over EDGE,WMS: parse, debounce, open lane session,<br/>snap front + rear, store candidates
  SITE->>EDGE: MID line (vehicle on bridge)
  Note over EDGE,WMS: capture front + rear + top, detect + OCR,<br/>best-of-4, match, decide PASS / FAIL,<br/>persist to SQLite after output delay
  EDGE->>WMS: Bridge push (session_id, plates, images per settings)
  WMS-->>EDGE: ACK (received, length)
  Note over WMS: weigh vehicle, decide<br/>Success / Failed
  WMS->>EDGE: POST /webhook/weighment {session_id, status}
  alt status = Success
    EDGE->>SITE: RST + CRLF over the same serial port
    Note over SITE,EDGE: boom / signal logic proceeds
  else status = Failed
    EDGE-->>WMS: 200 (RST suppressed)
  end
  SITE->>EDGE: EXIT line (vehicle leaves)
  Note over EDGE,WMS: clear lane session
  opt vehicle skipped weighment
    SITE->>EDGE: ALERT:SKIP:LEFT
    EDGE->>WMS: POST skip alert (weighment_skip)
  end

Other wiring options described in docs/client-verify/integration-details.md use the same pipeline: Mode A (IR trigger reaches ALPR Edge; the client reads results from the history APIs) and Mode B (IR trigger reaches the WMS first, and the WMS calls POST /webhook/verify with its own ticket id as session_id so ANPR is bound to the weighment ticket). In both, the UART lane steps 1-4 are replaced by the trigger call and everything from capture onward is identical.

4.2 The operator screens

Everything above can be watched and operated from two browser screens served by the edge node itself. The screenshots below were taken from a running instance on the development host (looping demo footage as the camera source, auth disabled on loopback). Click any screenshot to enlarge it.

Verify Console (/verify) - the booth operator and commissioning screen

Six numbered tabs follow the life of a trigger. The header strip is visible on every tab: PIPELINE (from /health), QUEUED and IN FLIGHT (sessions waiting or being processed by the trigger pipeline) and P50 (median processing time of the last sessions, from the aggregator).

http://gate-node/verify - 01 Preview

123456

Figure A - Preview. Always-on camera feeds (MJPEG from GET /cameras/{id}/stream). Use it to confirm camera placement before going live.

1. Health strip: pipeline status, queue depth, in-flight sessions, P50 latency
2. Tabs 01-06: Preview, Capture, Results, Images, Audit, Settings
3. View filter: All / Front / Rear / Top, and Reload
4. FRONT feed (physical plate camera, capture.plate) - click a cell to focus it
5. REAR feed (capture.back)
6. TOP feed (capture.material)

http://gate-node/verify - 02 Capture

123456

Figure B - Manual capture. "Capture and process" issues the same POST /api/v1/webhook/verify a sensor trigger does, polls the session, and shows the answer. This example is a real PASS: both cameras read UK07CA9035, confidence 93.7 %, match outcome both_pass_match, total 860 ms.

1. Live health strip (P50 348 ms in this run)
2. Capture and process - trigger, then poll until terminal; the label shows "Success in 860 ms"
3. Cameras at trigger time - the three frames dipped from the ring buffers
4. Result strip: status, final_raw_text, ocr_confidence, match_outcome, session id and failure reason
5. Client payload - the exact JSON a client receives (images shortened to their length)
6. Frames from API - the stored JPEGs returned by the image endpoint

http://gate-node/verify - 03 Results

1234

Figure C - Result history. Metadata only, filtered by IST day (GET /webhook/verify/calls?day=&limit=50). Note the red row UK07CA903: both cameras agreed, but the read was one character short and its confidence (84.3 %) fell below the 85 threshold, so the system failed it instead of passing a doubtful plate.

1. Date (IST) and Load
2. Result list: green bar = PASS, red bar = FAIL, with plate, session id, time and match_outcome
3. A near-miss: matching plates but confidence 84.3 % < 85 = FAIL
4. Session detail - click a row to inspect its full JSON

http://gate-node/verify - 04 Images

123456

Figure D - Image fetch. Images are never part of the status payload; they are pulled on demand from GET /webhook/verify/calls/{session_id}/image.

1. Session id to look up
2. Camera selector: All / Front / Rear / Top
3. Optional overlays: Detection (bbox) and Plate crop (the annotated and crop query flags)
4. Fetch - opens the request shown in 5
5. The exact request that was issued
6. Returned frames; a viewer opens on click. Payload size is shown below (about 2.9 million base64 characters per 4K frame)

http://gate-node/verify - 05 Audit

1234

Figure E - Audit log. The in-memory log ring (GET /api/v1/logs) rewritten in plain language. It is the fastest way to see where time goes in a trigger: every stage line carries duration_ms and queue_wait_ms (Section 16.3).

1. Filters: current session, all events, follow, clear
2. Startup warnings (for example auth disabled on loopback)
3. Stage line: "Frames extracted from cameras"
4. Per-stage timings: duration in the stage and time waiting in the queue

Settings tab - what an operator can change without a restart

Settings are stored as operator preferences in SQLite and applied live (cameras hot-reload). Delays are scheduled on deadlines, so a waiting session never blocks the trigger behind it.

http://gate-node/verify - 06 Settings - Timing and Storage

Figure F - Timing and storage. Per-camera input delays and the output delay in milliseconds (0 or 5 ms to 10 minutes). The effective worst-case SLA (5.0 s here) is shown and is raised automatically when long delays are configured. Retention (days) and JPEG quality for stored frames.

http://gate-node/verify - 06 Settings - Client / Bridge push

Figure G - Client / Bridge push and Skip alert. Base URL, key, timeout (10 s) and attempts (3); transfer method Metadata, Base64 or Multipart with a POST path each; what-to-share groups; the WMS skip-alert switch and path (/api/v1/alerts/skip); connectivity tests Test POST and Test GET last. See Section 11.1 and 11.3.

http://gate-node/verify - 06 Settings - Hardware trigger (UART)

Figure H - Hardware trigger (UART). Port and baud, the ENTRY / MID / EXIT / LEFT / RIGHT strings, debounce (1500 ms), line template or regex, RST command and terminator, alert prefix, skip token and skip debounce (3000 ms), and the Open serial monitor button that shows live rx / tx lines. These fields let the edge node be aligned to any controller firmware without code changes (Appendix C).

Operator dashboard (/) - single scans and batch work

http://gate-node/

1234

Figure I - Dashboard. The original single-lane console (dark theme): upload an image or video, batch upload, and drive one server camera with Open / Capture / Close (an async scan, Section 9). Retake guidance and manual review of failed reads live here. A card links to the Verify Console.

1. Choose image / video and Batch upload
2. Camera controls: Open, Capture (burst), Close
3. Live camera view (JPEG preview)
4. Link to the 3-camera Verify Console

5. High-level architecture

5.1 System context

flowchart LR
  subgraph Field["Gate / weighbridge (physical site)"]
    IR["IR sensors +<br/>boom controller"]
    CF["Front plate<br/>camera"]
    CB["Rear plate<br/>camera"]
    CT["Top camera"]
  end
  subgraph Edge["ALPR Edge node - Jetson Orin / GPU PC"]
    NG["nginx :80<br/>reverse proxy"]
    API["alpr-serve<br/>FastAPI + workers :8000"]
  end
  WMS["Client WMS /<br/>weighment software"]
  OP["Operator browser<br/>Dashboard + Verify Console"]
  IR -- "UART lines (USB-serial)" --> API
  API -- "RST frame" --> IR
  CF & CB & CT -- "RTSP / HTTP / USB / file" --> API
  OP -- "HTTP(S)" --> NG
  WMS -- "POST verify, GET calls,<br/>POST weighment" --> NG
  NG --> API
  API -- "Bridge push +<br/>SKIP alert" --> WMS

5.2 Logical layers

The separation matters for maintenance: plate/ has no knowledge of HTTP or storage, so the same code serves the API, the job queue, the trigger pipeline, the CLI and the benchmark scripts.

5.3 Runtime / deployment view

• One process, many threads. uvicorn hosts the asyncio event loop; all pipeline stages are plain threads communicating through bounded queue.Queue objects.
• Restart safety. systemd restarts the service 5 s after a crash. Durable state (SQLite) survives; the in-memory verify aggregator does not (see Section 13.7).
• Network exposure. uvicorn binds to loopback by default. Binding to a LAN address is refused unless API-key / JWT auth is enabled.

6. Startup and model loading

Startup is the slowest thing the service ever does, and it is deliberately done once, before the server accepts traffic. All of it happens inside the FastAPI lifespan function in api/app.py.

flowchart TB
  A["Step 1 - Load configuration and logging<br/>uvicorn imports alpr_edge.api.app (run.sh sources .env first)<br/>AppSettings.load(): environment, then .env, then plate.yaml, then defaults"]
  B["Step 2 - Load model set A: get_pipeline()<br/>torch-first guard, PlateDetector (YOLO weights or ORT session), PlateOCR (TRT engine / ONNX / Paddle)<br/>SLOWEST STEP: library imports, weights, engines, CUDA context"]
  C["Step 3 - Safety checks and housekeeping<br/>validate_auth_settings (public bind without auth = refuse to start),<br/>rate limiters, CORS allowlist, retention sweep + VACUUM"]
  D["Step 4 - warmup_pipeline()<br/>dummy 1280x720 frame through detect + OCR<br/>one-time CUDA / cuDNN kernel init, logged as warmup_ms"]
  E["Step 5 - Start workers and cameras<br/>JobWorker (shares set A), preview cameras, open plate / back / material readers,<br/>start_supervisor(): 5 pipeline threads + reaper"]
  F["Step 6 - start_serial_trigger_from_prefs()<br/>UART reader thread, if enabled in operator prefs"]
  G["Step 7 - lifespan yields: server accepts traffic<br/>(nginx returns 502 until this point)"]
  A --> B --> C --> D --> E --> F --> G
  classDef slow fill:#fff4e5,stroke:#b45309,stroke-width:2px
  classDef lazy fill:#fdecea,stroke:#b42318,stroke-width:2px
  class B,D slow
  class E lazy

6.1 What is loaded, from where, by whom

OCR backend selection order (PlateOCR.__init__): if backend is tensorrt try the TRT engine, then rec.onnx; if onnx try rec.onnx; then optionally load the text detector when use_det is true. If nothing GPU-side loads: with gpu_strict=true the service refuses to start (no silent CPU fallback); otherwise it falls back to Paddle. The label reported by /health tells you which path is live: PP-OCRv4-TRT+det, PP-OCRv4-TRT, PP-OCRv4-ONNX+det or PP-OCRv4+det (Paddle).

6.2 Why startup takes time

Measured on the development host (CPU inference): pipeline load 6 s in the run used for the screenshots (3 - 10 s across earlier logs), warm-up 216 ms in that run (134 - 288 ms earlier; from logs/alpr-serve.log and the live run log). Jetson figures depend on storage and thermal state; record them on first commissioning from the same log lines: Loading plate pipeline… → pipeline.warmed → Pipeline ready.

6.3 Two model instance sets (important for memory and first-trigger latency)

6.4 GPU keep-alive

Laptop and embedded GPUs drop to a low-power state after roughly 10-15 s of idleness, and the next CUDA launch then stalls for seconds. While the async JobWorker has no jobs it runs a cheap detector pass every 5 s (_gpu_keepalive) on a 640×640 dummy frame to keep set A warm. Set B is kept warm only by real traffic.

7. Core recognition pipeline

Every flow (F1, F2, F3 and the CLI) ends up running the same blocks in src/alpr_edge/plate/. In the booth flow the blocks are spread across the DetectWorker and OcrWorker threads; in the async and sync flows they run inside PlatePipeline (plate/pipeline.py).

flowchart TB
  IN["Input frame(s), BGR"] --> Q{"Quality gate (CPU)<br/>Laplacian variance >= 50<br/>mean luma 15 .. 245"}
  Q -- "every frame unusable" --> QF["quality_fail<br/>blurry / too_dark / too_bright"]
  Q -- "at least one usable" --> DET["Detector.detect_all()<br/>resize to model input, run net,<br/>map boxes back to original"]
  DET --> GEO{"Geometry filter<br/>height >= 40 px, width/height<br/>within allowed aspect"}
  GEO -- "no box survives" --> ND["no_detection"]
  GEO -- "rank by conf x sqrt(area), keep max 3" --> CROP["crop_with_padding (5 %)"]
  CROP --> OCR["PlateOCR.read()<br/>see OCR internals"]
  OCR -- "empty text" --> OF["ocr_failed"]
  OCR -- "text" --> SEL["select_best_read()<br/>format valid, tier, conf x det conf, box area"]
  SEL --> CONS["build_consensus()<br/>majority vote across burst frames"]
  CONS --> VAL["apply_validation()<br/>sanitize, parse Indian format,<br/>fuzzy repair, RTO check, plausibility"]
  VAL --> TIER["Confidence tier<br/>high / medium / low / reject"]
  TIER --> RES["PlateResult<br/>text, region, confidence, status,<br/>validation_status, warnings"]

7.1 Block-by-block: what is called, when, and why it costs time

7.2 Inside the OCR block

flowchart TB
  A["Plate crop"] --> B["Optional HSRP margin trim<br/>(yaml default: never)"]
  B --> C["Optional morphology 'open' 3x3<br/>only when detector = rfdetr"]
  C --> D{"Active OCR backend"}
  D -- "tensorrt / onnx<br/>use_det = true" --> E1["Text detector det.onnx<br/>ONNX Runtime CUDA, DBNet<br/>resize <= 960, stride 32 -> quads"]
  E1 --> E2["Per text line: perspective crop<br/>48 px high, <= 320 wide<br/>rec.engine (TRT) or rec.onnx + CTC"]
  D -- "tensorrt / onnx<br/>use_det = false" --> F["Recognizer on whole crop"]
  D -- "paddle<br/>use_det = true" --> G["Paddle text-det + Paddle rec per line"]
  D -- "paddle bundled" --> H["PaddleOCR.predict() det + rec"]
  E2 --> I
  F --> I
  G --> I
  H --> I
  I["Drop tokens below rec_min_conf 0.5<br/>keep A-Z 0-9, drop symbol noise"] --> J["ocr_layout: de-duplicate overlaps,<br/>left-to-right, two rows top-to-bottom"]
  J --> K["merge lines + sanitize_plate_read<br/>(strip IND / chakra / HSRP junk)"]
  K --> L["OcrRead: text, confidence, region"]
  E2 -. "GPU error" .-> M["fall back to Paddle<br/>(blocked when gpu_strict)"]

• Preprocessing is detector-aware. Morphological "open" (erode then dilate, 3×3) is applied only when the detector is RF-DETR, because that detector produces tighter crops with thin strokes; YOLO crops stay raw. This is controlled by ocr.preprocess.apply_when.
• Recognition details. Each text line is resized to 48 px high (at most 320 px wide, width rounded to a multiple of 8), normalised and passed through the recogniser; output is decoded with CTC (blank removal and repeat collapse) against the PP-OCRv4 English dictionary. The confidence is the mean of the kept character scores.
• Layout join. Tokens are de-duplicated when boxes overlap (e.g. a screw read as a digit), ordered left-to-right, and two-row plates are joined top row then bottom row.
• Fallback. If the GPU OCR path raises, the reader falls back to Paddle unless gpu_strict forbids it, in which case the read returns nothing and is logged as ocr.gpu_failed_strict.
• Optional retry. With blur_retry_on_fail enabled (off by default), a failed read is retried on the full frame with everything outside the plate box blurred. It adds ~0.8 s only when the first read failed validation.

7.3 Validation and confidence, explained

8. Flow F1 - Booth verify (3-camera, fast-async)

This is the production flow. It is the most detailed part of the code, so it is described from four angles: entry points, threads and queues, the finalisation logic, and the client contract.

8.1 Entry points

Both call the same function in trigger_pipeline/orchestrator.py (submit_trigger / submit_lane_event), which is the single choke point for triggers.

8.2 The lane (multi-phase) sequence

%%{init: {"sequence": {"width": 128, "height": 46, "actorMargin": 14, "messageMargin": 34, "boxMargin": 8, "noteMargin": 10, "wrap": true, "useMaxWidth": true,"messageFontSize": 13}}}%%
sequenceDiagram
  autonumber
  participant IR as IR / controller
  participant SER as Serial reader
  participant ORC as orchestrator
  participant LANE as Lane store
  participant AGG as Aggregator
  participant PIPE as Capture-detect-OCR
  participant PER as Persist
  participant WMS as WMS
  IR->>SER: ENTRY line (e.g. EVT:LEFT_ENTRY)
  Note over SER: parse (template or regex), debounce 1.5 s
  SER->>ORC: submit_lane_event (entry, left)
  ORC->>LANE: open_entry() - lane_busy raises TRIGGER_BUSY
  ORC->>AGG: begin(session, defer_persist=true)
  ORC->>PIPE: CaptureTask roles front + back
  PIPE->>AGG: plate results
  AGG->>LANE: record_entry_plates() - NO persist yet
  IR->>SER: MID line (vehicle on bridge)
  SER->>ORC: submit_lane_event (mid, left)
  ORC->>LANE: mark_mid()
  ORC->>PIPE: CaptureTask roles front + back + top
  PIPE->>AGG: plate results + top
  AGG->>LANE: merge_mid_and_pick() - best of entry + mid per role
  Note over AGG: re-run match_front_back on winners
  AGG->>PER: PersistTask (pass / fail)
  Note over PER: hold for output_delay, write SQLite
  PER->>WMS: Bridge push (session_id, plates, images per prefs)
  IR->>SER: EXIT line
  SER->>ORC: submit_lane_event (exit, left)
  ORC->>LANE: mark_exit() - lane cleared, no capture

stateDiagram-v2
  [*] --> Idle
  Idle --> Open: ENTRY - snap front + rear, defer persist
  Open --> Open: second ENTRY rejected (lane_busy, 503)
  Open --> AwaitingExit: MID - add top camera, best-of-4, persist + Bridge
  Open --> Idle: TTL 120 s expired
  AwaitingExit --> Idle: EXIT - lane cleared
  AwaitingExit --> Open: new ENTRY replaces lane
  AwaitingExit --> Idle: TTL expired

• Role mask per phase: ENTRY captures {front, back}; MID captures {front, back, top}; legacy captures all three.
• Best-of-4: up to 2 front and 2 rear candidates (one per phase). _best() picks the highest confidence for each role, then the pair is re-matched. Candidates carry an ok flag so unvalidated OCR noise cannot win.
• Fixed lane mapping: by default the physical plate camera is always logical "front" and the back camera always "rear", regardless of the direction token. Only a genuinely bidirectional shared lane sets capture.bidirectional_lane: true, in which case RIGHT swaps the mapping and an unknown direction is flagged (direction_unknown) rather than guessed.

8.3 Threads, queues and who calls whom

flowchart TB
  T["submit_trigger /<br/>submit_lane_event"] -- "put_nowait, size 2<br/>Full = 503 TRIGGER_BUSY" --> QC[("capture<br/>queue")]
  QC --> CW["CaptureWorker<br/>deadline scheduler"]
  CW -- "latest_frame x3" --> CAMS["Camera ring buffers"]
  CW -- "DetectTask x2<br/>front, back" --> QD[("detect queue 8")]
  CW -- "Module2Task" --> QM[("module2 queue 4")]
  CW -- "set_capture / errors" --> AGG
  QD --> DW["DetectWorker<br/>YOLO or RF-DETR<br/>single thread"]
  DW -- "no crops" --> AGG
  DW -- "OcrTask (all crops)" --> QO[("ocr queue 8")]
  QO --> OW["OcrWorker<br/>PlateOCR + validate<br/>single thread"]
  QM --> MW["Module2Worker<br/>top-camera hook (stub)"]
  OW -- "set_plate" --> AGG["SessionAggregator<br/>in-memory fan-in"]
  MW -- "set_top" --> AGG
  AGG -- "front + back + top done" --> QP[("persist queue 16")]
  QP --> PW["PersistWorker<br/>min-heap by release time"]
  PW --> DB[("vehicle_verify_calls")]
  PW --> BR["Bridge push<br/>pool of 2"]
  RP["Reaper every 250 ms<br/>SLA sweep, stale sweep,<br/>restart dead workers"] -.-> AGG

8.4 How a session is finalised

flowchart TB
  E["set_capture / set_plate /<br/>set_top / mark_pipeline_error"] --> C{"front done AND<br/>back done AND top done?"}
  C -- "no" --> W["keep waiting<br/>poll shows processing"]
  C -- "yes" --> F{"Error code?<br/>ALL_CAMERAS_FAILED, SLA_TIMEOUT,<br/>PIPELINE_BACKPRESSURE, SHUTDOWN"}
  F -- "yes" --> ER["status = error"]
  F -- "no" --> M["match_front_back()"]
  M --> P{"defer_persist?<br/>(ENTRY phase)"}
  P -- "yes" --> LS["store candidates on LaneSession<br/>stop - nothing persisted"]
  P -- "no" --> MID{"phase = mid?"}
  MID -- "yes" --> BO["merge with ENTRY candidates,<br/>best per role, re-match"]
  MID -- "no" --> PT
  BO --> PT["build PersistTask<br/>on_finalize -> persist queue"]
  ER --> PT
  RP["Reaper: session older than<br/>SLA worst case (5 s default)"] -. "force" .-> ER

"Done" is deliberately broad: a camera that failed to give a frame, a detector that found no plate, an OCR that produced nothing, and a back-pressure drop all mark that camera done with an error string. That is why the client always receives a terminal answer and a per-camera reason in camera_errors (capture_failed, no_detection, ocr_failed, validation_rejected, PIPELINE_BACKPRESSURE, detect_error, ocr_error).

8.5 The PASS / FAIL decision

flowchart TB
  S["Front result + Rear result"] --> A{"How many reads are ok?"}
  A -- "none" --> R1["both_fail<br/>status FAIL"]
  A -- "one" --> R2["front_only / back_only<br/>confidence = OCR x plausibility x 100"]
  A -- "both" --> B{"Identical text?"}
  B -- "yes" --> R3["both_pass_match"]
  B -- "no" --> C{"Fuzzy-repairable to one<br/>shared candidate?"}
  C -- "yes" --> R3
  C -- "no" --> D{"Edit distance <= 1?"}
  D -- "yes" --> R4["both_pass_fuzzy_match<br/>higher-confidence camera wins"]
  D -- "no" --> R5["both_pass_mismatch<br/>forced FAIL - never guess<br/>between two different plates"]
  R2 --> T{"confidence >= 85 ?"}
  R3 --> T
  R4 --> T
  T -- "yes" --> PASS["status PASS"]
  T -- "no" --> FAIL["status FAIL"]

Confidence is reported on a 0-100 scale everywhere in the verify payload (ocr_confidence, front_confidence, back_confidence), and is the OCR confidence multiplied by the plausibility score.

8.6 Client contract: trigger, poll, fetch images

%%{init: {"sequence": {"width": 170, "height": 46, "actorMargin": 40, "messageMargin": 34, "boxMargin": 8, "noteMargin": 10, "wrap": true, "useMaxWidth": true}}}%%
sequenceDiagram
  autonumber
  participant C as Client / WMS
  participant A as FastAPI
  participant O as orchestrator
  participant P as Pipeline threads
  participant DB as SQLite
  C->>A: POST /api/v1/webhook/verify {session_id?}
  A->>O: accept_vehicle_verify()
  Note over O: idempotency check - DB row, then in-flight
  O->>P: CaptureTask into capture queue
  A-->>C: 202 {session_id, status: processing}
  Note over O,DB: capture, detect, OCR, match and persist run on background threads
  loop poll until terminal
    C->>A: GET /webhook/verify/calls/{id}
    A->>DB: lookup row
    alt row not written yet
      A-->>C: 200 status = processing (from aggregator)
    else finalized
      A-->>C: 200 pass / fail / error + plates, match_outcome, timing
    end
  end
  C->>A: GET .../calls/{id}/image (camera, annotated, crop)
  A->>DB: fetch stored JPEGs
  A-->>C: data-URL images (never in list or detail)

• Idempotency. If the client sends a session_id, a repeated POST with the same id returns the same session without a new capture (looked up first in the database, then among in-flight sessions). Without one the server generates a UUID.
• Back-pressure. If the capture queue is full the API returns 503 TRIGGER_BUSY; a busy lane (ENTRY while a lane is open) does the same. Clients should retry after a short delay.
• Payload sizes. Detail and list responses never carry images. A stored 4K frame is roughly 2 MB of base64 per camera at JPEG quality 80, so ?camera=all&annotated=true&crop=true can be large; retention and JPEG quality are the levers.
• Terminal statuses. pass, fail, error. The poll returns the terminal status as soon as the aggregator has finalised, even if the database write is still pending or failed.

9. Flow F2 - Async scans (upload or camera capture)

Used when the client already has images (POST /api/v1/scans, 1-16 frames) or wants the node to shoot a burst (POST /api/v1/cameras/{id}/capture). Work goes through a durable SQLite job queue so it survives restarts.

flowchart TB
  C["Client: POST /scans (1-16 frames)<br/>or POST /cameras/{id}/capture"] --> V["Validate upload<br/>magic bytes, <= 10 MiB, <= 40 MP<br/>decode + re-encode as JPEG"]
  V --> S["create session (or begin_retake)<br/>write burst to data/uploads/ref/plate/*.jpg"]
  S --> J1[("jobs: PLATE_DETECT")]
  S --> ACK["HTTP 202 {ref_id, status: queued}"]
  J1 --> W["JobWorker claims job<br/>fair vs webhook jobs"]
  W --> H1["handle_plate_detect<br/>quality gate, detect every frame"]
  H1 -- "quality_fail or no boxes<br/>early abort" --> FIN
  H1 -- "boxes found" --> J2[("PLATE_OCR successor<br/>frames cached in RAM")]
  J2 --> H2["handle_plate_ocr<br/>crop best box per frame, OCR,<br/>consensus, validate"]
  H2 --> FIN["_finish_scan<br/>write scan_pass / scan_fail, decide retake,<br/>apply output delay, audit log"]
  FIN --> WH[("WEBHOOK_PUSH job<br/>optional, HMAC-signed")]
  ACK --> POLL["Client polls GET /refs/{ref_id}<br/>queued, processing, completed,<br/>failed, needs_retake"]
  FIN --> POLL

stateDiagram-v2
  [*] --> RECEIVED
  RECEIVED --> PREPROCESSING: job claimed
  PREPROCESSING --> DETECTING: quality ok
  DETECTING --> RECOGNIZING: boxes found
  RECOGNIZING --> POSTPROCESSING
  POSTPROCESSING --> SAVING
  SAVING --> COMPLETED
  PREPROCESSING --> NEEDS_RETAKE: quality_fail
  DETECTING --> NEEDS_RETAKE: no_detection
  POSTPROCESSING --> NEEDS_RETAKE: ocr_failed / validation_reject
  NEEDS_RETAKE --> RECEIVED: resubmit same session_id (max 3 attempts)
  RECEIVED --> FAILED: processing_timeout / job dead
  DETECTING --> FAILED: processing_timeout
  RECOGNIZING --> FAILED: processing_timeout
  COMPLETED --> [*]
  FAILED --> [*]

9.1 Why there are two jobs

handle_plate_detect runs the quality gate and detects on every frame. If there is nothing to read it finishes early (saving OCR time). Otherwise it caches the decoded frames and boxes in RAM (burst_frame_cache) and atomically replaces itself with a PLATE_OCR job (enqueue_successor). handle_plate_ocr then picks up the cached frames (disk is the fallback), crops the best box in each, runs OCR, consensus and validation, and calls _finish_scan.

9.2 Retry, timeout and retake are three different mechanisms

The JobWorker claims jobs fairly: after inference_burst_before_webhook (8) consecutive inference jobs it gives due webhook jobs one turn so outbound delivery cannot starve.

10. Flow F3 - Synchronous plate endpoints

POST /api/v1/plate, /plate/view (with annotated and crop images), /plate/detect (boxes only) and /plate/ocr (OCR on a supplied crop) run inline on a worker thread (asyncio.to_thread) so the event loop stays free. They use model set A directly, so concurrency is limited to one inference at a time per GPU. They are intended for testing, calibration and diagnostics; production traffic should use F1 or F2. They are covered by the sync rate limit (60 per minute).

11. Flows F4 - F6: WMS integration

11.1 Bridge push to the WMS (F4)

flowchart TB
  P["PersistWorker saved the row"] --> S{"status in push_statuses<br/>and Bridge enabled?"}
  S -- "no" --> X["skip push"]
  S -- "yes" --> B["build_bridge_payload()<br/>share flags: session, plates,<br/>errors, timing, images"]
  B --> M{"payload_mode"}
  M -- "metadata" --> J1["JSON body"]
  M -- "base64" --> J2["JSON body + images{}"]
  M -- "multipart" --> J3["multipart: meta JSON + JPEG files"]
  J1 --> POST
  J2 --> POST
  J3 --> POST["POST base_url + mode path<br/>timeout_s, max_attempts (3)"]
  POST --> A{"2xx AND ack_ok?<br/>received = true and<br/>length == bytes sent"}
  A -- "yes" --> OK["delivered"]
  A -- "no" --> G["GET last-session path:<br/>already stored?"]
  G -- "yes" --> REC["recovered_via_get_last"]
  G -- "no" --> RT{"attempts left?"}
  RT -- "yes" --> POST
  RT -- "no" --> FL["failed - use POST<br/>/bridge/sessions/{id}/retry"]

• Configured entirely in the Verify Console Settings (stored in operator prefs): base URL, API key, paths per mode, timeout (10 s), attempts (3), which statuses to push, which data groups to share (session, plates, errors, timing) and which images (front, rear, top, annotated, crop).
• Acknowledged delivery. A push counts as delivered only when the response is 2xx and the body says received: true with a length equal to the number of bytes sent. If the POST fails, the node checks the WMS's "last session" endpoint in case the row already arrived (recovered_via_get_last).
• Manual retry. POST /api/v1/bridge/sessions/{session_id}/retry re-pushes a stored session.

11.2 Weighment result and the RST frame (F5) / 11.3 SKIP alert (F6)

%%{init: {"sequence": {"width": 200, "height": 46, "actorMargin": 60, "messageMargin": 34, "boxMargin": 8, "noteMargin": 10, "wrap": true, "useMaxWidth": true}}}%%
sequenceDiagram
  autonumber
  participant CTL as Boom controller
  participant SER as SerialTriggerReader
  participant API as ALPR Edge API
  participant WMS as WMS / weighment software
  Note over API,WMS: A - weighment result closes the loop
  API->>WMS: Bridge push (session_id, plates, status)
  Note over WMS: capture weight, decide Success / Failed
  WMS->>API: POST /api/v1/webhook/weighment {session_id, status}
  Note over API: look up session (not rejected if missing), audit weighment_status
  alt status = Success
    API->>SER: send_rst()
    SER->>CTL: RST + CRLF (bytes 52 53 54 0D 0A)
    API-->>WMS: 200 rst_sent = true
  else status = Failed
    API-->>WMS: 200 rst_sent = false (RST suppressed)
  end
  Note over CTL,WMS: B - vehicle skipped weighment
  CTL->>SER: ALERT:SKIP:LEFT (heartbeat SYS:ALIVE:... ignored)
  Note over SER: parse_alert_line, debounce 3 s
  SER->>API: dispatch_skip_alert() on alert pool
  API->>WMS: POST {base_url}{skip_alert_path} weighment_skip
  WMS-->>API: any 2xx = accepted (retried up to max_attempts)
  Note over API: audit weighment_skip_alert

12. Where the time goes

This section answers "why does a verification take the time it does" for both a steady-state trigger and the exceptional cases.

12.1 Steady-state timeline of one booth trigger

gantt
  title One warm booth trigger (illustrative, ms after trigger)
  dateFormat x
  axisFormat %L
  section Capture thread
  Deadline wait (capture delay, 0 by default) : 0, 5
  latest_frame x3 + JPEG encode : 5, 45
  section Detect thread (single)
  Detect front camera : 45, 125
  Detect rear camera (queued behind front) : 125, 215
  section OCR thread (single)
  OCR front : 125, 195
  OCR rear : 215, 285
  section Finalize
  Aggregator match + persist queue : 285, 300
  SQLite write with base64 images : 300, 325

Two structural observations explain most of the total:

1. Detection is serialised. There is one detect thread, so the rear camera's detection starts only after the front's finishes (its queue_wait_ms in the logs is about equal to the front's duration). OCR of the front camera overlaps with detection of the rear camera, because they run on different threads.
2. Everything after OCR is small. Matching is microseconds, the SQLite write is tens of milliseconds (it stores base64 images), and the Bridge push is off the critical path.

12.2 Time budget by block

12.3 End-to-end figures

12.4 Concurrency and back-pressure

• Each verify stage is a single thread: throughput is roughly one trigger per (detect×2 + OCR) time. The capture queue holds up to 2 triggers not yet picked up by the capture thread; a further trigger gets 503 TRIGGER_BUSY instead of building an unbounded backlog. Safe sustained rate measured on the dev host: one trigger at a time.
• Stage queues (detect 8, OCR 8, module2 4, persist 16) time out enqueue after 1-2 s; a full queue marks that camera errored (PIPELINE_BACKPRESSURE) rather than blocking.
• The worst-case SLA (default 5 s, automatically raised to at least max capture delay + 30 s when delays are configured) is enforced by the reaper: anything older is finalised as error / SLA_TIMEOUT.
• Async scans queue in SQLite without bound; /ready returns 503 when pending jobs exceed 64 so a load balancer can drain the node.

13. Low-level architecture

13.1 Package and module map (src/alpr_edge/)

13.2 Thread inventory

13.3 Camera layer

• Sources: looping MP4 file (dev replay), USB webcam (OpenCV index), and named RTSP / HTTP streams (OpenCV, with an FFmpeg pipe reader; reconnect cool-down 2 s; bare http://host:8080 auto-tries /video and /videofeed). Camera settings (source mode, URLs, fps, width, height) live in operator prefs and hot-reload without restart.
• Ring buffer: each reader pushes every frame into a 30-frame RollingBuffer; latest_frame() is a lock-protected read of the newest entry, which is why a trigger costs almost nothing.
• Shared readers: camera ids resolving to the same file or URL share one reader (capture/shared.py, ref-counted). This removed a bug where three decoders on one MP4 drifted to three playback positions at triple the CPU cost.
• Roles: capture.plate = front, capture.back = rear, capture.material = top.

13.4 Data model

erDiagram
  sessions ||--o{ session_events : "stage timeline"
  sessions ||--o{ jobs : "work items"
  sessions ||--o{ scan_results : "reads"
  jobs ||--o{ webhook_deliveries : "attempts"
  sessions {
    text session_id PK
    text status
    text site_id
    text lane_id
    text current_stage
    real processing_time_ms
  }
  session_events {
    text session_id
    text stage
    text status
    real duration_ms
  }
  jobs {
    text id PK
    text type "plate_detect, plate_ocr, webhook_push"
    text status "pending, running, done, failed, dead"
    int attempts
    text next_run_at
    text last_error
  }
  scan_results {
    text session_id
    text plate_text
    real confidence
    text confidence_tier
    text validation_status
  }
  scan_pass {
    text session_id PK
    text plate_text
    real confidence
  }
  scan_fail {
    text session_id PK
    text status
    text image_base64
  }
  webhook_deliveries {
    text job_id
    text url
    int response_status
    int ok
  }
  audit_log {
    text event_type
    text actor
    text session_id
    text detail_json
  }
  vehicle_verify_calls {
    text id PK
    text client_session_id UK
    text status "pass, fail, error"
    real accuracy
    text ocr_front
    text ocr_back
    text image_front
  }
  client_prefs {
    text camera_id PK
    text payload_json
  }

13.5 Configuration model

13.6 Error model

13.7 Failure and recovery behaviour

13.8 Security model

• Authentication: shared API key (X-API-Key) and/or JWT from POST /api/v1/auth/token. Off by default on loopback; a non-loopback bind refuses to start without auth enabled, an API key and a JWT secret. MJPEG <img> streams authenticate with a short-lived JWT in ?api_key=, and access logs redact api_key / token query parameters.
• Input hygiene: uploads are checked by magic bytes, limited to 10 MiB and 40 megapixels, and re-encoded so original bytes are never stored; session ids must match a safe pattern (no path traversal).
• Abuse limits: in-process rate limits (sync scans 60/min, capture 20/min, token 20/min) plus nginx client_max_body_size 16m; CORS allowlist empty by default.
• Outbound integrity: webhooks are HMAC-signed.
• Host hardening: systemd unit uses NoNewPrivileges, PrivateTmp, ProtectSystem=full, and writes only to data/, logs/, models/. Secrets belong only in the device .env, never in git.

13.9 Operator interfaces

Screenshots and an element-by-element description are in Section 4.2.

14. API reference (summary)

All routes are under /api/v1 unless shown. Full request / response schemas are served live at /docs (OpenAPI) and mirrored in the Postman collections shipped with the project.

15. Configuration reference (key knobs)

The complete environment-variable list is in docs/ENV_REFERENCE.md.

16. Operations runbook

16.1 Deployment (Jetson)

1. deploy/setup_env.sh - system packages, uv virtual environment, install project with the OCR extra, seed .env.
2. deploy/setup_gpu_jetson.sh - Jetson-specific PyTorch / ONNX Runtime GPU wheels; writes GPU device and strict flags into .env.
3. deploy/pull_models.sh - unpack YOLO weights and the bundled RF-DETR package into models/; TensorRT engines are built on the board (deploy/export_tensorrt.sh), never copied from another machine.
4. Edit .env (auth key and JWT secret before any LAN bind).
5. sudo ./deploy/bootstrap_production.sh - installs and enables the alpr-serve systemd service and nginx; reboot-safe. deploy/run.sh runs it in the foreground for debugging.

16.2 Commissioning checklist

1. GET /healthz = alive; GET /ready = 200.
2. GET /health: confirm models labels (e.g. rfdetr/CUDAExecutionProvider/fp32 and PP-OCRv4-TRT+det), gpu_models_ok, trigger_pipeline.workers_alive all true.
3. Verify Console → Preview: all three cameras live and correctly placed.
4. Verify Console → Settings: set serial port, strings / template, Bridge URL and key; use Test and the serial monitor.
5. Fire one throw-away verify trigger to warm set B (Section 6.3), then run real triggers.
6. Confirm the WMS receives the Bridge push and that POST /webhook/weighment produces an » RST line in the serial monitor.

16.3 Reading the logs

Every stage logs one line with a stable key format, which makes latency analysis a matter of grep:

stage=capture  session_id=… duration_ms=66.5 queue_wait_ms=17.9 front=True back=True top=True extracted_ms=front:17.9/back:17.9
stage=detect   session_id=… camera=front duration_ms=79.5 queue_wait_ms=0.1  crops=1
stage=ocr      session_id=… camera=front duration_ms=58.3 queue_wait_ms=0.2  candidates=1 text=UK07CA9035 ok=True
stage=persist  session_id=… duration_ms=23.4 queue_wait_ms=6.7 status=pass output_delay_ms=0.0
trigger.finished session_id=… status=pass match_outcome=both_pass_match ocr_confidence=90.8 processing_duration_ms=311.9 phase=mid

duration_ms is the time in the stage; queue_wait_ms is time spent waiting for that stage's thread, which is the number to watch under load. Logs rotate at 10 MiB (10 backups, 14 days) under logs/; the live tail is at GET /api/v1/logs and in the Console Audit tab.

16.4 Housekeeping

At startup and every 300 s the retention sweep deletes expired sessions, scan history, audit rows, verify rows (with their images), jobs and webhook deliveries, rotated logs, debug dumps older than 3 days and orphan upload folders, then VACUUMs the database when rows were removed. Counters from the last sweep are in /health → retention.

16.5 Troubleshooting guide

17. Limitations, considerations and roadmap

Current limitations (be aware when planning)

• Single lane per process, SQLite per node. Scale by adding nodes; there is no shared central store, so a poll must reach the node that took the trigger.
• Two model instance sets (verify vs async / sync) double model memory; first booth trigger after restart is cold (Section 6.3).
• Verify sessions in flight are in memory. A process crash loses them; clients should re-trigger on 404.
• Serialised stages. One detect thread and one OCR thread per node; front and rear detections do not run in parallel.
• Recognition edge cases. Very small plates (below the 40 px height floor), heavy glare, stylised fonts, decorative symbols beside characters, and two-row square-ish truck plates outside the configured aspect range can fail or need a retake. These are input-quality issues, and the system fails closed (no guess) rather than reporting a wrong plate with high confidence.
• Top-camera analysis is a documented stub; the frame is captured and stored but not classified.
• Camera sources: no GStreamer / CSI source yet; RTSP needs FFmpeg present.
• Dependency locking: the checked-in uv.lock targets Windows; Jetson uses pinned JetPack wheels installed by the deploy scripts. On JetPack 7.2 there is no official Paddle GPU wheel, hence the TensorRT / ONNX OCR path.

Roadmap candidates

• Warm the verify models (set B) during startup or share set A with the trigger pipeline.
• Top-camera model behind the existing run_module2_top hook (material type / fill level).
• Parallel front / rear detection (batched or two detector workers) to cut steady-state latency.
• Shared store and load balancing across nodes; durable outbox for verify sessions.
• Optional fail-gated blur retry for difficult plates, subject to re-benchmarking.

Appendix

A. Glossary

B. Where to find things in source

C. UART line reference

Every string, the template / regex, the RST command and terminator, the alert prefix and skip token are operator settings, so the lines above are defaults and examples; they can be aligned to the client's controller firmware without code changes.

D. Companion documents in the project

• docs/ARCHITECTURE.md, docs/features.md, docs/ENV_REFERENCE.md, docs/security.md
• docs/client-verify/: hld.md, lld.md, api-layman.md, integration-details.md, partner hardware / Bridge / Jetson guides, system-simulation.html
• docs/weighment-integration.md, docs/deployment-orin.md, deploy/README.md, postman/ collections