# hodayashirazie/collecta architecture

> Architecture diagram of the GitHub repository hodayashirazie/collecta, 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/hodayashirazie/collecta
- Repository: https://github.com/hodayashirazie/collecta

## Overview

Collecta connects donors, drivers, and administrators through Flutter clients and Firebase-backed services. The principal flow is donor donation reporting: the client submits donation and pickup details, a Cloud Function records the donation and may assign it to a driver using activity-zone coverage; drivers then view routes and confirm pickups. Admin workflows cover donation and driver oversight, zone management, statistics, and driver impersonation. The Dart tree is documented in the README but absent from the supplied file tree, so client components use documented paths; backend links are limited to registrations and sampled calls.

Main entry points: [`lib/services/admin_service.dart`](https://github.com/hodayashirazie/collecta/blob/main/lib/services/admin_service.dart) (Admin service), [`functions/index.js`](https://github.com/hodayashirazie/collecta/blob/main/functions/index.js) (Function registry), [`functions/donations/reportDonation.js`](https://github.com/hodayashirazie/collecta/blob/main/functions/donations/reportDonation.js) (Report donation), [`lib/ui/screens/daily_route_driver.dart`](https://github.com/hodayashirazie/collecta/blob/main/lib/ui/screens/daily_route_driver.dart) (Driver screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter clients"]
  node_donor_ui["Donor screens"]
  node_driver_ui["Driver screens"]
  node_admin_ui["Admin screens"]
  node_donation_service["Donation service"]
  node_route_service["Route optimization"]
  node_admin_service["Admin service<br/>[admin_service.dart]"]
end

subgraph group_backend["Donation operations"]
  node_donation_api["Donation endpoints"]
  node_donation_report["Report donation<br/>[reportDonation.js]"]
  node_zone_api["Activity zones"]
  node_driver_profiles["Driver profiles"]
  node_route_api["Route endpoints"]
end

subgraph group_identity["Identity and profiles"]
  node_user_api["User roles"]
  node_uid_resolver["Identity resolver<br/>[resolveUid.js]"]
  node_function_registry["Function registry<br/>[index.js]"]
end

subgraph group_platform["Firebase and integrations"]
  node_firestore[("Cloud Firestore")]
  node_firebase_auth["Firebase Auth"]
  node_google_maps["Google Maps APIs"]
  node_route_optimizer["Route optimizer"]
end

node_donor(("Donor"))
node_driver(("Driver"))
node_admin(("Admin"))

node_donor -->|"reports donations"| node_donor_ui
node_donor_ui -->|"submits details"| node_donation_service
node_donation_service -.->|"calls endpoints"| node_donation_api
node_donation_report -->|"writes donation"| node_firestore
node_donation_report -->|"checks zone coverage"| node_firestore
node_donation_report -->|"assigns driver stop"| node_firestore
node_driver -->|"views route"| node_driver_ui
node_driver_ui -->|"requests optimization"| node_route_service
node_route_service -.->|"calls route function"| node_route_api
node_route_api -->|"builds traffic matrix"| node_google_maps
node_route_api -->|"posts route inputs"| node_route_optimizer
node_driver -->|"confirms pickups"| node_driver_ui
node_driver_ui -.->|"submits pickup"| node_donation_service
node_admin -->|"oversees operations"| node_admin_ui
node_admin_ui -->|"manages records"| node_admin_service
node_admin_service -.->|"queries donations"| node_donation_api
node_admin_service -.->|"manages drivers"| node_driver_profiles
node_admin_service -.->|"manages zones"| node_zone_api
node_admin_service -.->|"verifies admin"| node_user_api
node_function_registry -->|"registers endpoint"| node_donation_report
node_function_registry -->|"registers endpoints"| node_route_api
node_function_registry -->|"registers endpoints"| node_zone_api
node_function_registry -->|"registers endpoints"| node_user_api
node_driver_profiles -->|"resolves identity"| node_uid_resolver
node_uid_resolver -->|"verifies token"| node_firebase_auth
node_user_api -->|"stores role data"| node_firestore
node_zone_api -->|"reads zone data"| node_firestore

click node_donor_ui "https://github.com/hodayashirazie/collecta/blob/main/lib/ui/screens/report_donation.dart"
click node_driver_ui "https://github.com/hodayashirazie/collecta/blob/main/lib/ui/screens/daily_route_driver.dart"
click node_admin_ui "https://github.com/hodayashirazie/collecta/blob/main/lib/ui/screens/admin_homepage.dart"
click node_donation_service "https://github.com/hodayashirazie/collecta/blob/main/lib/services/donation_service.dart"
click node_route_service "https://github.com/hodayashirazie/collecta/blob/main/lib/services/route_optimization_service.dart"
click node_admin_service "https://github.com/hodayashirazie/collecta/blob/main/lib/services/admin_service.dart"
click node_donation_api "https://github.com/hodayashirazie/collecta/tree/main/functions/donations"
click node_donation_report "https://github.com/hodayashirazie/collecta/blob/main/functions/donations/reportDonation.js"
click node_zone_api "https://github.com/hodayashirazie/collecta/tree/main/functions/activityZones"
click node_driver_profiles "https://github.com/hodayashirazie/collecta/tree/main/functions/drivers"
click node_route_api "https://github.com/hodayashirazie/collecta/tree/main/functions/routes"
click node_user_api "https://github.com/hodayashirazie/collecta/tree/main/functions/users"
click node_uid_resolver "https://github.com/hodayashirazie/collecta/blob/main/functions/utils/resolveUid.js"
click node_function_registry "https://github.com/hodayashirazie/collecta/blob/main/functions/index.js"

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_donor_ui,node_driver_ui,node_admin_ui,node_donation_service,node_route_service,node_admin_service toneBlue
class node_donation_api,node_donation_report,node_zone_api,node_driver_profiles,node_route_api toneAmber
class node_user_api,node_uid_resolver,node_function_registry toneMint
class node_firestore,node_firebase_auth,node_google_maps,node_route_optimizer toneRose
class node_donor,node_driver,node_admin toneIndigo
```

## Components

### Flutter clients

- [Donor screens](https://github.com/hodayashirazie/collecta/blob/main/lib/ui/screens/report_donation.dart): `lib/ui/screens/report_donation.dart`
- [Driver screens](https://github.com/hodayashirazie/collecta/blob/main/lib/ui/screens/daily_route_driver.dart): `lib/ui/screens/daily_route_driver.dart`
- [Admin screens](https://github.com/hodayashirazie/collecta/blob/main/lib/ui/screens/admin_homepage.dart): `lib/ui/screens/admin_homepage.dart`
- [Donation service](https://github.com/hodayashirazie/collecta/blob/main/lib/services/donation_service.dart): `lib/services/donation_service.dart`
- [Route optimization](https://github.com/hodayashirazie/collecta/blob/main/lib/services/route_optimization_service.dart): `lib/services/route_optimization_service.dart`
- [Admin service](https://github.com/hodayashirazie/collecta/blob/main/lib/services/admin_service.dart): `lib/services/admin_service.dart`

### Donation operations

- [Donation endpoints](https://github.com/hodayashirazie/collecta/tree/main/functions/donations): `functions/donations`
- [Report donation](https://github.com/hodayashirazie/collecta/blob/main/functions/donations/reportDonation.js): `functions/donations/reportDonation.js`
- [Activity zones](https://github.com/hodayashirazie/collecta/tree/main/functions/activityZones): `functions/activityZones`
- [Driver profiles](https://github.com/hodayashirazie/collecta/tree/main/functions/drivers): `functions/drivers`
- [Route endpoints](https://github.com/hodayashirazie/collecta/tree/main/functions/routes): `functions/routes`

### Identity and profiles

- [User roles](https://github.com/hodayashirazie/collecta/tree/main/functions/users): `functions/users`
- [Identity resolver](https://github.com/hodayashirazie/collecta/blob/main/functions/utils/resolveUid.js): `functions/utils/resolveUid.js`
- [Function registry](https://github.com/hodayashirazie/collecta/blob/main/functions/index.js): `functions/index.js`

### Firebase and integrations

- **Cloud Firestore**
- **Firebase Auth**
- **Google Maps APIs**
- **Route optimizer**

### Other components

- **Donor**
- **Driver**
- **Admin**

## Connections

- Donor → Donor screens: reports donations
- Donor screens → Donation service: submits details
- Donation service → Donation endpoints: calls endpoints
- Report donation → Cloud Firestore: writes donation (evidence: `functions/donations/reportDonation.js`)
- Report donation → Cloud Firestore: checks zone coverage (evidence: `functions/donations/reportDonation.js`)
- Report donation → Cloud Firestore: assigns driver stop (evidence: `functions/donations/reportDonation.js`)
- Driver → Driver screens: views route
- Driver screens → Route optimization: requests optimization
- Route optimization → Route endpoints: calls route function
- Route endpoints → Google Maps APIs: builds traffic matrix (evidence: `functions/routes/computeRoutes.js`)
- Route endpoints → Route optimizer: posts route inputs (evidence: `functions/routes/computeRoutes.js`)
- Driver → Driver screens: confirms pickups
- Driver screens → Donation service: submits pickup
- Admin → Admin screens: oversees operations
- Admin screens → Admin service: manages records
- Admin service → Donation endpoints: queries donations
- Admin service → Driver profiles: manages drivers
- Admin service → Activity zones: manages zones
- Admin service → User roles: verifies admin
- Function registry → Report donation: registers endpoint (evidence: `functions/index.js`)
- Function registry → Route endpoints: registers endpoints (evidence: `functions/index.js`)
- Function registry → Activity zones: registers endpoints (evidence: `functions/index.js`)
- Function registry → User roles: registers endpoints (evidence: `functions/index.js`)
- Driver profiles → Identity resolver: resolves identity (evidence: `functions/drivers/updateDriverProfile.js`)
- Identity resolver → Firebase Auth: verifies token (evidence: `functions/utils/resolveUid.js`)
- User roles → Cloud Firestore: stores role data (evidence: `functions/users/syncUserWithRole.js`)
- Activity zones → Cloud Firestore: reads zone data (evidence: `functions/activityZones/getActivityZones.js`)
