# sabbirahmedfahim/campusride architecture

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

- Interactive diagram: https://gitdiagram.com/sabbirahmedfahim/campusride
- Repository: https://github.com/sabbirahmedfahim/campusride

## Overview

1. **Overall shape**
   CampusRide is a Flutter client application with a Supabase-backed backend. The repo is mostly the cross-platform app (`lib/`) plus generated platform hosts for Android, iOS, web, macOS, Linux, and Windows. In practice, the architecture is centered on the Flutter client talking directly to Supabase services.

2. **Client presentation layer**
   The UI is organized in `lib/pages/` as screen-level routes: authentication, dashboard, ride offer/request flows, ride detail/history, leaderboard, chat inbox/chat room, notifications, profile, and a separate admin shell with admin screens. `home_shell.dart` and `admin_shell.dart` define the two main navigation containers, with the user-facing app using persistent bottom tabs.

3. **State management boundary**
   `lib/providers/` contains the app’s runtime state layer, using Provider to coordinate auth, rides, chat, notifications, leaderboard/admin state, and refresh logic. Screens read from providers; providers in turn call the API layer and subscribe to real-time updates. This is the main boundary between UI and backend access.

4. **Backend/API access layer**
   `lib/api/` is the repository’s service boundary. It groups all Supabase operations by domain: auth, rides, chat, notifications, leaderboard, and admin. This separation reflects the backend data model and keeps screen code from calling Supabase directly.

5. **Data model layer**
   `lib/entities/` defines the app’s core domain objects: users, rides, ride requests, conversations, chat messages, and notifications. These models sit between the API responses and UI widgets, and they make the repository’s domain boundaries explicit for diagramming.

6. **Supabase as the system backend**
   The backend is not a custom server; it is Supabase Postgres plus Supabase Auth and Realtime. `lib/config/supabase_config.dart` holds the client configuration. The README indicates that the database also contains triggers, row-level security, scheduled jobs, and leaderboard logic, so a lot of business behavior lives in Postgres rather than in Dart.

7. **Authentication and access control flow**
   Users register and log in through Supabase Auth, with university-email restriction enforced both client-side and in the database. The app supports email/password plus OTP verification on signup. After sign-in, the auth provider determines whether the user is banned or is an admin and routes them either into the main shell or the admin shell.

8. **Ride and request workflow**
   Ride offers and ride requests are created from dedicated screens, stored in Supabase, and rendered in the dashboard and history views. The ride provider manages lifecycle actions such as posting, booking, canceling, and refreshing lists. The README shows that ride state transitions and cooldown/expiry behavior are driven by database rules and cron jobs, not just client logic.

9. **Real-time collaboration features**
   Ride feeds, request summaries, notifications, and chat all update through Supabase Realtime subscriptions. The app therefore has a push-like data flow: database changes trigger updates, which providers receive and fan out into screen refreshes. This is the key mechanism behind the “live” dashboard, inboxes, and chat.

10. **Chat and notification subsystems**
   Chat is a separate domain with conversation and message entities, an inbox screen, and a one-to-one chat screen. Notifications have their own inbox and unread-count behavior. Both are event-driven features backed by database records and synced to the client via realtime updates.

11. **Leaderboard and scoring**
   The leaderboard is a read-optimized view of users ranked by score. The app has a dedicated leaderboard screen and row widget, while the actual score changes are triggered by ride lifecycle events in the database. This keeps scoring logic on the backend and presentation logic on the client.

12. **Admin boundary**
   Admin functionality is isolated in its own shell and screens for dashboard metrics, user management, rides, and requests. Access is gated by `is_admin`, and the README notes that admin policies are enforced in Supabase/Postgres as well as in the UI. This is a separate trust boundary from the standard student workflow.

13. **Supporting UI components and assets**
   `lib/widgets/` contains reusable visual components such as ride cards, request cards, leaderboard rows, conversation tiles, and map thumbnails. `assets/` provides branding and app icons, while the `docs/` folder contains the project documentation and database setup material. These are supportive, not core runtime subsystems.

14. **External services and device capabilities**
   The app depends on device GPS via `geolocator` for pickup location capture, and it uses Google Maps only as a read-only external preview/open action rather than embedding a full map workflow. The architecture intentionally avoids manual map pinning and relies on the device location as an input constraint.

