# a7med-3li/vamo architecture

> Architecture diagram of the GitHub repository a7med-3li/vamo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/a7med-3li/vamo
- Repository: https://github.com/a7med-3li/vamo

## Overview

Vamo is a ride-sharing platform with passenger, driver, and administrative clients backed by a Spring service. The main ride lifecycle is requesting a ride, matching a driver through event-driven dispatch, accepting and completing it, then tracking related wallet and rating functions. Other major capabilities include account registration and authentication, route/address lookup, configurable fares, corridor subscriptions, notifications, and admin operations. The excerpts establish several service calls and event flows; unsampled controller wiring and some domain integrations are left implicit.

Main entry points: [`backend/src/main/java/com/vamo/ride/service/RideService.java`](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/service/RideService.java) (Ride lifecycle), [`backend/src/main/java/com/vamo/auth/service/AuthService.java`](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/auth/service/AuthService.java) (Authentication), [`backend/src/main/java/com/vamo/subscription/service/SubscriptionService.java`](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/subscription/service/SubscriptionService.java) (Subscriptions), [`backend/src/main/java/com/vamo/admin/controller/AdminController.java`](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/admin/controller/AdminController.java) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_passenger["Passenger web<br/>[App.tsx]"]
  node_adminweb["Admin web<br/>[App.tsx]"]
end

subgraph group_identity["Identity and profiles"]
  node_authapi["Auth API"]
  node_authservice["Authentication<br/>[AuthService.java]"]
  node_userservice["User profiles<br/>[UserService.java]"]
  node_userrepo[("User records")]
  node_driverprofiles[("Driver profiles")]
end

subgraph group_rides["Ride operations"]
  node_rideapi["Ride API"]
  node_rideservice["Ride lifecycle<br/>[RideService.java]"]
  node_riderepo[("Ride records")]
  node_dispatch["Ride dispatch"]
  node_connections["Driver connections"]
  node_pricing["Fare calculation"]
  node_routing["Route lookup"]
  node_addressing["Address search"]
end

subgraph group_services["Passenger services"]
  node_wallet["Driver wallet"]
  node_subscriptions["Subscriptions"]
  node_corridors["Corridors"]
  node_notifications["Notifications"]
  node_payments["Payments"]
  node_ratings["Ride ratings<br/>[RatingService.java]"]
end

subgraph group_operations["Administration"]
  node_adminapi["Admin API"]
  node_adminservice["Admin operations<br/>[AdminService.java]"]
  node_adminstats["Admin reporting"]
end

node_user(("User"))
node_driver(("Driver"))
node_administrator(("Administrator"))

node_user -->|"uses"| node_passenger
node_driver -.->|"uses"| node_passenger
node_administrator -->|"uses"| node_adminweb
node_passenger -->|"registers or logs in"| node_authapi
node_authapi -->|"authenticates"| node_authservice
node_authservice -->|"registers"| node_userservice
node_authservice -->|"loads identity"| node_userrepo
node_authservice -->|"loads driver ID"| node_driverprofiles
node_userservice -->|"reads and writes"| node_userrepo
node_rideapi -->|"handles ride requests"| node_rideservice
node_rideservice -->|"reads and writes rides"| node_riderepo
node_rideservice -->|"publishes ride events"| node_dispatch
node_dispatch -->|"dispatches rides"| node_connections
node_addressing -->|"searches map"| node_routing
node_addressing -.->|"unrelated"| node_adminservice
node_subscriptions -->|"loads corridor"| node_corridors
node_subscriptions -->|"publishes request event"| node_notifications
node_subscriptions -.->|"subscription payment"| node_payments
node_notifications -->|"reads subscription"| node_subscriptions
node_rideservice -.->|"ride payout"| node_wallet
node_rideservice -.->|"ride rating"| node_ratings
node_adminweb -->|"manages operations"| node_adminapi
node_adminapi -->|"handles admin actions"| node_adminservice
node_adminapi -->|"requests reports"| node_adminstats
node_adminstats -->|"reads ride records"| node_riderepo
node_adminstats -->|"reads driver records"| node_driverprofiles

