# poojitha20-b/illegal_dumping architecture

> Architecture diagram of the GitHub repository poojitha20-b/illegal_dumping, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poojitha20-b/illegal_dumping
- Repository: https://github.com/poojitha20-b/illegal_dumping

## Overview

VidTrace turns live or recorded CCTV footage into confirmed dumping verdicts and enforcement actions. The documented workflow runs perception, identity-preserving tracking, temporal memory and feature extraction, event inference, then agentic review; confirmed cases proceed to plate OCR or pedestrian face identification, challan creation, and notification. A Flask dashboard exposes violations and hotspots. The README documents this wider flow, while sampled source confirms selected components and runner actions; arrows for unsampled internals follow documented behavior rather than inspected implementation.

Main entry points: [`run_pipeline.py`](https://github.com/poojitha20-b/illegal_dumping/blob/main/run_pipeline.py) (Pipeline runner), [`dashboard/app.py`](https://github.com/poojitha20-b/illegal_dumping/blob/main/dashboard/app.py) (Review dashboard), [`hotspot/hotspot_manager.py`](https://github.com/poojitha20-b/illegal_dumping/blob/main/hotspot/hotspot_manager.py) (Hotspot manager), [`Layer5/agent.py`](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer5/agent.py) (Belief agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_perception["Video perception"]
  node_detection["Object detection<br/>[detector.py]"]
  node_trash["Trash detection<br/>[trash_detector.py]"]
  node_bins["Bin detection<br/>[bin_detector.py]"]
  node_tracking["Object tracking<br/>[tracker.py]"]
  node_bintracking["Bin tracking<br/>[bin_tracker.py]"]
end

subgraph group_reasoning["Temporal reasoning"]
  node_memory["Temporal memory<br/>[memory_manager.py]"]
  node_features["Behavior features"]
  node_inference["Dumping inference"]
  node_agent["Belief agent<br/>[agent.py]"]
  node_llm["LLM controller<br/>[llm_controller.py]"]
end

subgraph group_enforcement["Enforcement"]
  node_enhancer["Plate OCR<br/>[enhancer.py]"]
  node_faceid["Face identification<br/>[face_id_module.py]"]
  node_face_db[("Offender database<br/>[database.py]")]
  node_penalty["Challan manager<br/>[penalty_manager.py]"]
  node_delivery["Email delivery<br/>[delivery_agent.py]"]
end

subgraph group_operations["Review and records"]
  node_hotspots["Hotspot manager<br/>[hotspot_manager.py]"]
  node_hotspot_db[("Hotspot store<br/>[hotspot_manager.py]")]
  node_dashboard["Review dashboard<br/>[app.py]"]
end

node_cctv(("CCTV / video"))
node_pipeline["Pipeline runner<br/>[run_pipeline.py]"]
node_groq(("Groq service"))
node_smtp(("SMTP service"))
node_reviewer(("Enforcement reviewer"))

node_cctv -->|"provides footage"| node_pipeline
node_pipeline -->|"detects objects"| node_detection
node_pipeline -->|"detects trash"| node_trash
node_pipeline -->|"detects bins"| node_bins
node_pipeline -->|"tracks objects"| node_tracking
node_pipeline -->|"tracks bins"| node_bintracking
node_pipeline -->|"updates history"| node_memory
node_pipeline -->|"extracts behavior"| node_features
node_pipeline -->|"evaluates events"| node_inference
node_pipeline -->|"reviews candidates"| node_agent
node_agent -->|"requests verdict"| node_llm
node_llm -->|"calls model"| node_groq
node_pipeline -->|"resolves plates"| node_enhancer
node_pipeline -->|"identifies pedestrians"| node_faceid
node_faceid -->|"matches / records"| node_face_db
node_pipeline -->|"creates challan"| node_penalty
node_pipeline -->|"sends notice"| node_delivery
node_delivery -->|"sends email"| node_smtp
node_pipeline -->|"records location"| node_hotspots
node_hotspots -->|"reads / writes"| node_hotspot_db
node_reviewer -->|"reviews cases"| node_dashboard
node_dashboard -->|"reads violations"| node_penalty
node_dashboard -->|"reads hotspots"| node_hotspots

click node_pipeline "https://github.com/poojitha20-b/illegal_dumping/blob/main/run_pipeline.py"
click node_detection "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer1/detector.py"
click node_trash "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer1/trash_detector.py"
click node_bins "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer1/bin_detector.py"
click node_tracking "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer2/tracker.py"
click node_bintracking "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer2/bin_tracker.py"
click node_memory "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer3/memory_manager.py"
click node_features "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer3/feature_extractor.py"
click node_inference "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer4/dumping_inference.py"
click node_agent "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer5/agent.py"
click node_llm "https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer5/llm_controller.py"
click node_enhancer "https://github.com/poojitha20-b/illegal_dumping/blob/main/enhancer.py"
click node_faceid "https://github.com/poojitha20-b/illegal_dumping/blob/main/FaceID/face_id_module.py"
click node_face_db "https://github.com/poojitha20-b/illegal_dumping/blob/main/FaceID/database.py"
click node_penalty "https://github.com/poojitha20-b/illegal_dumping/blob/main/penalty_manager.py"
click node_delivery "https://github.com/poojitha20-b/illegal_dumping/blob/main/delivery_agent.py"
click node_hotspots "https://github.com/poojitha20-b/illegal_dumping/blob/main/hotspot/hotspot_manager.py"
click node_hotspot_db "https://github.com/poojitha20-b/illegal_dumping/blob/main/hotspot/hotspot_manager.py"
click node_dashboard "https://github.com/poojitha20-b/illegal_dumping/blob/main/dashboard/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_detection,node_trash,node_bins,node_tracking,node_bintracking,node_reviewer toneBlue
class node_memory,node_features,node_inference,node_agent,node_llm toneAmber
class node_enhancer,node_faceid,node_face_db,node_penalty,node_delivery toneMint
class node_hotspots,node_hotspot_db,node_dashboard toneRose
class node_cctv,node_groq,node_smtp toneIndigo
class node_pipeline toneTeal
```

## Components

### Video perception

- [Object detection](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer1/detector.py): `Layer1/detector.py`
- [Trash detection](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer1/trash_detector.py): `Layer1/trash_detector.py`
- [Bin detection](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer1/bin_detector.py): `Layer1/bin_detector.py`
- [Object tracking](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer2/tracker.py): `Layer2/tracker.py`
- [Bin tracking](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer2/bin_tracker.py): `Layer2/bin_tracker.py`

### Temporal reasoning

- [Temporal memory](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer3/memory_manager.py): `Layer3/memory_manager.py`
- [Behavior features](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer3/feature_extractor.py): `Layer3/feature_extractor.py`
- [Dumping inference](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer4/dumping_inference.py): `Layer4/dumping_inference.py`
- [Belief agent](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer5/agent.py): `Layer5/agent.py`
- [LLM controller](https://github.com/poojitha20-b/illegal_dumping/blob/main/Layer5/llm_controller.py): `Layer5/llm_controller.py`

### Enforcement

- [Plate OCR](https://github.com/poojitha20-b/illegal_dumping/blob/main/enhancer.py): `enhancer.py`
- [Face identification](https://github.com/poojitha20-b/illegal_dumping/blob/main/FaceID/face_id_module.py): `FaceID/face_id_module.py`
- [Offender database](https://github.com/poojitha20-b/illegal_dumping/blob/main/FaceID/database.py): `FaceID/database.py`
- [Challan manager](https://github.com/poojitha20-b/illegal_dumping/blob/main/penalty_manager.py): `penalty_manager.py`
- [Email delivery](https://github.com/poojitha20-b/illegal_dumping/blob/main/delivery_agent.py): `delivery_agent.py`

### Review and records

- [Hotspot manager](https://github.com/poojitha20-b/illegal_dumping/blob/main/hotspot/hotspot_manager.py): `hotspot/hotspot_manager.py`
- [Hotspot store](https://github.com/poojitha20-b/illegal_dumping/blob/main/hotspot/hotspot_manager.py): `hotspot/hotspot_manager.py`
- [Review dashboard](https://github.com/poojitha20-b/illegal_dumping/blob/main/dashboard/app.py): `dashboard/app.py`

### Other components

- **CCTV / video**
- [Pipeline runner](https://github.com/poojitha20-b/illegal_dumping/blob/main/run_pipeline.py): `run_pipeline.py`
- **Groq service**
- **SMTP service**
- **Enforcement reviewer**

## Connections

- CCTV / video → Pipeline runner: provides footage
- Pipeline runner → Object detection: detects objects
- Pipeline runner → Trash detection: detects trash
- Pipeline runner → Bin detection: detects bins
- Pipeline runner → Object tracking: tracks objects
- Pipeline runner → Bin tracking: tracks bins
- Pipeline runner → Temporal memory: updates history
- Pipeline runner → Behavior features: extracts behavior
- Pipeline runner → Dumping inference: evaluates events
- Pipeline runner → Belief agent: reviews candidates
- Belief agent → LLM controller: requests verdict
- LLM controller → Groq service: calls model
- Pipeline runner → Plate OCR: resolves plates
- Pipeline runner → Face identification: identifies pedestrians
- Face identification → Offender database: matches / records
- Pipeline runner → Challan manager: creates challan
- Pipeline runner → Email delivery: sends notice
- Email delivery → SMTP service: sends email
- Pipeline runner → Hotspot manager: records location
- Hotspot manager → Hotspot store: reads / writes
- Enforcement reviewer → Review dashboard: reviews cases
- Review dashboard → Challan manager: reads violations
- Review dashboard → Hotspot manager: reads hotspots