# madtechsolutions2026/ride-for-you-app architecture

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

- Interactive diagram: https://gitdiagram.com/madtechsolutions2026/ride-for-you-app
- Repository: https://github.com/madtechsolutions2026/ride-for-you-app

## Overview

Ride For You is an EV rental prototype with a wired OTP identity flow and broader rider/admin rental operations. A rider requests and verifies an OTP, receives tokens, then the app loads their profile; the mobile client attaches access tokens and refreshes expired sessions. Admin screens support operational domains through the backend API. Rental, KYC, payments, support, and fleet-related capabilities are present in the repository, though the README explicitly describes much of the rider booking experience as static UI. Backend route and database details beyond cited excerpts are represented only where README or SOURCE INDEX evidence supports them.

Main entry points: [`backend/src/app.ts`](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/app.ts) (API assembly), [`admin/src/App.tsx`](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/App.tsx) (Admin routing), [`mobile/src/api/client.ts`](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/api/client.ts) (API client), [`backend/src/controllers/rental.controller.ts`](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/rental.controller.ts) (Rental operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Rider mobile app"]
  node_mobile_app["App navigation<br/>[App.tsx]"]
  node_otp_screens["OTP screens"]
  node_profile["Profile and session<br/>[ProfileScreen.tsx]"]
  node_mobile_client["API client<br/>[client.ts]"]
  node_token_store["Token storage<br/>[tokenStore.ts]"]
  node_rider_experience["Rental screens<br/>[HomeScreen.tsx]"]
end

subgraph group_admin["Admin console"]
  node_admin_app["Admin routing<br/>[App.tsx]"]
  node_admin_auth["Admin auth<br/>[AuthContext.tsx]"]
  node_admin_client["Admin API client<br/>[client.ts]"]
  node_admin_ops["Operations console<br/>[Overview.tsx]"]
  node_admin_kyc["KYC review<br/>[KycReview.tsx]"]
  node_admin_recovery["Service recovery"]
end

subgraph group_backend["Backend API"]
  node_api_app["API assembly<br/>[app.ts]"]
  node_auth_routes["Auth routes<br/>[auth.routes.ts]"]
  node_auth_controller["OTP and sessions<br/>[auth.controller.ts]"]
  node_auth_middleware["Token guard<br/>[auth.ts]"]
  node_rental_routes["Rental routes<br/>[rental.routes.ts]"]
  node_rental_controller["Rental operations"]
  node_ride_controller["Rides and damage<br/>[ride.controller.ts]"]
  node_kyc_controller["KYC workflow<br/>[kyc.controller.ts]"]
  node_admin_routes["Admin routes<br/>[admin.routes.ts]"]
  node_ops_controller["Fleet recovery<br/>[ops.controller.ts]"]
  node_support_controller["Rider support"]
end

subgraph group_services["Backend services and data"]
  node_wallet_service["Wallet ledger<br/>[wallet.ts]"]
  node_collections_service["Rent collections<br/>[collections.ts]"]
  node_billing_service["Weekly billing<br/>[weeklyBilling.ts]"]
  node_notification_service["Notifications<br/>[notifications.ts]"]
  node_uploads_service["File uploads<br/>[uploads.ts]"]
  node_object_storage["Object storage<br/>[r2.ts]"]
  node_cache["Cache<br/>[cache.ts]"]
  node_database[("Application database<br/>[prisma.ts]")]
end

node_rider(("Rider"))
node_admin_user(("Admin operator"))
node_expo["Expo push service"]

node_rider -->|"enters phone and code"| node_otp_screens
node_otp_screens -->|"requests authentication"| node_mobile_client
node_mobile_app -->|"pings health"| node_mobile_client
node_mobile_app -->|"routes to"| node_otp_screens
node_mobile_app -->|"routes after login"| node_profile
node_mobile_client -->|"reads and refreshes tokens"| node_token_store
node_mobile_client -->|"calls API"| node_api_app
node_profile -->|"loads profile"| node_mobile_client
node_rider -.->|"uses rental features"| node_rider_experience
node_admin_user -->|"uses console"| node_admin_app
node_admin_app -->|"checks identity"| node_admin_auth
node_admin_app -->|"routes to operations"| node_admin_ops
node_admin_app -->|"routes to review"| node_admin_kyc
node_admin_app -->|"routes to recovery"| node_admin_recovery
node_admin_auth -->|"uses API client"| node_admin_client
node_admin_kyc -->|"calls API"| node_admin_client
node_admin_recovery -->|"calls API"| node_admin_client
node_admin_client -.->|"calls API"| node_api_app
node_api_app -->|"mounts routes"| node_auth_routes
node_api_app -->|"mounts routes"| node_rental_routes
node_api_app -->|"mounts routes"| node_admin_routes
node_auth_routes -->|"dispatches requests"| node_auth_controller
node_auth_controller -.->|"reads and writes sessions"| node_database
node_rental_routes -->|"dispatches requests"| node_rental_controller
node_rental_routes -->|"dispatches ride requests"| node_ride_controller
node_admin_routes -->|"routes review calls"| node_kyc_controller
node_admin_routes -->|"routes operations"| node_ops_controller
node_admin_routes -->|"routes ticket calls"| node_support_controller
node_auth_middleware -->|"loads account"| node_database
node_auth_middleware -->|"reads and caches account"| node_cache
node_rental_controller -->|"debits wallet"| node_wallet_service
node_rental_controller -->|"settles dunning"| node_collections_service
node_ops_controller -->|"marks recovery"| node_collections_service
node_ops_controller -->|"sends rider notices"| node_notification_service
node_kyc_controller -->|"stores documents"| node_object_storage
node_kyc_controller -->|"invalidates cache"| node_cache
node_ride_controller -->|"uploads damage photos"| node_uploads_service
node_uploads_service -->|"stores objects"| node_object_storage
node_rental_controller -.->|"sends rider notices"| node_notification_service
node_api_app -->|"starts billing"| node_billing_service
node_notification_service -->|"records notifications"| node_database
node_notification_service -->|"delivers push"| node_expo

click node_mobile_app "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/App.tsx"
click node_otp_screens "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/screens/RequestOtpScreen.tsx"
click node_profile "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/screens/ProfileScreen.tsx"
click node_mobile_client "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/api/client.ts"
click node_token_store "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/api/tokenStore.ts"
click node_rider_experience "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/screens/HomeScreen.tsx"
click node_admin_app "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/App.tsx"
click node_admin_auth "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/context/AuthContext.tsx"
click node_admin_client "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/api/client.ts"
click node_admin_ops "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/pages/Overview.tsx"
click node_admin_kyc "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/pages/KycReview.tsx"
click node_admin_recovery "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/pages/ServiceRecovery.tsx"
click node_api_app "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/app.ts"
click node_auth_routes "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/routes/auth.routes.ts"
click node_auth_controller "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/auth.controller.ts"
click node_auth_middleware "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/middleware/auth.ts"
click node_rental_routes "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/routes/rental.routes.ts"
click node_rental_controller "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/rental.controller.ts"
click node_ride_controller "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/ride.controller.ts"
click node_kyc_controller "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/kyc.controller.ts"
click node_admin_routes "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/routes/admin.routes.ts"
click node_ops_controller "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/ops.controller.ts"
click node_support_controller "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/support.controller.ts"
click node_wallet_service "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/services/wallet.ts"
click node_collections_service "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/services/collections.ts"
click node_billing_service "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/services/weeklyBilling.ts"
click node_notification_service "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/notifications.ts"
click node_uploads_service "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/uploads.ts"
click node_object_storage "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/r2.ts"
click node_cache "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/cache.ts"
click node_database "https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/prisma.ts"

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_mobile_app,node_otp_screens,node_profile,node_mobile_client,node_token_store,node_rider_experience toneBlue
class node_admin_app,node_admin_auth,node_admin_client,node_admin_ops,node_admin_kyc,node_admin_recovery toneAmber
class node_api_app,node_auth_routes,node_auth_controller,node_auth_middleware,node_rental_routes,node_rental_controller,node_ride_controller,node_kyc_controller,node_admin_routes,node_ops_controller,node_support_controller toneMint
class node_wallet_service,node_collections_service,node_billing_service,node_notification_service,node_uploads_service,node_object_storage,node_cache,node_database toneRose
class node_rider,node_admin_user,node_expo toneIndigo
```

## Components

### Rider mobile app

- [App navigation](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/App.tsx): `mobile/App.tsx`
- [OTP screens](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/screens/RequestOtpScreen.tsx): `mobile/src/screens/RequestOtpScreen.tsx`
- [Profile and session](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/screens/ProfileScreen.tsx): `mobile/src/screens/ProfileScreen.tsx`
- [API client](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/api/client.ts): `mobile/src/api/client.ts`
- [Token storage](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/api/tokenStore.ts): `mobile/src/api/tokenStore.ts`
- [Rental screens](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/mobile/src/screens/HomeScreen.tsx): `mobile/src/screens/HomeScreen.tsx`

### Admin console

- [Admin routing](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/App.tsx): `admin/src/App.tsx`
- [Admin auth](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/context/AuthContext.tsx): `admin/src/context/AuthContext.tsx`
- [Admin API client](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/api/client.ts): `admin/src/api/client.ts`
- [Operations console](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/pages/Overview.tsx): `admin/src/pages/Overview.tsx`
- [KYC review](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/pages/KycReview.tsx): `admin/src/pages/KycReview.tsx`
- [Service recovery](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/admin/src/pages/ServiceRecovery.tsx): `admin/src/pages/ServiceRecovery.tsx`

### Backend API

- [API assembly](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Auth routes](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/routes/auth.routes.ts): `backend/src/routes/auth.routes.ts`
- [OTP and sessions](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/auth.controller.ts): `backend/src/controllers/auth.controller.ts`
- [Token guard](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`
- [Rental routes](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/routes/rental.routes.ts): `backend/src/routes/rental.routes.ts`
- [Rental operations](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/rental.controller.ts): `backend/src/controllers/rental.controller.ts`
- [Rides and damage](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/ride.controller.ts): `backend/src/controllers/ride.controller.ts`
- [KYC workflow](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/kyc.controller.ts): `backend/src/controllers/kyc.controller.ts`
- [Admin routes](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/routes/admin.routes.ts): `backend/src/routes/admin.routes.ts`
- [Fleet recovery](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/ops.controller.ts): `backend/src/controllers/ops.controller.ts`
- [Rider support](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/controllers/support.controller.ts): `backend/src/controllers/support.controller.ts`

### Backend services and data

- [Wallet ledger](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/services/wallet.ts): `backend/src/services/wallet.ts`
- [Rent collections](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/services/collections.ts): `backend/src/services/collections.ts`
- [Weekly billing](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/services/weeklyBilling.ts): `backend/src/services/weeklyBilling.ts`
- [Notifications](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/notifications.ts): `backend/src/utils/notifications.ts`
- [File uploads](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/uploads.ts): `backend/src/utils/uploads.ts`
- [Object storage](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/r2.ts): `backend/src/utils/r2.ts`
- [Cache](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/cache.ts): `backend/src/utils/cache.ts`
- [Application database](https://github.com/madtechsolutions2026/ride-for-you-app/blob/main/backend/src/utils/prisma.ts): `backend/src/utils/prisma.ts`

### Other components

- **Rider**
- **Admin operator**
- **Expo push service**

## Connections

- Rider → OTP screens: enters phone and code
- OTP screens → API client: requests authentication
- App navigation → API client: pings health (evidence: `mobile/App.tsx`)
- App navigation → OTP screens: routes to (evidence: `mobile/App.tsx`)
- App navigation → Profile and session: routes after login (evidence: `mobile/App.tsx`)
- API client → Token storage: reads and refreshes tokens (evidence: `mobile/src/api/client.ts`)
- API client → API assembly: calls API
- Profile and session → API client: loads profile (evidence: `mobile/src/screens/ProfileScreen.tsx`)
- Rider → Rental screens: uses rental features
- Admin operator → Admin routing: uses console (evidence: `admin/src/App.tsx`)
- Admin routing → Admin auth: checks identity (evidence: `admin/src/App.tsx`)
- Admin routing → Operations console: routes to operations (evidence: `admin/src/App.tsx`)
- Admin routing → KYC review: routes to review (evidence: `admin/src/App.tsx`)
- Admin routing → Service recovery: routes to recovery (evidence: `admin/src/App.tsx`)
- Admin auth → Admin API client: uses API client (evidence: `admin/src/context/AuthContext.tsx`)
- KYC review → Admin API client: calls API (evidence: `admin/src/pages/KycReview.tsx`)
- Service recovery → Admin API client: calls API (evidence: `admin/src/pages/ServiceRecovery.tsx`)
- Admin API client → API assembly: calls API
- API assembly → Auth routes: mounts routes (evidence: `backend/src/app.ts`)
- API assembly → Rental routes: mounts routes (evidence: `backend/src/app.ts`)
- API assembly → Admin routes: mounts routes (evidence: `backend/src/app.ts`)
- Auth routes → OTP and sessions: dispatches requests
- OTP and sessions → Application database: reads and writes sessions
- Rental routes → Rental operations: dispatches requests (evidence: `backend/src/routes/rental.routes.ts`)
- Rental routes → Rides and damage: dispatches ride requests (evidence: `backend/src/routes/rental.routes.ts`)
- Admin routes → KYC workflow: routes review calls (evidence: `backend/src/routes/admin.routes.ts`)
- Admin routes → Fleet recovery: routes operations (evidence: `backend/src/routes/admin.routes.ts`)
- Admin routes → Rider support: routes ticket calls (evidence: `backend/src/routes/admin.routes.ts`)
- Token guard → Application database: loads account (evidence: `backend/src/middleware/auth.ts`)
- Token guard → Cache: reads and caches account (evidence: `backend/src/middleware/auth.ts`)
- Rental operations → Wallet ledger: debits wallet (evidence: `backend/src/controllers/rental.controller.ts`)
- Rental operations → Rent collections: settles dunning (evidence: `backend/src/controllers/rental.controller.ts`)
- Fleet recovery → Rent collections: marks recovery (evidence: `backend/src/controllers/ops.controller.ts`)
- Fleet recovery → Notifications: sends rider notices (evidence: `backend/src/controllers/ops.controller.ts`)
- KYC workflow → Object storage: stores documents (evidence: `backend/src/controllers/kyc.controller.ts`)
- KYC workflow → Cache: invalidates cache (evidence: `backend/src/controllers/kyc.controller.ts`)
- Rides and damage → File uploads: uploads damage photos (evidence: `backend/src/controllers/ride.controller.ts`)
- File uploads → Object storage: stores objects (evidence: `backend/src/utils/uploads.ts`)
- Rental operations → Notifications: sends rider notices (evidence: `backend/src/controllers/rental.controller.ts`)
- API assembly → Weekly billing: starts billing (evidence: `backend/src/app.ts`)
- Notifications → Application database: records notifications (evidence: `backend/src/utils/notifications.ts`)
- Notifications → Expo push service: delivers push (evidence: `backend/src/utils/notifications.ts`)
