| # Architecture |
|
|
| AVIS (Automated Violation Intelligence System) is designed as a **production-credible modular monolith**. The architecture avoids the complexity of microservices while providing true horizontal scalability using a task queue. |
|
|
| ## 1. High-Level Architecture |
|
|
| The system consists of three main tiers: |
| 1. **Frontend**: A React + Vite dashboard for uploading images, reviewing flagged violations, and analytics. It features a dynamically themed Empty-State Hero dashboard, animated hardware-accelerated gradients, and real-time observability Trace Logs. |
| 2. **API & Worker Layer**: A FastAPI application that handles HTTP requests and a Redis-backed queue that processes the heavy computer vision (CV) workloads asynchronously. |
| 3. **Data Layer**: PostgreSQL for structured evidence and metadata, and MinIO (S3-compatible) for raw and annotated image storage. |
|
|
| ```mermaid |
| graph TD |
| Client[React Dashboard] -->|Upload Image| API[FastAPI API] |
| API -->|Enqueue Task| Queue[Redis Queue] |
| Queue -->|Consume Task| Worker[Background Worker] |
| |
| Worker -->|Read/Write Meta| DB[(PostgreSQL)] |
| Worker -->|Read/Write Images| Storage[(MinIO)] |
| API -->|Query Status| DB |
| ``` |
|
|
| ## 2. Technology Stack |
|
|
| ### Core Frameworks |
| - **Backend**: Python 3.11+, FastAPI, Uvicorn, Pydantic, SQLModel. |
| - **Frontend**: React, Vite, Chart.js. |
| - **Database**: PostgreSQL (JSONB for unstructured evidence graphs) via `psycopg`. |
| - **Object Storage**: MinIO. |
| - **Message Broker**: Redis (for background task queues). |
|
|
| ### ML & AI Components |
| - **Object Detection**: Ultralytics YOLO11/YOLOv8 (runs on CPU/GPU). Detects vehicles, persons, and traffic lights. |
| - **License Plate Recognition (ALPR)**: `fast-alpr` with ONNX runtime for detection and OCR. |
| - **Vision-Language Model (VLM)**: Google Gemini Flash (free tier via `google-genai`), used strictly as a verification and fallback layer for ambiguous cases. |
|
|
| ### Infrastructure & Deployment |
| - **Orchestration**: Docker Compose (`docker-compose.yml`) stands up the entire production-like environment (Postgres, Redis, MinIO, API). |
| - **Local Dev Mode**: A fast, zero-infra mode is supported using SQLite (instead of Postgres) and in-process background tasks (instead of Redis). |
|
|
| ## 3. Scalability Path |
|
|
| The monolith is built to scale out horizontally without architectural rewrites: |
| - **API Nodes**: Stateless, can be scaled out behind a load balancer. |
| - **CV Workers**: The heaviest workload (YOLO detection, OCR) is isolated to background workers consuming from Redis. Scaling means adding more worker nodes (potentially with GPUs). |
| - **Storage**: MinIO can be seamlessly replaced by AWS S3; PostgreSQL can be moved to a managed service like AWS RDS. |
| - **VLM API Limits**: The VLM is called sparingly (only for ambiguous cases), avoiding rate limits and keeping operational costs near zero. Results are hashed and cached to prevent redundant API calls. |
|
|
| ## 4. Key Design Patterns |
|
|
| - **Evidence Graph**: A typed graph structure representing detections (nodes) and their relationships (edges, e.g., `rides`, `has_plate`). This provides an explainable basis for the rules engine. |
| - **Deterministic Rule Engine**: Rules (like "triple riding") are pure functions evaluating the Evidence Graph. No ML is used for the *reasoning* step, making it 100% predictable and unit-testable. |
| - **Confidence Fusion**: A mechanism to blend raw detection confidence, rule evidence, and VLM confidence into a single actionable score. |
|
|
