# shifat-arman/ride-share-nestjs architecture

> Architecture diagram of the GitHub repository shifat-arman/ride-share-nestjs, 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/shifat-arman/ride-share-nestjs
- Repository: https://github.com/shifat-arman/ride-share-nestjs

## Overview

This NestJS backend serves a ride-sharing API for riders, drivers, and administrators. The principal workflow runs from rider ride estimation and booking through driver discovery/acceptance, trip progress, and completion; location updates support driver discovery. Authentication issues and rotates access/refresh sessions. The graph also preserves account management, vehicles, ratings, public FAQ/testimonials, and admin announcements. Controller-to-service calls are grounded in sampled controllers; database and external routing/geocoding integrations are represented at the subsystem level where implementation excerpts were not available.

Main entry points: [`src/auth/auth.service.ts`](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/auth.service.ts) (Auth service), [`src/entities/driver/driver.controller.ts`](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/driver/driver.controller.ts) (Driver API), [`src/entities/ride/ride.service.ts`](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/ride/ride.service.ts) (Ride service), [`src/entities/location/location.service.ts`](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/location/location.service.ts) (Location service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_auth_api["Auth API<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_token_service["Token pairs"]
  node_refresh_store["Refresh token store"]
end

subgraph group_ride["Ride operations"]
  node_ride_api["Ride API<br/>[ride.controller.ts]"]
  node_ride_service["Ride service<br/>[ride.service.ts]"]
  node_location_api["Location API"]
  node_location_service["Location service"]
end

subgraph group_accounts["Accounts and fleet"]
  node_rider_api["Rider API"]
  node_rider_service["Rider service<br/>[rider.service.ts]"]
  node_driver_api["Driver API"]
  node_driver_service["Driver service<br/>[driver.service.ts]"]
  node_vehicle_service["Vehicle service<br/>[vehicle.service.ts]"]
  node_rating_service["Rating service<br/>[rating.service.ts]"]
end

subgraph group_content["Admin and public content"]
  node_admin_api["Admin API"]
  node_admin_service["Admin service<br/>[admin.service.ts]"]
  node_faq_api["FAQ API<br/>[faq.controller.ts]"]
  node_faq_service["FAQ service<br/>[faq.service.ts]"]
  node_testimonial_api["Testimonial API"]
  node_testimonial_service["Testimonial service"]
end

subgraph group_shared["Shared services"]
  node_profile_picture["Profile pictures"]
  node_storage["Object storage"]
end

node_rider(("Rider"))
node_driver(("Driver"))
node_admin(("Admin"))
node_postgres[("PostgreSQL")]
node_object_store[("Neon object storage")]
node_routing["Route provider"]
node_geocoding["Geocoding provider"]

node_rider -->|"register or sign in"| node_auth_api
node_auth_api -->|"handles auth"| node_auth_service
node_auth_service -->|"issues or rotates"| node_token_service
node_token_service -->|"stores tokens"| node_refresh_store
node_refresh_store -->|"reads and writes"| node_postgres
node_auth_service -->|"manages rider profile"| node_rider_service
node_auth_service -->|"applies driver role"| node_driver_service
node_auth_service -->|"registers admin"| node_admin_service
node_rider -->|"estimates and books"| node_ride_api
node_driver -->|"accepts and progresses"| node_ride_api
node_ride_api -->|"dispatches ride actions"| node_ride_service
node_ride_service -->|"persists ride state"| node_postgres
node_ride_service -.->|"requests route estimate"| node_routing
node_driver -->|"sends GPS updates"| node_location_api
node_location_api -->|"dispatches location actions"| node_location_service
node_location_service -->|"stores driver locations"| node_postgres
node_location_service -.->|"searches places"| node_geocoding
node_admin -->|"manages riders"| node_rider_api
node_rider -->|"manages own profile"| node_rider_api
node_rider_api -->|"dispatches profile actions"| node_rider_service
node_admin -->|"manages drivers"| node_driver_api
node_driver -->|"manages own profile"| node_driver_api
node_driver_api -->|"dispatches driver actions"| node_driver_service
node_driver_api -->|"creates vehicle"| node_vehicle_service
node_driver_api -->|"retrieves ratings"| node_rating_service
node_admin -->|"manages admins and announcements"| node_admin_api
node_admin_api -->|"dispatches admin actions"| node_admin_service
node_rider -->|"views FAQs"| node_faq_api
node_faq_api -->|"dispatches content actions"| node_faq_service
node_rider -->|"views testimonials"| node_testimonial_api
node_testimonial_api -->|"dispatches content actions"| node_testimonial_service
node_admin_api -->|"uploads profile image"| node_profile_picture
node_profile_picture -->|"stores image"| node_storage
node_storage -->|"uploads or deletes objects"| node_object_store

click node_auth_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/auth.service.ts"
click node_token_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/token-pair.service.ts"
click node_refresh_store "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/typeorm-refresh-token.store.ts"
click node_ride_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/ride/ride.controller.ts"
click node_ride_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/ride/ride.service.ts"
click node_location_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/location/location.controller.ts"
click node_location_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/location/location.service.ts"
click node_rider_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/rider/rider.controller.ts"
click node_rider_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/rider/rider.service.ts"
click node_driver_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/driver/driver.controller.ts"
click node_driver_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/driver/driver.service.ts"
click node_vehicle_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/vehicle/vehicle.service.ts"
click node_rating_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/rating/rating.service.ts"
click node_admin_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/admin/admin.controller.ts"
click node_admin_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/admin/admin.service.ts"
click node_faq_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/faq/faq.controller.ts"
click node_faq_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/faq/faq.service.ts"
click node_testimonial_api "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/testimonial/testimonial.controller.ts"
click node_testimonial_service "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/testimonial/testimonial.service.ts"
click node_profile_picture "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/common/profile-picture/profile-picture.service.ts"
click node_storage "https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/common/storage/neon-storage.service.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_auth_api,node_auth_service,node_token_service,node_refresh_store toneBlue
class node_ride_api,node_ride_service,node_location_api,node_location_service,node_postgres,node_object_store toneAmber
class node_rider_api,node_rider_service,node_driver_api,node_driver_service,node_vehicle_service,node_rating_service,node_routing toneMint
class node_admin_api,node_admin_service,node_faq_api,node_faq_service,node_testimonial_api,node_testimonial_service toneRose
class node_profile_picture,node_storage,node_rider,node_driver,node_admin,node_geocoding toneIndigo
```

## Components

### API and sessions

- [Auth API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/auth.controller.ts): `src/auth/auth.controller.ts`
- [Auth service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [Token pairs](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/token-pair.service.ts): `src/auth/token-pair.service.ts`
- [Refresh token store](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/auth/typeorm-refresh-token.store.ts): `src/auth/typeorm-refresh-token.store.ts`

### Ride operations

- [Ride API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/ride/ride.controller.ts): `src/entities/ride/ride.controller.ts`
- [Ride service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/ride/ride.service.ts): `src/entities/ride/ride.service.ts`
- [Location API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/location/location.controller.ts): `src/entities/location/location.controller.ts`
- [Location service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/location/location.service.ts): `src/entities/location/location.service.ts`

### Accounts and fleet

- [Rider API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/rider/rider.controller.ts): `src/entities/rider/rider.controller.ts`
- [Rider service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/rider/rider.service.ts): `src/entities/rider/rider.service.ts`
- [Driver API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/driver/driver.controller.ts): `src/entities/driver/driver.controller.ts`
- [Driver service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/driver/driver.service.ts): `src/entities/driver/driver.service.ts`
- [Vehicle service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/vehicle/vehicle.service.ts): `src/entities/vehicle/vehicle.service.ts`
- [Rating service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/rating/rating.service.ts): `src/entities/rating/rating.service.ts`

### Admin and public content

- [Admin API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/admin/admin.controller.ts): `src/entities/admin/admin.controller.ts`
- [Admin service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/admin/admin.service.ts): `src/entities/admin/admin.service.ts`
- [FAQ API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/faq/faq.controller.ts): `src/entities/faq/faq.controller.ts`
- [FAQ service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/faq/faq.service.ts): `src/entities/faq/faq.service.ts`
- [Testimonial API](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/testimonial/testimonial.controller.ts): `src/entities/testimonial/testimonial.controller.ts`
- [Testimonial service](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/testimonial/testimonial.service.ts): `src/entities/testimonial/testimonial.service.ts`

### Shared services

- [Profile pictures](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/common/profile-picture/profile-picture.service.ts): `src/entities/common/profile-picture/profile-picture.service.ts`
- [Object storage](https://github.com/shifat-arman/ride-share-nestjs/blob/main/src/entities/common/storage/neon-storage.service.ts): `src/entities/common/storage/neon-storage.service.ts`

### Other components

- **Rider**
- **Driver**
- **Admin**
- **PostgreSQL**
- **Neon object storage**
- **Route provider**
- **Geocoding provider**

## Connections

- Rider → Auth API: register or sign in
- Auth API → Auth service: handles auth
- Auth service → Token pairs: issues or rotates
- Token pairs → Refresh token store: stores tokens
- Refresh token store → PostgreSQL: reads and writes
- Auth service → Rider service: manages rider profile
- Auth service → Driver service: applies driver role
- Auth service → Admin service: registers admin
- Rider → Ride API: estimates and books
- Driver → Ride API: accepts and progresses
- Ride API → Ride service: dispatches ride actions
- Ride service → PostgreSQL: persists ride state
- Ride service → Route provider: requests route estimate
- Driver → Location API: sends GPS updates
- Location API → Location service: dispatches location actions
- Location service → PostgreSQL: stores driver locations
- Location service → Geocoding provider: searches places
- Admin → Rider API: manages riders
- Rider → Rider API: manages own profile
- Rider API → Rider service: dispatches profile actions
- Admin → Driver API: manages drivers
- Driver → Driver API: manages own profile
- Driver API → Driver service: dispatches driver actions
- Driver API → Vehicle service: creates vehicle
- Driver API → Rating service: retrieves ratings
- Admin → Admin API: manages admins and announcements
- Admin API → Admin service: dispatches admin actions
- Rider → FAQ API: views FAQs
- FAQ API → FAQ service: dispatches content actions
- Rider → Testimonial API: views testimonials
- Testimonial API → Testimonial service: dispatches content actions
- Admin API → Profile pictures: uploads profile image
- Profile pictures → Object storage: stores image
- Object storage → Neon object storage: uploads or deletes objects