# yo-gerr/vcroad architecture

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

- Interactive diagram: https://gitdiagram.com/yo-gerr/vcroad
- Repository: https://github.com/yo-gerr/vcroad

## Overview

VCRoad is a cross-platform Valenzuela City road-safety app. The main citizen workflow is sign-in, viewing the map dashboard, submitting a guided incident report, and following its status; a parallel advisory workflow lets administrators plot and publish traffic updates for users. The tree shows distinct feature, provider, model, and repository layers, while the README documents capabilities and selected integrations. Source excerpts cover platform launchers rather than Dart runtime code, so feature-to-repository links are documented at a high level; other internal call relationships are not inferred.

Main entry points: [`lib/data/repositories/advisory.dart`](https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/advisory.dart) (Advisory repository), [`lib/presentation/features/reports/screens/report_screen.dart`](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/reports/screens/report_screen.dart) (Report wizard), [`lib/presentation/features/advisories/screens/advisory_screen.dart`](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/advisories/screens/advisory_screen.dart) (Advisory management), [`lib/presentation/app/app_shell.dart`](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/app/app_shell.dart) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app_start["App startup<br/>[main.dart]"]
  node_app_shell["App shell<br/>[app_shell.dart]"]
  node_role_navigation["Role navigation<br/>[role_router.dart]"]
end

subgraph group_citizen["Citizen services"]
  node_authentication["Authentication<br/>[login_screen.dart]"]
  node_home_dashboard["Map dashboard<br/>[home_screen.dart]"]
  node_map_view["Incident map<br/>[map.dart]"]
  node_report_wizard["Report wizard<br/>[report_screen.dart]"]
  node_report_steps["Report steps"]
  node_report_history["Report history<br/>[history.dart]"]
end

subgraph group_advisory["Traffic advisories"]
  node_advisory_management["Advisory management"]
  node_advisory_creation["Advisory wizard"]
  node_route_plotting["Route plotting<br/>[plot.dart]"]
  node_advisory_alerts["Advisory alerts"]
  node_advisory_export["Advisory export"]
end

subgraph group_learning_admin["Learning and administration"]
  node_lessons["Road safety lessons"]
  node_admin_accounts["Account administration"]
  node_profile["User profile"]
end

subgraph group_data["Data and integrations"]
  node_report_data["Report repository<br/>[report.dart]"]
  node_advisory_data["Advisory repository<br/>[advisory.dart]"]
  node_lesson_data["Lesson repository<br/>[lesson.dart]"]
  node_firebase[("Firebase")]
  node_osm["OpenStreetMap"]
  node_osrm["OSRM"]
  node_supabase[("Supabase media")]
end

node_citizen_user(("Citizen"))
node_admin_user(("Administrator"))

node_citizen_user -->|"signs in"| node_authentication
node_authentication -.->|"enters app"| node_home_dashboard
node_home_dashboard -->|"shows incidents"| node_map_view
node_citizen_user -->|"reports incident"| node_report_wizard
node_report_wizard -->|"guides through"| node_report_steps
node_report_wizard -.->|"submits report"| node_report_data
node_report_history -.->|"tracks status"| node_report_data
node_admin_user -->|"manages advisories"| node_advisory_management
node_advisory_management -->|"creates advisory"| node_advisory_creation
node_advisory_creation -->|"plots route"| node_route_plotting
node_route_plotting -->|"snaps roads"| node_osrm
node_advisory_management -.->|"publishes updates"| node_advisory_data
node_advisory_data -->|"streams updates"| node_firebase
node_advisory_alerts -->|"alerts on additions"| node_advisory_data
node_advisory_export -->|"renders map tiles"| node_osm
node_advisory_data -->|"removes advisory photo"| node_supabase
node_citizen_user -->|"learns safety"| node_lessons
node_admin_user -->|"manages accounts"| node_admin_accounts
node_lessons -.->|"loads lessons"| node_lesson_data
node_app_start -.->|"starts"| node_app_shell
node_app_shell -.->|"routes by role"| node_role_navigation

