Recount Dashboard

AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md — bytetrack-counter
+
+## Architecture
+
+- **Edge AI counter**: RTSP camera → YOLO RKNN (NPU) → tracking → line-crossing → SQLite + JSON state → Flask dashboard.
+- **2 counter scripts**, only 1 deployed:
+  - `counter_live.py` — Jetson TensorRT variant (CUDA, NOT used on RK3588).
+  - **`counter_live_rknn_bytetrack.py`** — RK3588 with ByteTrack. **This is what systemd runs.** Reference for C++ port.
+- `batch_store.py` — shared SQLite persistence + batch state machine.
+- `counter_dashboard.py` — Flask dashboard on port 5000, same DB.
+
+## No build / test / lint
+
+There is no build system, no test framework, no linter config, no typechecker.  
+Do not try to run `pytest`, `ruff`, `mypy`, etc. — they don't exist here.
+
+## How to run
+
+```bash
+# Copy env (required, .env is gitignored)
+cp config.env.example .env
+
+# Venv (must use system-site-packages for RKNN toolkit)
+python3 -m venv --system-site-packages venv
+source venv/bin/pip install -r requirements.txt
+
+# Run counter (RK3588 only — needs rknn-toolkit-lite2 & RKNN model)
+PYTHONNOUSERSITE=1 venv/bin/python counter_live_rknn_bytetrack.py
+
+# Run dashboard
+PYTHONNOUSERSITE=1 venv/bin/python counter_dashboard.py
+```
+
+## Key environment & install quirks
+
+- **`PYTHONNOUSERSITE=1`** is mandatory when running from the venv — without it, system/user packages leak in.
+- **`.env` is gitignored** — always copy from `config.env.example` first.
+- **`numpy<2`** is required for `rknn-toolkit-lite2` compatibility.
+- **Install path in service files is `/opt/bytetrack-counter`** (not the `/opt/jetson-counter` mentioned in README/DEPLOY). The `.env.example` also reflects `/opt/bytetrack-counter`.
+- Service user is **`root`**, not `jetson` (despite README saying otherwise).
+- Two systemd units: `bytetrack-counter.service` + `bytetrack-counter-dashboard.service`.
+- `counter_live.py` (TensorRT) is Jetson-only and won't work on RK3588.
+
+## Code conventions
+
+- All config lives in `.env` (dotenv), read via `os.getenv()` at module top-level in each script.
+- The 3 counter scripts duplicate ~80% of each other (drawing helpers, batch loop, etc). Changes to logic may need replication across variants.
+- `batch_store.py` has its own threading (cutoff watcher, batch timeout timer) — thread safety is via a single `state_lock`.
+- The dashboard re-creates DB tables on startup (`_ensure_db()`) independently from `batch_store.py`.
+- No formal version tracking exists anywhere in this codebase.