# manny2706/pitwatch-ai architecture

> Architecture diagram of the GitHub repository manny2706/pitwatch-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manny2706/pitwatch-ai
- Repository: https://github.com/manny2706/pitwatch-ai

## Overview

Pitwatch is a road-surveillance platform spanning a React admin dashboard, Django API and workers, ML inference, and a Flutter mobile client. The main admin workflow is login → protected analytics, reports, or nearby-hazard map → authenticated API requests → displayed results. Backend capabilities also cover report management, async detection, and email escalation; the README describes mobile drowsiness monitoring, but its Dart sources are absent from the supplied tree. Relationships for unsampled backend and mobile features are based on README statements, not source inspection.

Main entry points: [`FRONTEND/src/App.jsx`](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/App.jsx) (React dashboard), [`backend/pitwatch/reports/views.py`](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/reports/views.py) (Reports API), [`backend/pitwatch/ml/tasks.py`](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/tasks.py) (Async inference), [`FRONTEND/src/pages/DashBoardPage.jsx`](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/pages/DashBoardPage.jsx) (Analytics page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Admin dashboard"]
  node_app["React dashboard<br/>[App.jsx]"]
  node_auth["Admin login<br/>[Auth.jsx]"]
  node_guard["Route protection"]
  node_analytics["Analytics page<br/>[DashBoardPage.jsx]"]
  node_reportui["Reports page<br/>[ReportsPage.jsx]"]
  node_mapui["Live map<br/>[LiveMap.jsx]"]
  node_api_client["API endpoints<br/>[APIs.js]"]
  node_state["Dashboard state<br/>[statSlice.js]"]
end

subgraph group_api["Django services"]
  node_accounts["Accounts API<br/>[views.py]"]
  node_reports["Reports API<br/>[views.py]"]
  node_report_data[("Report records<br/>[models.py]")]
  node_summary["Dashboard summary<br/>[views.py]"]
  node_report_tasks["Report tasks<br/>[tasks.py]"]
end

subgraph group_inference["Detection"]
  node_ml_api["Detection API<br/>[views.py]"]
  node_inference_jobs[("Inference jobs<br/>[models.py]")]
  node_inference_task["Async inference<br/>[tasks.py]"]
  node_model["Model inference<br/>[model.py]"]
  node_model_assets["Model assets<br/>[main.py]"]
end

subgraph group_mobile["Mobile safety"]
  node_flutter["Flutter safety app"]
  node_drowsiness["Drowsiness monitor"]
end

node_analyst(("Admin / analyst"))
node_mobile(("Mobile user"))
node_email["Email provider"]
node_database[("PostgreSQL")]
node_celery["Redis / Celery"]

node_analyst -->|"uses"| node_app
node_app -->|"routes to"| node_auth
node_app -->|"protects routes"| node_guard
node_app -->|"routes to"| node_analytics
node_app -->|"routes to"| node_reportui
node_app -->|"routes to"| node_mapui
node_auth -->|"authenticates"| node_accounts
node_analytics -->|"requests summary"| node_summary
node_analytics -->|"updates"| node_state
node_reportui -->|"fetches reports"| node_reports
node_mapui -->|"nearby lookup"| node_reports
node_accounts -.->|"reads account data"| node_database
node_reports -.->|"reads and updates"| node_report_data
node_summary -.->|"summarizes"| node_report_data
node_reports -.->|"sends notifications"| node_email
node_reports -.->|"queues maintenance"| node_report_tasks
node_report_tasks -.->|"runs asynchronously"| node_celery
node_ml_api -.->|"queues detection"| node_inference_task
node_ml_api -.->|"runs inference"| node_model
node_inference_task -->|"calls"| node_model
node_inference_task -->|"updates job"| node_inference_jobs
node_inference_task -->|"creates detected report"| node_report_data
node_inference_task -.->|"dispatched through"| node_celery
node_model -.->|"uses weights"| node_model_assets
node_mobile -->|"uses"| node_flutter
node_flutter -->|"monitors driver"| node_drowsiness
node_drowsiness -->|"posts emergency context"| node_reports

click node_app "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/App.jsx"
click node_auth "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/components/Auth.jsx"
click node_guard "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/services/ProtectedRoutes.jsx"
click node_analytics "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/pages/DashBoardPage.jsx"
click node_reportui "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/pages/ReportsPage.jsx"
click node_mapui "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/pages/LiveMap.jsx"
click node_api_client "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/services/APIs.js"
click node_state "https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/services/statSlice.js"
click node_accounts "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/accounts/views.py"
click node_reports "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/reports/views.py"
click node_report_data "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/reports/models.py"
click node_summary "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/dashboard/views.py"
click node_report_tasks "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/reports/tasks.py"
click node_ml_api "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/views.py"
click node_inference_jobs "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/models.py"
click node_inference_task "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/tasks.py"
click node_model "https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/services/model.py"
click node_model_assets "https://github.com/manny2706/pitwatch-ai/blob/main/ML/PitWatch_YOLOv8_nano_AI_model/main.py"
click node_flutter "https://github.com/manny2706/pitwatch-ai/tree/main/APP/pitwatch"
click node_drowsiness "https://github.com/manny2706/pitwatch-ai/tree/main/APP/pitwatch"

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_app,node_auth,node_guard,node_analytics,node_reportui,node_mapui,node_api_client,node_state,node_mobile toneBlue
class node_accounts,node_reports,node_report_data,node_summary,node_report_tasks,node_database,node_celery toneAmber
class node_ml_api,node_inference_jobs,node_inference_task,node_model,node_model_assets toneMint
class node_flutter,node_drowsiness toneRose
class node_analyst,node_email toneIndigo
```

## Components

### Admin dashboard

- [React dashboard](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/App.jsx): `FRONTEND/src/App.jsx`
- [Admin login](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/components/Auth.jsx): `FRONTEND/src/components/Auth.jsx`
- [Route protection](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/services/ProtectedRoutes.jsx): `FRONTEND/src/services/ProtectedRoutes.jsx`
- [Analytics page](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/pages/DashBoardPage.jsx): `FRONTEND/src/pages/DashBoardPage.jsx`
- [Reports page](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/pages/ReportsPage.jsx): `FRONTEND/src/pages/ReportsPage.jsx`
- [Live map](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/pages/LiveMap.jsx): `FRONTEND/src/pages/LiveMap.jsx`
- [API endpoints](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/services/APIs.js): `FRONTEND/src/services/APIs.js`
- [Dashboard state](https://github.com/manny2706/pitwatch-ai/blob/main/FRONTEND/src/services/statSlice.js): `FRONTEND/src/services/statSlice.js`

### Django services

- [Accounts API](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/accounts/views.py): `backend/pitwatch/accounts/views.py`
- [Reports API](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/reports/views.py): `backend/pitwatch/reports/views.py`
- [Report records](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/reports/models.py): `backend/pitwatch/reports/models.py`
- [Dashboard summary](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/dashboard/views.py): `backend/pitwatch/dashboard/views.py`
- [Report tasks](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/reports/tasks.py): `backend/pitwatch/reports/tasks.py`

### Detection

- [Detection API](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/views.py): `backend/pitwatch/ml/views.py`
- [Inference jobs](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/models.py): `backend/pitwatch/ml/models.py`
- [Async inference](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/tasks.py): `backend/pitwatch/ml/tasks.py`
- [Model inference](https://github.com/manny2706/pitwatch-ai/blob/main/backend/pitwatch/ml/services/model.py): `backend/pitwatch/ml/services/model.py`
- [Model assets](https://github.com/manny2706/pitwatch-ai/blob/main/ML/PitWatch_YOLOv8_nano_AI_model/main.py): `ML/PitWatch_YOLOv8_nano_AI_model/main.py`

### Mobile safety

- [Flutter safety app](https://github.com/manny2706/pitwatch-ai/tree/main/APP/pitwatch): `APP/pitwatch`
- [Drowsiness monitor](https://github.com/manny2706/pitwatch-ai/tree/main/APP/pitwatch): `APP/pitwatch`

### Other components

- **Admin / analyst**
- **Mobile user**
- **Email provider**
- **PostgreSQL**
- **Redis / Celery**

## Connections

- Admin / analyst → React dashboard: uses
- React dashboard → Admin login: routes to (evidence: `FRONTEND/src/App.jsx`)
- React dashboard → Route protection: protects routes (evidence: `FRONTEND/src/App.jsx`)
- React dashboard → Analytics page: routes to (evidence: `FRONTEND/src/App.jsx`)
- React dashboard → Reports page: routes to (evidence: `FRONTEND/src/App.jsx`)
- React dashboard → Live map: routes to (evidence: `FRONTEND/src/App.jsx`)
- Admin login → Accounts API: authenticates (evidence: `FRONTEND/src/components/Auth.jsx`)
- Analytics page → Dashboard summary: requests summary (evidence: `FRONTEND/src/pages/DashBoardPage.jsx`)
- Analytics page → Dashboard state: updates (evidence: `FRONTEND/src/pages/DashBoardPage.jsx`)
- Reports page → Reports API: fetches reports
- Live map → Reports API: nearby lookup
- Accounts API → PostgreSQL: reads account data
- Reports API → Report records: reads and updates
- Dashboard summary → Report records: summarizes
- Reports API → Email provider: sends notifications
- Reports API → Report tasks: queues maintenance
- Report tasks → Redis / Celery: runs asynchronously
- Detection API → Async inference: queues detection
- Detection API → Model inference: runs inference
- Async inference → Model inference: calls (evidence: `backend/pitwatch/ml/tasks.py`)
- Async inference → Inference jobs: updates job (evidence: `backend/pitwatch/ml/tasks.py`)
- Async inference → Report records: creates detected report (evidence: `backend/pitwatch/ml/tasks.py`)
- Async inference → Redis / Celery: dispatched through
- Model inference → Model assets: uses weights
- Mobile user → Flutter safety app: uses
- Flutter safety app → Drowsiness monitor: monitors driver
- Drowsiness monitor → Reports API: posts emergency context
