# Transporter Management API - Complete Mermaid Flow

## 1. Authentication Flow

```mermaid
flowchart TD
    Start([User]) --> Choice{Action?}
    Choice -->|Register| Register[POST /auth/register]
    Choice -->|Login| Login[POST /auth/login]
    Choice -->|Social| Social[POST /auth/social-login]
    Choice -->|OTP Login| SendOTP[POST /auth/send-otp]
    
    Register --> Tokens1[Access + Refresh Tokens]
    Login --> Tokens2[Access + Refresh Tokens]
    
    SendOTP --> VerifyOTP[POST /auth/verify-otp]
    VerifyOTP --> UserVerified[User Verified]
    
    Tokens1 --> AuthFlow{Token Expired?}
    Tokens2 --> AuthFlow
    AuthFlow -->|Yes| Refresh[POST /auth/refresh-token]
    AuthFlow -->|No| Protected[Access Protected APIs]
    Refresh --> NewTokens[New Tokens]
    NewTokens --> Protected
    
    Choice -->|Logout| Logout[POST /auth/logout]
    Logout --> Invalidated[Token Invalidated]
    
    Choice -->|Change Password| ChangePass[POST /auth/change-password]
    ChangePass --> Updated[Password Updated]
```

## 2. Ride Booking Flow (Passenger → Driver → Complete)

```mermaid
flowchart TD
    subgraph Passenger["Passenger Flow"]
        P1[Get Categories<br>GET /rides/categories]
        P2[Estimate Fare<br>POST /rides/estimate]
        P3[Book Ride<br>POST /rides/book]
        P4[View Bids<br>GET /rides/id/bids]
        P5[Accept Bid<br>POST /rides/id/bids/bid_id/accept]
        P6[Track Ride<br>WebSocket /ws/ride/id]
        P7[Cancel Ride<br>POST /rides/id/cancel]
    end
    
    subgraph Driver["Driver Flow"]
        D1[Update Location<br>PUT /driver/location]
        D2[Go Online<br>PUT /driver/status]
        D3[Get Nearby Rides<br>GET /driver/rides/nearby]
        D4[Submit Bid<br>POST /driver/rides/id/bid]
        D5[Update Ride Status<br>PUT /rides/id/status]
    end
    
    subgraph RideStates["Ride Status States"]
        RS1[REQUESTED]
        RS2[BIDDING]
        RS3[ACCEPTED]
        RS4[DRIVER_ARRIVED]
        RS5[STARTED]
        RS6[COMPLETED]
        RSC[CANCELLED]
    end
    
    P1 --> P2 --> P3
    P3 --> RS1
    RS1 --> RS2
    D2 --> D3
    D3 --> D4
    D4 --> P4
    P4 --> P5
    P5 --> RS3
    RS3 --> D5
    D5 --> RS4 --> RS5 --> RS6
    P7 --> RSC
    P6 -.->|Real-time| RS4
```

## 3. End-to-End Ride Lifecycle

```mermaid
stateDiagram-v2
    [*] --> REQUESTED: Passenger books ride
    REQUESTED --> SEARCHING: System searches
    SEARCHING --> BIDDING: Drivers receive request
    BIDDING --> ACCEPTED: Passenger accepts bid
    BIDDING --> EXPIRED: No acceptance
    BIDDING --> CANCELLED: Cancel
    ACCEPTED --> DRIVER_ARRIVED: Driver at pickup
    ACCEPTED --> CANCELLED: Cancel
    DRIVER_ARRIVED --> STARTED: Ride begins
    STARTED --> COMPLETED: Arrive at destination
    COMPLETED --> [*]: Payment processed
    CANCELLED --> [*]
    EXPIRED --> [*]
    REQUESTED --> NO_DRIVERS: No nearby drivers
    NO_DRIVERS --> [*]
```

## 4. Payment & Wallet Flow

```mermaid
flowchart TD
    subgraph PassengerPayments["Passenger Payments"]
        W1[Get Wallet<br>GET /payments/wallet]
        W2[Top Up<br>POST /payments/wallet/topup]
        W3[View Transactions<br>GET /payments/transactions]
        W4[Ride Payment<br>Auto-deduct on completion]
    end
    
    subgraph DriverPayments["Driver Payments"]
        E1[Get Earnings<br>GET /driver/earnings]
        E2[Request Withdrawal<br>POST /payments/withdraw]
        E3[Withdrawal History<br>GET /payments/withdrawals]
    end
    
    W1 --> W2
    W2 --> W3
    W4 --> W3
    
    E1 --> E2
    E2 --> E3
```