click node_app_start "https://github.com/yo-gerr/vcroad/blob/main/lib/main.dart"
click node_app_shell "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/app/app_shell.dart"
click node_role_navigation "https://github.com/yo-gerr/vcroad/blob/main/lib/core/utils/routing/role_router.dart"
click node_authentication "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/auth/screens/login_screen.dart"
click node_home_dashboard "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/home/screens/home_screen.dart"
click node_map_view "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/home/widgets/map.dart"
click node_report_wizard "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/reports/screens/report_screen.dart"
click node_report_steps "https://github.com/yo-gerr/vcroad/tree/main/lib/presentation/features/reports/widgets/steps"
click node_report_history "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/reports/widgets/history.dart"
click node_advisory_management "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/advisories/screens/advisory_screen.dart"
click node_advisory_creation "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/advisories/widgets/create_advisory.dart"
click node_route_plotting "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/advisories/widgets/steps/plot.dart"
click node_advisory_alerts "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/shared/dialogs/advisory_alert.dart"
click node_advisory_export "https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/advisory_export.dart"
click node_lessons "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/lesson/screens/lesson_browser_screen.dart"
click node_admin_accounts "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/admin/screens/account_screen.dart"
click node_profile "https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/profile/screens/profile_screen.dart"
click node_report_data "https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/report.dart"
click node_advisory_data "https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/advisory.dart"
click node_lesson_data "https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/lesson.dart"

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_start,node_app_shell,node_role_navigation toneBlue
class node_authentication,node_home_dashboard,node_map_view,node_report_wizard,node_report_steps,node_report_history toneAmber
class node_advisory_management,node_advisory_creation,node_route_plotting,node_advisory_alerts,node_advisory_export toneMint
class node_lessons,node_admin_accounts,node_profile toneRose
class node_report_data,node_advisory_data,node_lesson_data,node_firebase,node_osm,node_osrm,node_supabase,node_citizen_user,node_admin_user toneIndigo
```

## Components

### App shell

- [App startup](https://github.com/yo-gerr/vcroad/blob/main/lib/main.dart): `lib/main.dart`
- [App shell](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/app/app_shell.dart): `lib/presentation/app/app_shell.dart`
- [Role navigation](https://github.com/yo-gerr/vcroad/blob/main/lib/core/utils/routing/role_router.dart): `lib/core/utils/routing/role_router.dart`

### Citizen services

- [Authentication](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/auth/screens/login_screen.dart): `lib/presentation/features/auth/screens/login_screen.dart`
- [Map dashboard](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/home/screens/home_screen.dart): `lib/presentation/features/home/screens/home_screen.dart`
- [Incident map](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/home/widgets/map.dart): `lib/presentation/features/home/widgets/map.dart`
- [Report wizard](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/reports/screens/report_screen.dart): `lib/presentation/features/reports/screens/report_screen.dart`
- [Report steps](https://github.com/yo-gerr/vcroad/tree/main/lib/presentation/features/reports/widgets/steps): `lib/presentation/features/reports/widgets/steps`
- [Report history](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/reports/widgets/history.dart): `lib/presentation/features/reports/widgets/history.dart`

### Traffic advisories

- [Advisory management](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/advisories/screens/advisory_screen.dart): `lib/presentation/features/advisories/screens/advisory_screen.dart`
- [Advisory wizard](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/advisories/widgets/create_advisory.dart): `lib/presentation/features/advisories/widgets/create_advisory.dart`
- [Route plotting](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/advisories/widgets/steps/plot.dart): `lib/presentation/features/advisories/widgets/steps/plot.dart`
- [Advisory alerts](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/shared/dialogs/advisory_alert.dart): `lib/presentation/shared/dialogs/advisory_alert.dart`
- [Advisory export](https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/advisory_export.dart): `lib/data/repositories/advisory_export.dart`

### Learning and administration

- [Road safety lessons](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/lesson/screens/lesson_browser_screen.dart): `lib/presentation/features/lesson/screens/lesson_browser_screen.dart`
- [Account administration](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/admin/screens/account_screen.dart): `lib/presentation/features/admin/screens/account_screen.dart`
- [User profile](https://github.com/yo-gerr/vcroad/blob/main/lib/presentation/features/profile/screens/profile_screen.dart): `lib/presentation/features/profile/screens/profile_screen.dart`

### Data and integrations

- [Report repository](https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/report.dart): `lib/data/repositories/report.dart`
- [Advisory repository](https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/advisory.dart): `lib/data/repositories/advisory.dart`
- [Lesson repository](https://github.com/yo-gerr/vcroad/blob/main/lib/data/repositories/lesson.dart): `lib/data/repositories/lesson.dart`
- **Firebase**
- **OpenStreetMap**
- **OSRM**
- **Supabase media**

### Other components

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

## Connections

- Citizen → Authentication: signs in (evidence: `README.md`)
- Authentication → Map dashboard: enters app
- Map dashboard → Incident map: shows incidents (evidence: `README.md`)
- Citizen → Report wizard: reports incident (evidence: `README.md`)
- Report wizard → Report steps: guides through (evidence: `README.md`)
- Report wizard → Report repository: submits report
- Report history → Report repository: tracks status
- Administrator → Advisory management: manages advisories (evidence: `README.md`)
- Advisory management → Advisory wizard: creates advisory (evidence: `README.md`)
- Advisory wizard → Route plotting: plots route (evidence: `README.md`)
- Route plotting → OSRM: snaps roads (evidence: `README.md`)
- Advisory management → Advisory repository: publishes updates
- Advisory repository → Firebase: streams updates (evidence: `README.md`)
- Advisory alerts → Advisory repository: alerts on additions (evidence: `README.md`)
- Advisory export → OpenStreetMap: renders map tiles (evidence: `README.md`)
- Advisory repository → Supabase media: removes advisory photo (evidence: `README.md`)
- Citizen → Road safety lessons: learns safety (evidence: `README.md`)
- Administrator → Account administration: manages accounts (evidence: `README.md`)
- Road safety lessons → Lesson repository: loads lessons
- App startup → App shell: starts
- App shell → Role navigation: routes by role
