# albotech405/albotaxi_v1 architecture

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

- Interactive diagram: https://gitdiagram.com/albotech405/albotaxi_v1
- Repository: https://github.com/albotech405/albotaxi_v1

## Overview

##### Project type and purpose
- This is a full‐stack, cross-platform ride-sharing mobile application built in Flutter.
- It supports two user roles (Customer & Driver), integrates with Supabase (Postgres, auth, realtime, storage), Firebase Cloud Messaging, Google Maps, Twilio (OTP), and uses Provider for state management.

##### File structure
- Top‐level “android/”, “ios/”, “web/”, “linux/”, “macos/”, “windows/” directories contain platform runners.
- “lib/” holds application code:
- main.dart (entry point)
- screens/ (UI pages grouped by feature & role)
- providers/ (state management)
- services/ (all API-calling business logic)
- models/, widgets/, utils/, constants/, config
- “supabase/” holds serverless functions and SQL migrations.
- CI/CD pipelines in “.github/workflows” and “.roocode”.

##### README for additional insights
- Confirms tech stack: Flutter 3.9+, Supabase backend, FCM, Google Maps, Provider.
- Mentions serverless “send_push_notification” function for welcome messages.
- Defines core features and ongoing “welcome notification” architecture.

##### Main components
a. Mobile App (Flutter layer)
- UI Screens (Auth, Customer, Driver, Emergency, Home, Payment)
- State Management (Provider)
- Service Layer (Dart services: auth, ride matching, payments, notifications, location, etc.)
- Config/env (.env via flutter_dotenv)
b. External Services
- Supabase
- Auth (phone + OTP)
- PostgreSQL DB (user, trip, notification tables)
- Realtime (WebSocket) for live location & trip updates
- Storage (documents & photos)
- Serverless Functions (TypeScript: send_push_notification)
- Firebase Cloud Messaging (push notifications)
- Google Maps API (maps, directions)
- Twilio (OTP SMS relay)
c. CI/CD
- GitHub Actions / RooCode pipelines for building & deploying to Android, iOS, Web, Desktop

##### Relationships & data flows
- User interacts with Flutter UI → triggers Provider state change → invokes Service method
- Service makes REST/gotrue calls to Supabase Auth / Database / Storage
- Service subscribes to Supabase Realtime channel for trip & driver location updates
- Service requests Google Maps Directions API for routing
- On new user signup, Supabase function triggers FCM via Firebase Admin SDK → FCM pushes to device
- Twilio OTP service invoked by AuthService for phone verification
- CI/CD pipelines pull code → run flutter build for each platform

