# Schema Design

AVIS strictly types all internal data passing between pipeline stages. The core schema is the `EvidenceGraph`, built using Pydantic, which transforms raw machine learning detections into explainable geometric and semantic relationships.

## 1. The Evidence Graph Data Model

The `EvidenceGraph` is not a flat list of objects; it is a typed graph.

### Nodes

Every physical entity detected in the image is represented as a node. Nodes contain their spatial bounds (`BBox`) and ML confidence score.

- **`Vehicle`**: Represents cars, motorcycles, trucks, buses, or bicycles. Stores a `type`, `bbox`, and `confidence`. Also tracks which calibration zones it sits inside (`in_zones`).
- **`Person`**: Represents humans. Includes a `role` enum (`rider`, `driver`, `pedestrian`). Can carry attribute scores (e.g., `helmet: bool`, `seatbelt: bool`).
- **`Light`**: A traffic light. Tracks its `state` (`red`, `amber`, `green`, `unknown`).
- **`Plate`**: A cropped license plate. Tracks `text` (OCR output) and `regex_ok` (whether it matches standard Indian plate formats).
- **`Zone`**: A geometric area derived from the camera calibration file. Can be a `stop_line`, `no_parking`, or `lane` zone. Defined by a `polygon`.

### Edges

Edges define the relationships between nodes. A violation is essentially a small subgraph.

- **`rides`**: `Person` → `Vehicle:motorcycle`. Links a rider to a bike. Used for helmet and triple-riding rules.
- **`drives`**: `Person` → `Vehicle:car`. Links a driver to a car. Used for seatbelt rules.
- **`has_plate`**: `Vehicle` → `Plate`. Links OCR text to a specific vehicle.
- **`located_in`**: `Vehicle` → `Zone`. Determines if a vehicle has breached a calibration polygon.
- **`governed_by`**: `Vehicle` → `Light`. Links a vehicle to the specific traffic light dictating its allowed movement.

## 2. Violation Representation

When the Rule Engine identifies a violation subgraph, it generates structured records.

### `Candidate`

An intermediate object representing a potential violation before routing or VLM verification.
- `type`: E.g., `TRIPLE_RIDING`.
- `tier`: The evidence sufficiency tier (`A`, `B`, `C`, `D`).
- `subjects`: A list of node IDs involved in the violation (e.g., `["motorcycle_1", "rider_1", "rider_2", "rider_3"]`).
- `rule_score`: Mathematical confidence of the rule logic.

### `Violation`

The final output payload, destined for the database and e-challan generation.
- Inherits the `Candidate` data but adds the final ruling:
- `evidence_sufficiency`: `sufficient`, `candidate`, or `insufficient`.
- `scores`: A fused object containing `detection`, `rule`, `vlm`, and `fused` scores.
- `route`: How the decision was made (`auto_confirmed`, `vlm_confirmed`, `human_review`).
- `reason`: A human-readable, single-sentence justification.
- `legal`: A dictionary containing the `act`, `section`, and `fine` amount.
- `evidence_hash`: A SHA-256 hash of the original image to prove no tampering occurred.

## 3. Database Schema (PostgreSQL)

Because the `EvidenceGraph` is highly variable and deeply nested, AVIS does not use a strict relational schema for detections. Instead, it utilizes **JSONB columns** in PostgreSQL via SQLModel.

This provides:
1. **Relational Integrity**: Metadata (timestamp, camera ID, status) is stored in standard relational columns for fast indexing and queue management.
2. **Flexible Storage**: The entire `EvidenceGraph` and the resulting `Violation` JSON are dumped into a JSONB column. This allows querying the database for specific graph conditions using Postgres JSON operators while allowing the schema to evolve without heavy migrations.