devdocs/file_structure.md

File Structure Documentation

The AVIS project is organized as a modular monolith. This document outlines the purpose of each directory and significant files.

Root Directory

AVIS/
├── .env.example         # Template for environment variables
├── docker-compose.yml   # Orchestration for full-stack deployment
├── Dockerfile           # Docker container definition for the API
├── pyproject.toml       # Project metadata and tool configuration (Ruff, Mypy)
├── requirements.txt     # Python package dependencies
├── README.md            # Quickstart guide
└── Devdocs/             # Comprehensive system documentation

api/ (Presentation Layer)

Contains the FastAPI application entry point and route definitions.

• main.py: Bootstraps the FastAPI app, wires up dependencies, and defines HTTP endpoints (e.g., POST /images, GET /status).

core/ (Domain & Business Logic)

The heart of the application, broken down into specific bounded contexts.

• config.py: Pydantic settings loading the .env file configurations.
• schemas/: Contains the Pydantic models acting as the data contract.
  • __init__.py: Defines EvidenceGraph, Detection, Zone, Candidate, Violation, etc.
• pipeline/: The orchestrator for the 10-stage processing workflow. Passes data sequentially through the stages.
• preprocess/: OpenCV-based image enhancement (CLAHE, denoise, deblur).
• detect/: Wrappers for Ultralytics YOLOv8/11.
• graph/: Logic for associating raw detections into semantic relationships (e.g., calculating Intersection over Union to link riders to a motorcycle).
• rules/: Pure, deterministic functions that evaluate the Evidence Graph against predefined violation criteria.
• llm/: Provider-agnostic wrappers for interacting with Vision-Language Models (primarily Google Gemini).
• plates/: Integration with fast-alpr for OCR and regex validation of license plates.
• legal/: Static mappings that tie specific violations to the Motor Vehicles Act sections and fine amounts.
• quality/: The initial "Quality Gate" that analyzes exposure and blur to abstain from processing unusable images.
• storage/: Abstracted interfaces for saving structured data (Postgres via SQLModel) and blobs (MinIO/S3).
• queue/: Wrappers for the Redis background task queue.

frontend/ (User Interface)

The React + Vite single-page application for the dashboard.

• package.json: NPM dependencies including React, Vite, React Router, and Chart.js.
• src/: React components for image upload, reviewing the human-in-the-loop queue, and displaying analytics charts.
• vite.config.js: Vite build configuration.

configs/ (Deployment specific)

Contains JSON camera calibration files.

• e.g., cam_demo.json: Defines geometric polygons (stop_line, no_parking, lane vectors) specific to a single camera's field of view, critical for Tier C/D violations.

data/ and models/ (Assets)

• data/: Local storage directory (if not using MinIO) and labeled datasets for evaluation.
• models/: Directory to cache downloaded YOLO .pt weights and ONNX models to avoid redownloading.

docs/ (Original Specs)

Original foundational specifications for the project.

• DESIGN.md: The single source of truth for the architectural philosophy, evidence tiers, and routing logic.
• ROADMAP.md: Outlines the phased implementation plan.

eval/ (Evaluation Suite)

Scripts for measuring the performance of the pipeline.

• run.py: Executes the ablation study and calculates P/R/F1 scores.
• sample_dataset.json: Metadata linking test images to expected ground-truth violations.

tests/ (Test Suite)

• Contains unit tests (via Pytest) focused on the deterministic logic (Graph association, Rule Engine, Legal mappings) ensuring core business logic is sound without requiring heavy ML inference.