## 5. WebSocket Real-Time Flow

```mermaid
flowchart LR
    subgraph RideTracking["/ws/ride/{ride_id}"]
        RT1[Passenger Connect] --> RT2[Receive: driver_location]
        RT3[Driver Connect] --> RT4[Send: location_update]
        RT4 --> RT2
        RT2 --> RT5[Receive: ride_status]
    end
    
    subgraph DriverTracking["/ws/driver/{driver_id}"]
        DT1[Driver Connect] --> DT2[Send: location]
        DT2 --> DT3[Store/Update DB]
    end
    
    subgraph Notifications["/ws/notifications"]
        N1[User Connect] --> N2[New ride request]
        N1 --> N3[Ride status updates]
        N1 --> N4[New bids]
    end
```

## 6. API Architecture Overview

```mermaid
flowchart TB
    subgraph Clients["Clients"]
        App[Mobile App]
        Web[Web Console]
    end
    
    subgraph API["FastAPI Backend"]
        Auth["/api/v1/auth"]
        Passenger["/api/v1/passenger"]
        Driver["/api/v1/driver"]
        Rides["/api/v1/rides"]
        Payments["/api/v1/payments"]
        Admin["/api/v1/admin"]
        Config["/api/v1/config"]
        WS["/ws/*"]
    end
    
    subgraph Services["Services"]
        AuthSvc[AuthService]
        RideSvc[RideService]
        PaymentSvc[PaymentService]
        MapSvc[MapProvider]
    end
    
    subgraph Data["Data"]
        DB[(MySQL)]
        Redis[(Redis Cache)]
    end
    
    App --> Auth
    App --> Passenger
    App --> Driver
    App --> Rides
    App --> Payments
    App --> WS
    Web --> Admin
    
    Auth --> AuthSvc
    Rides --> RideSvc
    Payments --> PaymentSvc
    RideSvc --> MapSvc
    
    AuthSvc --> DB
    RideSvc --> DB
    PaymentSvc --> DB
    MapSvc --> Redis
```

## 7. Complete Request Flow (Sequential)

```mermaid
sequenceDiagram
    participant P as Passenger
    participant API as API
    participant DB as Database
    participant WS as WebSocket
    participant D as Driver
    
    P->>API: POST /auth/login
    API->>DB: Validate user
    API-->>P: JWT Tokens
    
    P->>API: POST /rides/estimate
    API->>API: MapProvider.getDistance
    API-->>P: Fare estimate
    
    P->>API: POST /rides/book
    API->>DB: Create Ride (REQUESTED)
    API-->>P: Ride created
    
    D->>API: PUT /driver/status (online)
    D->>API: PUT /driver/location
    
    D->>API: GET /driver/rides/nearby
    API->>DB: Query rides
    API-->>D: Available rides
    
    D->>API: POST /driver/rides/{id}/bid
    API->>DB: Create FareBid
    API->>WS: notify_new_bid()
    WS-->>P: New bid notification
    
    P->>API: GET /rides/{id}/bids
    API-->>P: Pending bids
    
    P->>API: POST /rides/{id}/bids/{bid_id}/accept
    API->>DB: Assign driver, ACCEPTED
    API->>WS: notify_ride_update()
    WS-->>D: Bid accepted
    
    D->>WS: Connect /ws/ride/{id}
    P->>WS: Connect /ws/ride/{id}
    
    D->>API: PUT /rides/{id}/status (driver_arrived)
    D->>WS: location_update
    WS-->>P: driver_location
    
    D->>API: PUT /rides/{id}/status (started)
    D->>WS: location_update (during ride)
    WS-->>P: driver_location
    
    D->>API: PUT /rides/{id}/status (completed)
    API->>DB: Deduct wallet, credit driver
    API->>WS: ride_status completed
    WS-->>P: Ride completed
```

## 8. Driver Onboarding Flow

```mermaid
flowchart TD
    Start([Driver Registration]) --> Reg[POST /auth/register<br>role=driver]
    Reg --> Login[POST /auth/login]
    Login --> Profile[PUT /auth/profile]
    Profile --> Doc[POST /driver/documents<br>license, vehicle docs]
    Doc --> AdminReview{Admin Approves?}
    AdminReview -->|No| Rejected[Driver PENDING/REJECTED]
    AdminReview -->|Yes| Approved[Driver APPROVED]
    Approved --> Online[PUT /driver/status<br>is_online=true]
    Online --> Bid[Can submit bids]
```

---

**Usage:** Paste any diagram block into [Mermaid Live Editor](https://mermaid.live) or use in GitHub/GitLab Markdown for rendering.