# Data Flow Documentation

The AVIS data pipeline operates sequentially, passing an `EvidenceGraph` through 10 distinct processing stages. This ensures determinism and maintainability.

## Pipeline Architecture

The pipeline logic is executed by a background worker (or in-process runner) defined in `core/pipeline/`.

```mermaid
graph TD
    Upload([1. Image Upload]) --> Quality[2. Quality Gate]
    Quality --> Preprocess[3. Preprocessing]
    Preprocess --> Detect[4. Object Detection]
    Detect --> Graph[5. Scene Graph Association]
    Graph --> Attributes[6. Attribute Extraction]
    Attributes --> Rules[7. Rule Engine]
    Rules --> Fuse[8. Fuse & Route]
    Fuse --> VLM[9. VLM Verification]
    VLM --> Legal[10. Legal Mapping]
    Legal --> Output([11. Evidence Composer])
```

## Stage Descriptions

### 1. Ingestion
The image is received via the FastAPI endpoint (`POST /images`). It is saved to MinIO, and a metadata record is created in PostgreSQL with status `pending`.

### 2. Quality Gate (`core/quality/`)
Analyzes the image using OpenCV.
- Checks image resolution.
- Checks variance of Laplacian (for blur).
- Checks pixel intensity histograms (for extreme under/overexposure).
If the image fails, processing halts, and status becomes `undeterminable`.

### 3. Preprocessing (`core/preprocess/`)
Enhances the image non-destructively (original remains untouched).
- Applies CLAHE (Contrast Limited Adaptive Histogram Equalization).
- Reduces noise.
Output: A normalized image matrix passed to the detector.

### 4. Detection (`core/detect/`)
Ultralytics YOLOv8/11 models process the image.
- Identifies bounding boxes for vehicles, persons, and traffic lights.
- Generates raw `Detection` objects.

### 5. Scene Graph (`core/graph/`)
Converts raw detections into semantic relationships.
- Uses Intersection over Union (IoU) and bounding box geometry.
- Associates riders to motorcycles (`rides` edge).
- Associates drivers to cars (`drives` edge).
Output: An initialized `EvidenceGraph`.

### 6. Attribute Classifiers (`core/attributes/`)
Extracts localized details from crops.
- Evaluates helmet presence on riders.
- Uses `fast-alpr` to crop license plates and run OCR.
- Evaluates traffic light state (Red/Amber/Green).

### 7. Rule Engine (`core/rules/`)
Deterministic functions evaluate the `EvidenceGraph` to find violations.
- Example: The Triple Riding rule checks if a motorcycle node has > 2 `rides` edges.
- Creates `Candidate` objects with a rule-evidence score and assigns a Tier.

### 8. Fuse & Route (`core/pipeline/`)
Calculates a fused confidence score based on detection, attribute, and rule scores.
Assigns a routing action: `auto_confirmed`, `vlm_confirmed`, or `human_review`.

### 9. VLM Verify (`core/llm/`)
Triggered ONLY if the route is `vlm_confirmed`.
- Constructs a prompt and sends the specific image crop to the Vision-Language Model.
- Parses the JSON response to either confirm the violation or change the route to `abstain`/`human_review`.

### 10. Legal Mapping (`core/legal/`)
Deterministic lookup. Maps the violation type (e.g., `HELMET_NON_COMPLIANCE`) to the Indian Motor Vehicles Act section and assigns the corresponding fine amount.

### 11. Evidence Composer
Finalizes the output.
- Generates an annotated image overlay (bounding boxes, reasons, plate info).
- Computes a SHA-256 hash of the original image for tamper evidence.
- Saves the final `Violation` JSON document to PostgreSQL.