File size: 3,459 Bytes
1c0c94d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | # 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.
|