click node_passenger "https://github.com/a7med-3li/vamo/blob/main/app-client/src/App.tsx"
click node_adminweb "https://github.com/a7med-3li/vamo/blob/main/admin-client/src/App.tsx"
click node_authapi "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/auth/controller/AuthController.java"
click node_authservice "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/auth/service/AuthService.java"
click node_userservice "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/user/service/UserService.java"
click node_userrepo "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/user/repository/UserRepository.java"
click node_rideapi "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/controller/RideController.java"
click node_rideservice "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/service/RideService.java"
click node_riderepo "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/repository/RideRepository.java"
click node_dispatch "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/dispatch/service/RideDispatchListener.java"
click node_connections "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/dispatch/service/ConnectionManager.java"
click node_pricing "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/pricing/service/FareCalculationService.java"
click node_routing "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/service/HERERoutingServiceImpl.java"
click node_addressing "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/addressing/service/AddressingService.java"
click node_wallet "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/driver/service/DriverWalletService.java"
click node_subscriptions "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/subscription/service/SubscriptionService.java"
click node_corridors "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/corridor/service/CorridorService.java"
click node_notifications "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/notification/service/SubscriptionNotificationListenerService.java"
click node_payments "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/payment/service/PaymentService.java"
click node_ratings "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/rating/service/RatingService.java"
click node_adminapi "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/admin/controller/AdminController.java"
click node_adminservice "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/admin/service/AdminService.java"
click node_adminstats "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/admin/service/AdminStatsService.java"
click node_driverprofiles "https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/driver/repository/DriverProfileRepository.java"

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_passenger,node_adminweb,node_user toneBlue
class node_authapi,node_authservice,node_userservice,node_userrepo,node_driverprofiles toneAmber
class node_rideapi,node_rideservice,node_riderepo,node_dispatch,node_connections,node_pricing,node_routing,node_addressing toneMint
class node_wallet,node_subscriptions,node_corridors,node_notifications,node_payments,node_ratings toneRose
class node_adminapi,node_adminservice,node_adminstats,node_driver,node_administrator toneIndigo
```

## Components

### User clients

- [Passenger web](https://github.com/a7med-3li/vamo/blob/main/app-client/src/App.tsx): `app-client/src/App.tsx`
- [Admin web](https://github.com/a7med-3li/vamo/blob/main/admin-client/src/App.tsx): `admin-client/src/App.tsx`

### Identity and profiles

- [Auth API](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/auth/controller/AuthController.java): `backend/src/main/java/com/vamo/auth/controller/AuthController.java`
- [Authentication](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/auth/service/AuthService.java): `backend/src/main/java/com/vamo/auth/service/AuthService.java`
- [User profiles](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/user/service/UserService.java): `backend/src/main/java/com/vamo/user/service/UserService.java`
- [User records](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/user/repository/UserRepository.java): `backend/src/main/java/com/vamo/user/repository/UserRepository.java`
- [Driver profiles](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/driver/repository/DriverProfileRepository.java): `backend/src/main/java/com/vamo/driver/repository/DriverProfileRepository.java`

### Ride operations

- [Ride API](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/controller/RideController.java): `backend/src/main/java/com/vamo/ride/controller/RideController.java`
- [Ride lifecycle](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/service/RideService.java): `backend/src/main/java/com/vamo/ride/service/RideService.java`
- [Ride records](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/repository/RideRepository.java): `backend/src/main/java/com/vamo/ride/repository/RideRepository.java`
- [Ride dispatch](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/dispatch/service/RideDispatchListener.java): `backend/src/main/java/com/vamo/dispatch/service/RideDispatchListener.java`
- [Driver connections](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/dispatch/service/ConnectionManager.java): `backend/src/main/java/com/vamo/dispatch/service/ConnectionManager.java`
- [Fare calculation](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/pricing/service/FareCalculationService.java): `backend/src/main/java/com/vamo/pricing/service/FareCalculationService.java`
- [Route lookup](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/ride/service/HERERoutingServiceImpl.java): `backend/src/main/java/com/vamo/ride/service/HERERoutingServiceImpl.java`
- [Address search](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/addressing/service/AddressingService.java): `backend/src/main/java/com/vamo/addressing/service/AddressingService.java`

### Passenger services

- [Driver wallet](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/driver/service/DriverWalletService.java): `backend/src/main/java/com/vamo/driver/service/DriverWalletService.java`
- [Subscriptions](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/subscription/service/SubscriptionService.java): `backend/src/main/java/com/vamo/subscription/service/SubscriptionService.java`
- [Corridors](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/corridor/service/CorridorService.java): `backend/src/main/java/com/vamo/corridor/service/CorridorService.java`
- [Notifications](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/notification/service/SubscriptionNotificationListenerService.java): `backend/src/main/java/com/vamo/notification/service/SubscriptionNotificationListenerService.java`
- [Payments](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/payment/service/PaymentService.java): `backend/src/main/java/com/vamo/payment/service/PaymentService.java`
- [Ride ratings](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/rating/service/RatingService.java): `backend/src/main/java/com/vamo/rating/service/RatingService.java`

### Administration

- [Admin API](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/admin/controller/AdminController.java): `backend/src/main/java/com/vamo/admin/controller/AdminController.java`
- [Admin operations](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/admin/service/AdminService.java): `backend/src/main/java/com/vamo/admin/service/AdminService.java`
- [Admin reporting](https://github.com/a7med-3li/vamo/blob/main/backend/src/main/java/com/vamo/admin/service/AdminStatsService.java): `backend/src/main/java/com/vamo/admin/service/AdminStatsService.java`

### Other components

- **User**
- **Driver**
- **Administrator**

## Connections

- User → Passenger web: uses
- Driver → Passenger web: uses
- Administrator → Admin web: uses
- Passenger web → Auth API: registers or logs in
- Auth API → Authentication: authenticates
- Authentication → User profiles: registers
- Authentication → User records: loads identity
- Authentication → Driver profiles: loads driver ID
- User profiles → User records: reads and writes
- Ride API → Ride lifecycle: handles ride requests
- Ride lifecycle → Ride records: reads and writes rides
- Ride lifecycle → Ride dispatch: publishes ride events
- Ride dispatch → Driver connections: dispatches rides
- Address search → Route lookup: searches map
- Address search → Admin operations: unrelated
- Subscriptions → Corridors: loads corridor
- Subscriptions → Notifications: publishes request event
- Subscriptions → Payments: subscription payment
- Notifications → Subscriptions: reads subscription
- Ride lifecycle → Driver wallet: ride payout
- Ride lifecycle → Ride ratings: ride rating
- Admin web → Admin API: manages operations
- Admin API → Admin operations: handles admin actions
- Admin API → Admin reporting: requests reports
- Admin reporting → Ride records: reads ride records
- Admin reporting → Driver profiles: reads driver records