PROJECT_TRACKER.md¶
High-level tracking for Chaverim ALPR Platform development progress.
Current Phase¶
Phase: Phase 0 - Foundation Status: 🟡 In Progress Started: 2025-12-29 Target Completion: TBD
Current Focus¶
- Finalize monorepo code structure (central/, edge/, shared/)
- Create shared detection schema definitions
Recent Completions¶
- Unified ingest service design (dual-mode: edge + central)
- Ingest Service PRP with implementation patterns
- Comprehensive CLAUDE.md with development workflows
- Architecture documentation (16 documents, 9 approved)
- Development workflow scripts (worktree-docker.sh, check-worktree.sh, db-schema.sh)
- Docker Compose configuration
- Documentation structure (architecture/, phases/, prp/, testing/)
- PRP system and templates
Remaining for Phase 0¶
- Monorepo code structure (central/, edge/, shared/)
- Shared Pydantic detection schema definitions
- CI/CD pipeline setup
Upcoming Next¶
- Phase 1: Central Server Core
Phase Overview¶
Before starting any phase: Check docs/prp/global.md first - it contains patterns that apply to ALL components.
Phase 0: Foundation¶
Status: 🟡 In Progress Started: 2025-12-29 Purpose: Project setup, monorepo structure, development environment, shared schemas
Key Deliverables: - [x] Development workflow scripts (worktree-docker.sh, check-worktree.sh, db-schema.sh) - [x] Docker Compose for central server (FastAPI, PostgreSQL, MinIO) - [x] Architecture documentation and design decisions - [x] Documentation structure (architecture/, phases/, prp/, testing/) - [ ] Monorepo code structure (central/, edge/, shared/) - [ ] Shared detection schema definitions (Pydantic models) - [ ] CI/CD pipeline setup
Architecture Docs Completed: | Document | Status | |----------|--------| | ARCHITECTURE.md | Living | | Detection Batching | Approved | | Alert Engine | Approved | | Rate Limiting (Backpressure) | Approved | | Data Retention | Approved | | Data Integrity | Approved | | Search | Approved | | API Key Management | Approved | | Edge Provisioning | Approved | | Two-Factor Authentication | Approved | | Camera Adapters | Living | | Ingest Service | Living | | Monorepo | Living | | Backup & DR | Draft | | Observability | Draft |
Documentation: docs/phases/phase-0-foundation/
Phase 1: Central Server Core¶
Status: 🔴 Not Started Purpose: Core backend API, database schema, user authentication, RBAC
Key Deliverables: - [ ] FastAPI application structure - [ ] PostgreSQL database schema (users, collectors, detections, images) - [ ] User authentication (JWT + Argon2id) - [ ] RBAC implementation (admin, operator, viewer roles) - [ ] Two-factor authentication (TOTP) - [ ] Collector API key management - [ ] Basic health endpoints
PRPs to Reference:
- docs/prp/global.md - Security patterns, error handling
- docs/architecture/api-key-management.md - API key lifecycle
- docs/architecture/two-factor-authentication.md - TOTP implementation
Documentation: docs/phases/phase-1-central-core/
Phase 2: Detection Ingestion & Storage¶
Status: 🔴 Not Started Purpose: Detection reception from edge collectors, image storage, collector management
Key Deliverables: - [ ] Detection ingestion API endpoint (multipart form-data) - [ ] Backpressure signaling (NOT rate limiting - never reject evidence) - [ ] API key authentication for collectors - [ ] MinIO image storage integration (full scene + plate crop) - [ ] Heartbeat endpoint (health monitoring + command delivery) - [ ] Command queue and acknowledgment system - [ ] Detection deduplication (30s window) - [ ] Collector health dashboard
PRPs to Reference:
- docs/architecture/detection-batching.md - Batch upload strategy
- docs/architecture/rate-limiting.md - Backpressure approach
- docs/architecture/data-integrity.md - WORM protection
Documentation: docs/phases/phase-2-ingestion/
Phase 3: Central Web UI¶
Status: 🔴 Not Started Purpose: Web interface for search, timeline, map visualization
Key Deliverables: - [ ] HTMX + Alpine.js + Tailwind CSS setup - [ ] Login/logout flow with 2FA - [ ] Plate search interface (exact + fuzzy with pg_trgm) - [ ] OCR-aware matching (normalized plate column) - [ ] Detection timeline view - [ ] Interactive map with camera locations (Leaflet.js) - [ ] Route visualization - [ ] Mobile-responsive design (field use)
PRPs to Reference:
- docs/architecture/search.md - Search implementation
- docs/prp/global.md - UI patterns
Documentation: docs/phases/phase-3-central-ui/
Phase 4: Alerting System¶
Status: 🔴 Not Started Purpose: Watchlist management, real-time alerts, user subscriptions
Key Deliverables: - [ ] Watchlist CRUD (plates, categories) - [ ] Async alert matching engine (decoupled from ingestion) - [ ] In-memory watchlist cache (O(1) lookups, 60s refresh) - [ ] User alert subscriptions - [ ] WebSocket real-time notifications - [ ] Telegram bot integration - [ ] Alert history and management UI
PRPs to Reference:
- docs/architecture/alert-engine.md - Alert processing design
Documentation: docs/phases/phase-4-alerting/
Phase 5: Edge Collector Core¶
Status: 🔴 Not Started Purpose: Edge collector application for Raspberry Pi
Key Deliverables: - [ ] Python application structure - [ ] Configuration management (YAML + remote config) - [ ] SQLite detection buffer with WAL mode (7-day retention) - [ ] Batch detection uploader with API key auth - [ ] Heartbeat loop (60s interval, polls for commands) - [ ] Command handler and acknowledgment - [ ] Device-bound credential encryption (Fernet + hardware ID) - [ ] Systemd service files
PRPs to Reference:
- docs/prp/ingest-service-prp.md - Dual-mode ingest patterns
- docs/architecture/edge-provisioning.md - Provisioning workflow
- docs/architecture/detection-batching.md - Batch upload specification
Documentation: docs/phases/phase-5-edge-core/
Phase 6: Camera Adapters¶
Status: 🔴 Not Started Purpose: Camera vendor integrations for edge collectors
Key Deliverables: - [ ] Abstract adapter interface - [ ] Hikvision ISAPI adapter (digest auth, ISUP events) - [ ] Unifi Protect adapter (API polling) - [ ] Detection transformer (normalize to standard schema) - [ ] Adapter configuration and testing
PRPs to Reference:
- docs/architecture/camera-adapters.md - Adapter pattern
Documentation: docs/phases/phase-6-adapters/
Phase 7: Edge Local UI¶
Status: 🔴 Not Started Purpose: Local web UI for edge collector setup and diagnostics
Key Deliverables: - [ ] Flask + HTMX minimal app - [ ] QR code claim workflow (field-friendly) - [ ] Status dashboard (queue depth, camera status, connectivity) - [ ] Camera configuration interface - [ ] Network diagnostics - [ ] PIN authentication for config changes
PRPs to Reference:
- docs/architecture/edge-provisioning.md - Claim code workflow
Documentation: docs/phases/phase-7-edge-ui/
Phase 8: Production Deployment¶
Status: 🔴 Not Started Purpose: Production deployment, monitoring, documentation
Key Deliverables: - [ ] Production Docker Compose configuration - [ ] TLS certificate setup (Let's Encrypt) - [ ] Nginx reverse proxy configuration - [ ] SD card image builder for edge collectors - [ ] Deployment documentation - [ ] Monitoring and alerting setup (Prometheus/Grafana) - [ ] Log aggregation (decision pending: OD-001) - [ ] Backup implementation (decision pending: OD-002, OD-003)
Open Decisions Blocking This Phase: - OD-001: Log aggregation platform - OD-002: Backup target host - OD-003: Cloud backup approval
Documentation: docs/phases/phase-8-deployment/
Feature Summary¶
Features with architecture documentation. See FEATURES.md for complete MVP and post-MVP feature lists.
| Feature | Phase | Architecture Doc |
|---|---|---|
| Multi-vendor camera support | 6 | camera-adapters.md |
| Offline resilience (7-day buffer) | 5 | detection-batching.md |
| High-frequency detection (1/sec) | 2 | rate-limiting.md |
| Real-time WebSocket alerts | 4 | alert-engine.md |
| Telegram notifications | 4 | alert-engine.md |
| Mobile-responsive UI | 3 | ARCHITECTURE.md |
| Image storage (MinIO) | 2 | data-retention.md |
| RBAC (admin/operator/viewer) | 1 | ARCHITECTURE.md |
| Two-factor authentication | 1 | two-factor-authentication.md |
| Plate search (exact + fuzzy) | 3 | search.md |
| OCR-aware matching | 3 | search.md |
| Evidence integrity (WORM) | 2 | data-integrity.md |
| Legal hold support | 2 | data-integrity.md |
| Edge claim-code provisioning | 7 | edge-provisioning.md |
| Device-bound credential encryption | 5 | edge-provisioning.md |
Priorities¶
High Priority¶
- Complete Phase 0 (monorepo structure, shared schemas)
- Phase 1-2: Core infrastructure must be complete before other work
- API key authentication system (blocks edge development)
Medium Priority¶
- Phase 3: Web UI (required for POC demo)
- Phase 4: Alerting system (core use case)
- Two-factor authentication (security requirement)
Low Priority / Future¶
- Phase 7: Edge local UI (collectors work without it)
- Native mobile app (post-POC)
- Evidence chain-of-custody export
- Road-based route visualization (OSRM/GraphHopper)
- Analytics dashboard
Active Blockers¶
| Issue | Impact | Phase | Status | Notes |
|---|---|---|---|---|
| None | - | - | - | - |
Open Architecture Decisions¶
See open-decisions.md for full details.
| ID | Decision | Status | Blocker For |
|---|---|---|---|
| OD-001 | Log aggregation platform | 🟡 Pending | Phase 8 |
| OD-002 | Backup target host | 🟡 Pending | Phase 8 |
| OD-003 | Cloud backup (S3/Glacier) | 🔴 Blocked | Phase 8 (security review) |
| OD-004 | MinIO replication strategy | 🟡 Pending | Post-POC |
Decisions Log (Recent)¶
Recent major decisions. See phase-specific decisions.md for complete history.
| Date | Decision | Rationale | Impact |
|---|---|---|---|
| 2025-12-30 | Unified ingest service | Single app with edge/central modes, shared adapters | Edge/central architecture |
| 2025-12-29 | Mandatory TOTP 2FA | Security requirement, no SMS/email fallback | Authentication |
| 2025-12-29 | Backpressure over rate limiting | Never reject evidence data | Detection ingestion |
| 2025-12-29 | Async alert processing | Decouple from ingestion for scalability | Alert engine |
| 2025-12-29 | In-memory watchlist cache | O(1) lookups, 60s refresh | Alert performance |
| 2025-12-29 | API key auth over mTLS | Simpler operations, no certificate rotation | Edge-central communication |
| 2025-12-29 | HTTP polling for commands | Single protocol, no broker to manage | Edge-central communication |
| 2025-12-29 | MinIO for image storage | S3-compatible, handles high-volume storage | Storage architecture |
| 2025-12-29 | Monorepo structure | Single repo for central, edge, shared code | Project organization |
| 2025-12-29 | Claim-code provisioning | Field-friendly, admin-controlled device admission | Edge provisioning |
| 2025-12-29 | Device-bound encryption | SD card theft protection | Edge security |
Metrics & Progress¶
Code Coverage¶
- Central Backend: N/A (not started)
- Central Frontend: N/A (not started)
- Edge Collector: N/A (not started)
Technical Debt¶
- None yet (new project)
Performance Benchmarks¶
- Detection ingestion: Target <100ms per batch
- Alert latency: Target 1-5 seconds
- Plate search: Target <500ms
- Timeline query: Target <1s for 1000+ detections
- WebSocket notification: Target <100ms
Resources & Links¶
- Architecture Documentation:
docs/architecture/ - Phase Documentation:
docs/phases/ - PRPs (Implementation Patterns):
docs/prp/ - Testing Documentation:
docs/testing/ - Open Decisions:
docs/architecture/open-decisions.md - API Documentation: TBD (OpenAPI generated)
Notes¶
- Update this file at the start and end of each phase
- Use phase-specific README.md for day-to-day task tracking
- Keep this file focused on high-level status and priorities
- Archive completed phases but keep summary visible
- Reference architecture docs for design details, PRPs for implementation patterns
Last Updated: 2025-12-30 (added Ingest Service architecture)