Main entry points: [`lib/pages`](https://github.com/sabbirahmedfahim/campusride/tree/main/lib/pages) (Screens), [`lib/config/supabase_config.dart`](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/config/supabase_config.dart) (Supabase config), [`lib/entities`](https://github.com/sabbirahmedfahim/campusride/tree/main/lib/entities) (Domain models), [`lib/main.dart`](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/main.dart) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App entry"]
  node_main(("Main<br/>entrypoint<br/>[main.dart]"))
end

subgraph group_client["Client layers"]
  node_home_shell["Home shell<br/>navigation shell<br/>[home_shell.dart]"]
  node_admin_shell["Admin shell<br/>navigation shell<br/>[admin_shell.dart]"]
  node_auth_provider["Auth state<br/>provider<br/>[auth_provider.dart]"]
  node_ride_provider["Ride state<br/>provider<br/>[ride_provider.dart]"]
  node_chat_provider["Chat state<br/>provider<br/>[chat_provider.dart]"]
  node_notification_provider["Notification state<br/>provider"]
  node_admin_provider["Admin state<br/>provider"]
  node_entities["Domain models"]
  node_screens["Screens<br/>presentation"]
  node_widgets["Shared widgets<br/>ui components"]
end

subgraph group_backend["Supabase backend"]
  node_auth_api["Auth API<br/>supabase service<br/>[auth_api.dart]"]
  node_ride_api["Ride API<br/>supabase service<br/>[ride_api.dart]"]
  node_chat_api["Chat API<br/>supabase service<br/>[chat_api.dart]"]
  node_notification_api["Notification API<br/>supabase service"]
  node_leaderboard_api["Leaderboard API<br/>supabase service"]
  node_admin_api["Admin API<br/>supabase service<br/>[admin_api.dart]"]
  node_supabase_config["Supabase config"]
end

subgraph group_platform["Platform hosts"]
  node_native_hosts["Native hosts<br/>platform shells"]
end

node_main -->|"initializes"| node_supabase_config
node_main -->|"wires"| node_auth_provider
node_main -->|"opens"| node_home_shell
node_main -->|"opens"| node_admin_shell
node_auth_provider -->|"calls"| node_auth_api
node_auth_provider -->|"routes to"| node_home_shell
node_auth_provider -->|"routes to"| node_admin_shell
node_ride_provider -->|"calls"| node_ride_api
node_chat_provider -->|"calls"| node_chat_api
node_notification_provider -->|"calls"| node_notification_api
node_admin_provider -->|"calls"| node_admin_api
node_screens -->|"contains"| node_home_shell
node_screens -->|"contains"| node_admin_shell
node_screens -->|"reads"| node_auth_provider
node_screens -->|"reads"| node_ride_provider
node_screens -->|"reads"| node_chat_provider
node_screens -->|"reads"| node_notification_provider
node_screens -->|"reads"| node_admin_provider
node_ride_api -->|"maps to"| node_entities
node_chat_api -->|"maps to"| node_entities
node_notification_api -->|"maps to"| node_entities
node_leaderboard_api -->|"maps to"| node_entities
node_admin_api -->|"maps to"| node_entities
node_widgets -->|"renders"| node_entities
node_widgets -->|"used by"| node_screens
node_supabase_config -->|"backs"| node_ride_api
node_supabase_config -->|"backs"| node_chat_api
node_supabase_config -->|"backs"| node_notification_api
node_supabase_config -->|"backs"| node_leaderboard_api
node_supabase_config -->|"backs"| node_admin_api
node_native_hosts -->|"launches"| node_main

click node_main "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/main.dart"
click node_home_shell "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/pages/home_shell.dart"
click node_admin_shell "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/pages/admin_shell.dart"
click node_auth_provider "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/auth_provider.dart"
click node_ride_provider "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/ride_provider.dart"
click node_chat_provider "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/chat_provider.dart"
click node_notification_provider "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/notification_provider.dart"
click node_admin_provider "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/admin_provider.dart"
click node_auth_api "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/auth_api.dart"
click node_ride_api "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/ride_api.dart"
click node_chat_api "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/chat_api.dart"
click node_notification_api "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/notification_api.dart"
click node_leaderboard_api "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/leaderboard_api.dart"
click node_admin_api "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/admin_api.dart"
click node_supabase_config "https://github.com/sabbirahmedfahim/campusride/blob/main/lib/config/supabase_config.dart"
click node_entities "https://github.com/sabbirahmedfahim/campusride/tree/main/lib/entities"
click node_screens "https://github.com/sabbirahmedfahim/campusride/tree/main/lib/pages"
click node_widgets "https://github.com/sabbirahmedfahim/campusride/tree/main/lib/widgets"

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_main toneBlue
class node_home_shell,node_admin_shell,node_auth_provider,node_ride_provider,node_chat_provider,node_notification_provider,node_admin_provider,node_entities,node_screens,node_widgets toneAmber
class node_auth_api,node_ride_api,node_chat_api,node_notification_api,node_leaderboard_api,node_admin_api,node_supabase_config toneMint
class node_native_hosts toneRose
```

## Components

### App entry

Flutter entrypoint and navigation roots.

- [Main](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/main.dart): entrypoint · Bootstraps Flutter and wires app services. · `lib/main.dart`

### Client layers

UI, state, domain models, and reusable widgets.

- [Home shell](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/pages/home_shell.dart): navigation shell · Primary user navigation container with tabs. · `lib/pages/home_shell.dart`
- [Admin shell](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/pages/admin_shell.dart): navigation shell · Separate navigation container for admin workflows. · `lib/pages/admin_shell.dart`
- [Auth state](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/auth_provider.dart): provider · Tracks sign-in, role, and access routing. · `lib/providers/auth_provider.dart`
- [Ride state](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/ride_provider.dart): provider · Coordinates ride posting, booking, refresh, and lifecycle updates. · `lib/providers/ride_provider.dart`
- [Chat state](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/chat_provider.dart): provider · Manages conversations, messages, and chat refresh. · `lib/providers/chat_provider.dart`
- [Notification state](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/notification_provider.dart): provider · Handles notification inbox and unread counts. · `lib/providers/notification_provider.dart`
- [Admin state](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/providers/admin_provider.dart): provider · Supports admin metrics and moderation workflows. · `lib/providers/admin_provider.dart`
- [Domain models](https://github.com/sabbirahmedfahim/campusride/tree/main/lib/entities): models · Users, rides, requests, conversations, messages, and notifications. · `lib/entities`
- [Screens](https://github.com/sabbirahmedfahim/campusride/tree/main/lib/pages): presentation · Auth, dashboard, ride, chat, notification, profile, and admin screens. · `lib/pages`
- [Shared widgets](https://github.com/sabbirahmedfahim/campusride/tree/main/lib/widgets): ui components · Reusable cards, rows, tiles, and map thumbnail UI. · `lib/widgets`

### Supabase backend

Supabase configuration and server-side data boundaries.

- [Auth API](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/auth_api.dart): supabase service · Supabase auth operations and access checks. · `lib/api/auth_api.dart`
- [Ride API](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/ride_api.dart): supabase service · Ride and ride-request data access. · `lib/api/ride_api.dart`
- [Chat API](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/chat_api.dart): supabase service · Conversation and message persistence. · `lib/api/chat_api.dart`
- [Notification API](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/notification_api.dart): supabase service · Notification persistence and read-state updates. · `lib/api/notification_api.dart`
- [Leaderboard API](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/leaderboard_api.dart): supabase service · Score and ranking reads used by the leaderboard view. · `lib/api/leaderboard_api.dart`
- [Admin API](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/api/admin_api.dart): supabase service · Admin-facing user, ride, and request operations. · `lib/api/admin_api.dart`
- [Supabase config](https://github.com/sabbirahmedfahim/campusride/blob/main/lib/config/supabase_config.dart): config · Client initialization and backend connection settings. · `lib/config/supabase_config.dart`

### Platform hosts

Generated native and desktop/web wrappers.

- **Native hosts**: platform shells · Android, iOS, macOS, Linux, Windows, and web launchers.

## Connections

- Main → Supabase config: initializes · App startup depends on Supabase client setup.
- Main → Auth state: wires · Root app provides auth state for routing.
- Main → Home shell: opens · Authenticated users enter the main shell.
- Main → Admin shell: opens · Admin users can be routed to the admin shell.
- Auth state → Auth API: calls · Auth state delegates sign-in and role checks.
- Auth state → Home shell: routes to · Controls entry into the student experience.
- Auth state → Admin shell: routes to · Controls entry into the admin experience.
- Ride state → Ride API: calls · Ride state reads and mutates ride data.
- Chat state → Chat API: calls · Chat state fetches and syncs conversations.
- Notification state → Notification API: calls · Notification state loads and updates inbox items.
- Admin state → Admin API: calls · Admin state drives moderation and reporting actions.
- Screens → Home shell: contains · User-facing screens are hosted by the main shell.
- Screens → Admin shell: contains · Admin screens are hosted by the admin shell.
- Screens → Auth state: reads · Screens consume auth state for routing and gating.
- Screens → Ride state: reads · Ride screens react to ride state.
- Screens → Chat state: reads · Chat screens react to conversation state.
- Screens → Notification state: reads · Notification screens react to inbox state.
- Screens → Admin state: reads · Admin screens consume admin state.
- Ride API → Domain models: maps to · Ride responses are shaped into domain models.
- Chat API → Domain models: maps to · Conversation and message data use shared models.
- Notification API → Domain models: maps to · Notification data uses shared models.
- Leaderboard API → Domain models: maps to · Leaderboard reads are projected from user and ride models.
- Admin API → Domain models: maps to · Admin operations work over the core domain objects.
- Shared widgets → Domain models: renders · Shared UI components present core domain data.
- Shared widgets → Screens: used by · Screens compose reusable visual pieces.
- Supabase config → Ride API: backs · All domain APIs rely on the configured Supabase client.
- Supabase config → Chat API: backs · Chat access is powered by the same backend client.
- Supabase config → Notification API: backs · Notification access is powered by the same backend client.
- Supabase config → Leaderboard API: backs · Leaderboard access is powered by the same backend client.
- Supabase config → Admin API: backs · Admin access is powered by the same backend client.
- Native hosts → Main: launches · Platform wrappers start the Flutter app.