# hafizardd/ecotraffic-gis architecture

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

- Interactive diagram: https://gitdiagram.com/hafizardd/ecotraffic-gis
- Repository: https://github.com/hafizardd/ecotraffic-gis

## Overview

EcoTraffic GIS is a real-time WebGIS for monitoring vehicle emissions across Yogyakarta. Its primary workflow runs CCTV imagery through vehicle detection and emission estimation, then presents camera and road-segment results on a live map and analytics dashboard. A separate segment workflow aggregates traffic observations into volume, VKT, and Tier-2 emissions; spatial layers and activity-grid scoring add geographic context, while Bang Jo provides a segment-oriented assistant. The graph combines README capabilities with sampled source; some route and frontend wiring is documented but not shown in the excerpts.

Main entry points: [`frontend/src/services/api.ts`](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/core/database.py`](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/core/database.py) (PostGIS database), [`backend/app/workers/tracking_worker.py`](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/workers/tracking_worker.py) (Camera tracking), [`backend/app/api/routes`](https://github.com/hafizardd/ecotraffic-gis/tree/main/backend/app/api/routes) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web dashboard"]
  node_dashboard["Dashboard shell<br/>[DashboardShell.tsx]"]
  node_map["Live map<br/>[MapView.tsx]"]
  node_camera_panel["Camera details<br/>[SidePanel.tsx]"]
  node_video_feed["Camera video<br/>[VideoFeed.tsx]"]
  node_analytics["Emission analytics"]
  node_activity_grid_ui["Activity grid<br/>[useActivityGrid.ts]"]
  node_chat_ui["Bang Jo chat<br/>[BangJoWidget.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_live_hook["Live emissions hook<br/>[useEmissions.ts]"]
end

subgraph group_api["API services"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_api_routes["API routes"]
  node_bangjo_service["Bang Jo services"]
end

subgraph group_vision["Vision and tracking"]
  node_tracking["Camera tracking<br/>[tracking_worker.py]"]
  node_detector["Vehicle detection<br/>[detector.py]"]
  node_cv_emissions["Camera emission factors"]
end

subgraph group_segments["Segment analytics"]
  node_segment_worker["Segment calculation"]
  node_segment_pipeline["Segment emissions"]
  node_activity_scoring["Activity scoring"]
end

subgraph group_state["Data and realtime"]
  node_database[("PostGIS database<br/>[database.py]")]
  node_redis[("Redis state and pub/sub")]
end

node_city_user(("City user"))
node_cctv(("CCTV feeds"))
node_browser(("Browser user"))
node_embedding_service["Embedding API"]

node_city_user -->|"views"| node_dashboard
node_dashboard -->|"shows"| node_map
node_dashboard -->|"opens"| node_analytics
node_map -->|"requests layers"| node_api_client
node_camera_panel -->|"requests details"| node_api_client
node_video_feed -->|"requests stream"| node_api_client
node_analytics -->|"fetches history"| node_api_client
node_activity_grid_ui -->|"fetches grid"| node_api_client
node_chat_ui -->|"sends questions"| node_api_client
node_api_client -->|"HTTP requests"| node_fastapi
node_live_hook -->|"hydrates emissions"| node_api_client
node_live_hook -->|"receives updates"| node_redis
node_fastapi -->|"mounts routes"| node_api_routes
node_api_routes -->|"reads and writes"| node_database
node_api_routes -->|"subscribes"| node_redis
node_api_routes -->|"resolves queries"| node_bangjo_service
node_bangjo_service -->|"loads embeddings"| node_database
node_bangjo_service -.->|"embeds query"| node_embedding_service
node_cctv -->|"supplies video"| node_tracking
node_tracking -->|"detects vehicles"| node_detector
node_tracking -->|"estimates emissions"| node_cv_emissions
node_tracking -->|"persists observations"| node_database
node_tracking -->|"publishes updates"| node_redis
node_segment_worker -->|"reads observations"| node_database
node_segment_worker -->|"calculates windows"| node_segment_pipeline
node_segment_pipeline -->|"persists results"| node_database
node_segment_worker -->|"publishes segment state"| node_redis
node_activity_scoring -->|"uses spatial data"| node_database
node_browser -->|"interacts"| node_dashboard

click node_dashboard "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Dashboard/DashboardShell.tsx"
click node_map "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Map/MapView.tsx"
click node_camera_panel "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Panel/SidePanel.tsx"
click node_video_feed "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Panel/VideoFeed.tsx"
click node_analytics "https://github.com/hafizardd/ecotraffic-gis/tree/main/frontend/src/components/Analytics"
click node_activity_grid_ui "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/hooks/useActivityGrid.ts"
click node_chat_ui "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Chatbot/BangJoWidget.tsx"
click node_api_client "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/services/api.ts"
click node_live_hook "https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/hooks/useEmissions.ts"
click node_fastapi "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/hafizardd/ecotraffic-gis/tree/main/backend/app/api/routes"
click node_bangjo_service "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/services/bangjo_retrieval.py"
click node_tracking "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/workers/tracking_worker.py"
click node_detector "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/cv/detector.py"
click node_cv_emissions "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/cv/emission_factors.py"
click node_segment_worker "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/workers/segment_calculation_worker.py"
click node_segment_pipeline "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/services/segment_emission_pipeline.py"
click node_activity_scoring "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/services/hex_activity_scoring.py"
click node_database "https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/core/database.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_dashboard,node_map,node_camera_panel,node_video_feed,node_analytics,node_activity_grid_ui,node_chat_ui,node_api_client,node_live_hook,node_city_user,node_browser toneBlue
class node_fastapi,node_api_routes,node_bangjo_service toneAmber
class node_tracking,node_detector,node_cv_emissions,node_embedding_service toneMint
class node_segment_worker,node_segment_pipeline,node_activity_scoring toneRose
class node_database,node_redis,node_cctv toneIndigo
```

## Components

### Web dashboard

- [Dashboard shell](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Dashboard/DashboardShell.tsx): `frontend/src/components/Dashboard/DashboardShell.tsx`
- [Live map](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Map/MapView.tsx): `frontend/src/components/Map/MapView.tsx`
- [Camera details](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Panel/SidePanel.tsx): `frontend/src/components/Panel/SidePanel.tsx`
- [Camera video](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Panel/VideoFeed.tsx): `frontend/src/components/Panel/VideoFeed.tsx`
- [Emission analytics](https://github.com/hafizardd/ecotraffic-gis/tree/main/frontend/src/components/Analytics): `frontend/src/components/Analytics`
- [Activity grid](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/hooks/useActivityGrid.ts): `frontend/src/hooks/useActivityGrid.ts`
- [Bang Jo chat](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/components/Chatbot/BangJoWidget.tsx): `frontend/src/components/Chatbot/BangJoWidget.tsx`
- [API client](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Live emissions hook](https://github.com/hafizardd/ecotraffic-gis/blob/main/frontend/src/hooks/useEmissions.ts): `frontend/src/hooks/useEmissions.ts`

### API services

- [FastAPI app](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/hafizardd/ecotraffic-gis/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Bang Jo services](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/services/bangjo_retrieval.py): `backend/app/services/bangjo_retrieval.py`

### Vision and tracking

- [Camera tracking](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/workers/tracking_worker.py): `backend/app/workers/tracking_worker.py`
- [Vehicle detection](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/cv/detector.py): `backend/cv/detector.py`
- [Camera emission factors](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/cv/emission_factors.py): `backend/cv/emission_factors.py`

### Segment analytics

- [Segment calculation](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/workers/segment_calculation_worker.py): `backend/app/workers/segment_calculation_worker.py`
- [Segment emissions](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/services/segment_emission_pipeline.py): `backend/app/services/segment_emission_pipeline.py`
- [Activity scoring](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/services/hex_activity_scoring.py): `backend/app/services/hex_activity_scoring.py`

### Data and realtime

- [PostGIS database](https://github.com/hafizardd/ecotraffic-gis/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **Redis state and pub/sub**

### Other components

- **City user**
- **CCTV feeds**
- **Browser user**
- **Embedding API**

## Connections

- City user → Dashboard shell: views
- Dashboard shell → Live map: shows
- Dashboard shell → Emission analytics: opens
- Live map → API client: requests layers
- Camera details → API client: requests details
- Camera video → API client: requests stream
- Emission analytics → API client: fetches history
- Activity grid → API client: fetches grid
- Bang Jo chat → API client: sends questions
- API client → FastAPI app: HTTP requests
- Live emissions hook → API client: hydrates emissions
- Live emissions hook → Redis state and pub/sub: receives updates
- FastAPI app → API routes: mounts routes
- API routes → PostGIS database: reads and writes
- API routes → Redis state and pub/sub: subscribes
- API routes → Bang Jo services: resolves queries
- Bang Jo services → PostGIS database: loads embeddings
- Bang Jo services → Embedding API: embeds query
- CCTV feeds → Camera tracking: supplies video
- Camera tracking → Vehicle detection: detects vehicles
- Camera tracking → Camera emission factors: estimates emissions
- Camera tracking → PostGIS database: persists observations
- Camera tracking → Redis state and pub/sub: publishes updates
- Segment calculation → PostGIS database: reads observations
- Segment calculation → Segment emissions: calculates windows
- Segment emissions → PostGIS database: persists results
- Segment calculation → Redis state and pub/sub: publishes segment state
- Activity scoring → PostGIS database: uses spatial data
- Browser user → Dashboard shell: interacts