# riteshkumar-devs/greeen-track architecture

> Architecture diagram of the GitHub repository riteshkumar-devs/greeen-track, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riteshkumar-devs/greeen-track
- Repository: https://github.com/riteshkumar-devs/greeen-track

## Overview

GreenTrack is a campus waste-management app whose main workflow runs from bin registration and citizen check-in/reporting through admin dispatch to collector inspection and pickup. The React frontend defaults to browser-based mock data; the FastAPI backend currently exposes only health, and PostgreSQL is prepared for future tables rather than used by the demo workflows. Some frontend feature-to-service connections are supported by the SOURCE INDEX; unsampled implementation details are left out.

Main entry points: [`frontend/src/services/apiClient.ts`](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/services/apiClient.ts) (API Client), [`frontend/src/app/AppShell.tsx`](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/app/AppShell.tsx) (Workspace Shell), [`frontend/src/features/admin/AdminPortal.tsx`](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/admin/AdminPortal.tsx) (Admin Portal), [`frontend/src/features/collector/CollectorPortal.tsx`](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/collector/CollectorPortal.tsx) (Collector Portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspaces["Role Workspaces"]
  node_app_shell["Workspace Shell<br/>[AppShell.tsx]"]
  node_auth["Role Authentication<br/>[AuthContext.tsx]"]
  node_login["Role Login<br/>[RoleLoginPanel.tsx]"]
end

subgraph group_operations["Campus Operations"]
  node_citizen_portal["Citizen Portal<br/>[CitizenPortal.tsx]"]
  node_citizen_reports["Condition Reports<br/>[BinFeedback.tsx]"]
  node_admin_portal["Admin Portal<br/>[AdminPortal.tsx]"]
  node_bin_zones["Zones &amp; Bins"]
  node_collector_tasks["Collectors &amp; Tasks"]
  node_collector_portal["Collector Portal"]
end

subgraph group_routing_insights["Routing &amp; Insights"]
  node_routes["Route Operations<br/>[RoutesView.tsx]"]
  node_analytics["Activity Analytics<br/>[AnalyticsView.tsx]"]
  node_routing_service["Routing Service<br/>[routingService.ts]"]
  node_osrm["OSRM Routing"]
  node_google_maps["Google Maps"]
end

subgraph group_frontend_core["Frontend Core"]
  node_api_client["API Client<br/>[apiClient.ts]"]
  node_mock_api["Browser Mock API<br/>[mockApi.ts]"]
  node_api_types["API Data Types<br/>[api.ts]"]
  node_shared_components["Shared UI Components"]
end

subgraph group_backend["Backend Health"]
  node_health_route["Health Endpoint<br/>[health.py]"]
  node_health_schema["Health Schema<br/>[health.py]"]
  node_backend_app["FastAPI App<br/>[main.py]"]
end

node_citizen(("Citizen"))
node_collector(("Collector"))
node_admin(("Administrator"))

node_citizen -->|"opens workspace"| node_app_shell
node_collector -->|"opens workspace"| node_app_shell
node_admin -->|"opens workspace"| node_app_shell
node_app_shell -->|"renders"| node_login
node_app_shell -->|"renders"| node_citizen_portal
node_app_shell -->|"renders"| node_collector_portal
node_app_shell -->|"renders"| node_admin_portal
node_login -->|"authenticates via"| node_auth
node_citizen_portal -->|"renders"| node_citizen_reports
node_admin_portal -->|"renders"| node_bin_zones
node_admin_portal -->|"renders"| node_collector_tasks
node_admin_portal -->|"renders"| node_analytics
node_admin_portal -->|"renders"| node_routes
node_collector_portal -.->|"opens"| node_routes
node_routes -->|"requests routing"| node_routing_service
node_routing_service -->|"gets road distances"| node_osrm
node_collector_portal -->|"opens directions"| node_google_maps
node_citizen_portal -->|"sends requests"| node_api_client
node_citizen_reports -.->|"sends requests"| node_api_client
node_collector_portal -->|"sends requests"| node_api_client
node_collector_tasks -->|"sends requests"| node_api_client
node_analytics -->|"sends requests"| node_api_client
node_routes -.->|"sends requests"| node_api_client
node_auth -->|"sends requests"| node_api_client
node_api_client -->|"dispatches locally"| node_mock_api
node_api_client -->|"sends HTTP requests"| node_backend_app
node_backend_app -->|"registers route"| node_health_route
node_health_route -->|"returns schema"| node_health_schema
node_citizen_portal -->|"uses UI"| node_shared_components
node_collector_portal -->|"uses UI"| node_shared_components
node_bin_zones -->|"uses UI"| node_shared_components
node_api_client -->|"uses contracts"| node_api_types

click node_app_shell "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/app/AppShell.tsx"
click node_auth "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/app/AuthContext.tsx"
click node_login "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/auth/RoleLoginPanel.tsx"
click node_citizen_portal "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/citizen/CitizenPortal.tsx"
click node_citizen_reports "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/citizen/BinFeedback.tsx"
click node_admin_portal "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/admin/AdminPortal.tsx"
click node_bin_zones "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/admin/ZonesAndBinsView.tsx"
click node_collector_tasks "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/admin/CollectorsAndTasksView.tsx"
click node_collector_portal "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/collector/CollectorPortal.tsx"
click node_routes "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/routes/RoutesView.tsx"
click node_analytics "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/analytics/AnalyticsView.tsx"
click node_routing_service "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/services/routingService.ts"
click node_api_client "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/services/apiClient.ts"
click node_mock_api "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/mocks/mockApi.ts"
click node_api_types "https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/types/api.ts"
click node_shared_components "https://github.com/riteshkumar-devs/greeen-track/tree/main/frontend/src/components"
click node_health_route "https://github.com/riteshkumar-devs/greeen-track/blob/main/backend/app/api/v1/health.py"
click node_health_schema "https://github.com/riteshkumar-devs/greeen-track/blob/main/backend/app/schemas/health.py"
click node_backend_app "https://github.com/riteshkumar-devs/greeen-track/blob/main/backend/app/main.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_app_shell,node_auth,node_login toneBlue
class node_citizen_portal,node_citizen_reports,node_admin_portal,node_bin_zones,node_collector_tasks,node_collector_portal toneAmber
class node_routes,node_analytics,node_routing_service,node_osrm,node_google_maps toneMint
class node_api_client,node_mock_api,node_api_types,node_shared_components toneRose
class node_health_route,node_health_schema,node_backend_app,node_citizen,node_collector,node_admin toneIndigo
```

## Components

### Role Workspaces

- [Workspace Shell](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/app/AppShell.tsx): `frontend/src/app/AppShell.tsx`
- [Role Authentication](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/app/AuthContext.tsx): `frontend/src/app/AuthContext.tsx`
- [Role Login](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/auth/RoleLoginPanel.tsx): `frontend/src/features/auth/RoleLoginPanel.tsx`

### Campus Operations

- [Citizen Portal](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/citizen/CitizenPortal.tsx): `frontend/src/features/citizen/CitizenPortal.tsx`
- [Condition Reports](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/citizen/BinFeedback.tsx): `frontend/src/features/citizen/BinFeedback.tsx`
- [Admin Portal](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/admin/AdminPortal.tsx): `frontend/src/features/admin/AdminPortal.tsx`
- [Zones & Bins](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/admin/ZonesAndBinsView.tsx): `frontend/src/features/admin/ZonesAndBinsView.tsx`
- [Collectors & Tasks](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/admin/CollectorsAndTasksView.tsx): `frontend/src/features/admin/CollectorsAndTasksView.tsx`
- [Collector Portal](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/collector/CollectorPortal.tsx): `frontend/src/features/collector/CollectorPortal.tsx`

### Routing & Insights

- [Route Operations](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/routes/RoutesView.tsx): `frontend/src/features/routes/RoutesView.tsx`
- [Activity Analytics](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/features/analytics/AnalyticsView.tsx): `frontend/src/features/analytics/AnalyticsView.tsx`
- [Routing Service](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/services/routingService.ts): `frontend/src/services/routingService.ts`
- **OSRM Routing**
- **Google Maps**

### Frontend Core

- [API Client](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`
- [Browser Mock API](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/mocks/mockApi.ts): `frontend/src/mocks/mockApi.ts`
- [API Data Types](https://github.com/riteshkumar-devs/greeen-track/blob/main/frontend/src/types/api.ts): `frontend/src/types/api.ts`
- [Shared UI Components](https://github.com/riteshkumar-devs/greeen-track/tree/main/frontend/src/components): `frontend/src/components`

### Backend Health

- [Health Endpoint](https://github.com/riteshkumar-devs/greeen-track/blob/main/backend/app/api/v1/health.py): `backend/app/api/v1/health.py`
- [Health Schema](https://github.com/riteshkumar-devs/greeen-track/blob/main/backend/app/schemas/health.py): `backend/app/schemas/health.py`
- [FastAPI App](https://github.com/riteshkumar-devs/greeen-track/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Citizen**
- **Collector**
- **Administrator**

## Connections

- Citizen → Workspace Shell: opens workspace (evidence: `README.md`)
- Collector → Workspace Shell: opens workspace (evidence: `README.md`)
- Administrator → Workspace Shell: opens workspace (evidence: `README.md`)
- Workspace Shell → Role Login: renders (evidence: `frontend/src/app/AppShell.tsx`)
- Workspace Shell → Citizen Portal: renders (evidence: `frontend/src/app/AppShell.tsx`)
- Workspace Shell → Collector Portal: renders (evidence: `frontend/src/app/AppShell.tsx`)
- Workspace Shell → Admin Portal: renders (evidence: `frontend/src/app/AppShell.tsx`)
- Role Login → Role Authentication: authenticates via (evidence: `frontend/src/features/auth/RoleLoginPanel.tsx`)
- Citizen Portal → Condition Reports: renders (evidence: `frontend/src/features/citizen/CitizenPortal.tsx`)
- Admin Portal → Zones & Bins: renders (evidence: `frontend/src/features/admin/AdminPortal.tsx`)
- Admin Portal → Collectors & Tasks: renders (evidence: `frontend/src/features/admin/AdminPortal.tsx`)
- Admin Portal → Activity Analytics: renders (evidence: `frontend/src/features/admin/AdminPortal.tsx`)
- Admin Portal → Route Operations: renders (evidence: `frontend/src/features/admin/AdminPortal.tsx`)
- Collector Portal → Route Operations: opens
- Route Operations → Routing Service: requests routing (evidence: `frontend/src/features/routes/RoutesView.tsx`)
- Routing Service → OSRM Routing: gets road distances (evidence: `README.md`)
- Collector Portal → Google Maps: opens directions (evidence: `README.md`)
- Citizen Portal → API Client: sends requests (evidence: `frontend/src/features/citizen/CitizenPortal.tsx`)
- Condition Reports → API Client: sends requests
- Collector Portal → API Client: sends requests (evidence: `frontend/src/features/collector/CollectorPortal.tsx`)
- Collectors & Tasks → API Client: sends requests
- Activity Analytics → API Client: sends requests (evidence: `frontend/src/features/analytics/AnalyticsView.tsx`)
- Route Operations → API Client: sends requests
- Role Authentication → API Client: sends requests (evidence: `frontend/src/app/AuthContext.tsx`)
- API Client → Browser Mock API: dispatches locally (evidence: `frontend/src/services/apiClient.ts`)
- API Client → FastAPI App: sends HTTP requests (evidence: `README.md`)
- FastAPI App → Health Endpoint: registers route (evidence: `backend/app/main.py`)
- Health Endpoint → Health Schema: returns schema (evidence: `backend/app/api/v1/health.py`)
- Citizen Portal → Shared UI Components: uses UI (evidence: `frontend/src/features/citizen/CitizenPortal.tsx`)
- Collector Portal → Shared UI Components: uses UI (evidence: `frontend/src/features/collector/CollectorPortal.tsx`)
- Zones & Bins → Shared UI Components: uses UI (evidence: `frontend/src/features/admin/ZonesAndBinsView.tsx`)
- API Client → API Data Types: uses contracts (evidence: `frontend/src/services/apiClient.ts`)