##### Architectural patterns & design principles
- Layered architecture: UI → State (Provider) → Services → External APIs
- Single Responsibility: each service file encapsulates one domain concern
- Dependency Injection via Provider
- Separation of concerns between platform runners and shared Dart code
- Real-time event-driven updates via WebSockets

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Flutter Client Layer
    subgraph "Flutter Client" 
        style FlutterClient fill:#cfe2f3,stroke:#0366d6,stroke-width:2px
        Main["main.dart"] 
        Screens["UI Screens"] 
    end
    subgraph "UI Screens Details"
        AuthScreens["Auth Flows"] 
        CustomerScreens["Customer Views"] 
        DriverScreens["Driver Views"] 
        HomeScreens["Home & Navigation"] 
        PaymentScreens["Payment Flow"] 
        RiderScreens["Rider-Specific Flow"] 
        EmergencyScreens["Emergency Module"] 
        DebugScreens["Debug Pages"] 
    end

    %% Provider State Layer
    subgraph "Provider State" 
        style Provider fill:#d0e7ff,stroke:#1f78b4,stroke-width:2px
        StateMgmt["Provider (lib/providers/)"] 
    end

    %% Services Layer
    subgraph "Services Layer"
        style Services fill:#fff3cd,stroke:#d39e00,stroke-width:2px
        AuthService["AuthService (Dart)"] 
        RideMatchingService["RideMatchingService"] 
        TripService["TripService"] 
        LiveLocationService["LiveLocationService"] 
        DriverLocationService["DriverLocationService"] 
        NotificationService["NotificationService"] 
        FirebaseMessagingService["FirebaseMessagingService"] 
        PaymentService["PaymentService"] 
        WalletService["WalletService"] 
        DirectionsService["DirectionsService"] 
        ETAService["ETAService"] 
        TwilioService["TwilioService"] 
    end

    %% External Systems Layer
    subgraph "External Systems"
        style External fill:#d4edda,stroke:#28a745,stroke-width:2px
        GoogleMaps["Google Maps API"] 
        TwilioExt["Twilio (OTP SMS)"] 
        FCM["Firebase Cloud Messaging"] 
    end

    %% Supabase Backend Layer
    subgraph "Supabase Backend"
        style Supabase fill:#f8d7da,stroke:#d73a49,stroke-width:2px
        AuthSupabase["Auth (Phone+OTP)"] 
        Realtime["Realtime (WebSocket)"] 
        Storage["Storage (Files)"] 
        Functions["send_push_notification (Function)"] 
        DB["Postgres DB"] 
        Migrations["DB Migrations"] 
    end

    %% CI/CD Layer
    CI["CI/CD Pipelines"] 
    style CI fill:#e2e3e5,stroke:#6c757d,stroke-width:2px

    %% Connections
    Main -->|"initializes"| StateMgmt
    StateMgmt -->|"calls"| AuthService
    StateMgmt -->|"calls"| RideMatchingService
    StateMgmt -->|"calls"| TripService
    StateMgmt -->|"calls"| LiveLocationService
    StateMgmt -->|"calls"| DriverLocationService
    StateMgmt -->|"calls"| NotificationService
    StateMgmt -->|"calls"| FirebaseMessagingService
    StateMgmt -->|"calls"| PaymentService
    StateMgmt -->|"calls"| WalletService
    StateMgmt -->|"calls"| DirectionsService
    StateMgmt -->|"calls"| ETAService
    StateMgmt -->|"calls"| TwilioService

    AuthService -->|"REST/Gotrue"| AuthSupabase
    RideMatchingService -->|"REST"| Functions
    TripService -->|"REST"| DB
    LiveLocationService -->|"WebSocket"| Realtime
    DriverLocationService -->|"WebSocket"| Realtime
    DirectionsService -->|"REST"| GoogleMaps
    ETAService -->|"REST"| GoogleMaps
    NotificationService -->|"REST"| FCM
    FirebaseMessagingService -->|"FCM SDK"| FCM
    TwilioService -->|"REST"| TwilioExt
    Storage -->|"Storage SDK"| Storage

    Functions -->|"writes to"| DB
    Functions -->|"push via"| FCM
    Migrations --> DB

    CI -->|"builds/deploys"| Main

    %% UI screens hierarchy
    Screens --> AuthScreens
    Screens --> CustomerScreens
    Screens --> DriverScreens
    Screens --> HomeScreens
    Screens --> PaymentScreens
    Screens --> RiderScreens
    Screens --> EmergencyScreens
    Screens --> DebugScreens

    %% Click Events
    click Main "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/main.dart"
    click Screens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/"
    click AuthScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/auth/"
    click CustomerScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/customer/"
    click DriverScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/driver/"
    click HomeScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/home/"
    click PaymentScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/payment/"
    click RiderScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/rider/"
    click EmergencyScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/emergency/"
    click DebugScreens "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/screens/debug/"
    click StateMgmt "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/lib/providers/"
    click AuthService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/auth_service.dart"
    click RideMatchingService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/ride_matching_service.dart"
    click TripService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/trip_service.dart"
    click LiveLocationService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/live_location_service.dart"
    click DriverLocationService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/driver_location_service.dart"
    click NotificationService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/notification_service.dart"
    click FirebaseMessagingService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/firebase_messaging_service.dart"
    click PaymentService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/payment_service.dart"
    click WalletService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/wallet_service.dart"
    click DirectionsService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/directions_service.dart"
    click ETAService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/services/eta_service.dart"
    click TwilioService "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/lib/twilio/twilio_service.dart"
    click Functions "https://github.com/albotech405/albotaxi_v1/blob/AlboTaxi_V1/supabase/functions/send_push_notification/index.ts"
    click Migrations "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/supabase/migrations/"
    click CI "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/.github/workflows/"
    click CI "https://github.com/albotech405/albotaxi_v1/tree/AlboTaxi_V1/.roocode/"

    %% Styles
    classDef flutter fill:#cfe2f3,stroke:#0366d6
    classDef provider fill:#d0e7ff,stroke:#1f78b4
    classDef service fill:#fff3cd,stroke:#d39e00
    classDef external fill:#d4edda,stroke:#28a745
    classDef supabase fill:#f8d7da,stroke:#d73a49
    classDef cicd fill:#e2e3e5,stroke:#6c757d

    class Main,Screens flutter
    class StateMgmt provider
    class AuthService,RideMatchingService,TripService,LiveLocationService,DriverLocationService,NotificationService,FirebaseMessagingService,PaymentService,WalletService,DirectionsService,ETAService,TwilioService service
    class GoogleMaps,TwilioExt,FCM external
    class AuthSupabase,Realtime,Storage,Functions,DB,Migrations supabase
    class CI cicd
```
