sabbirahmedfahim/campusride

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.