# majd-ba15/otw-backend architecture

> Architecture diagram of the GitHub repository majd-ba15/otw-backend, 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/majd-ba15/otw-backend
- Repository: https://github.com/majd-ba15/otw-backend

## Overview

OTW is a campus ride-sharing API. Riders and drivers authenticate, maintain profiles, publish or find rides, and book or fulfil trips; a separate demand path matches rider requests against driver availability. Trip completion supports ratings, while messaging, location updates, notifications, and administrative review support the ride lifecycle. Controller and service excerpts are partial, so several feature branches are represented by their exact paths and domain names; their internal call wiring is not asserted where source was not sampled.

Main entry points: [`Data/AppDbContext.cs`](https://github.com/majd-ba15/otw-backend/blob/main/Data/AppDbContext.cs) (Application database), [`Controllers/BookingsController.cs`](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/BookingsController.cs) (Bookings), [`Controllers/UsersController.cs`](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/UsersController.cs) (User profiles), [`Controllers/DemandController.cs`](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/DemandController.cs) (Demand matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and profiles"]
  node_auth["Authentication<br/>[AuthController.cs]"]
  node_authsvc["Auth service<br/>[AuthService.cs]"]
  node_users["User profiles<br/>[UsersController.cs]"]
  node_files["File storage<br/>[FileService.cs]"]
end

subgraph group_rides["Ride lifecycle"]
  node_ridesapi["Ride discovery<br/>[RidesController.cs]"]
  node_booking["Bookings"]
  node_demand["Demand matching"]
  node_location["Location updates"]
end

subgraph group_engagement["Trip engagement"]
  node_chat["Messaging"]
  node_chathub["Live chat<br/>[ChatHub.cs]"]
  node_ratings["Ratings"]
  node_notifications["Notifications"]
  node_notifapi["Notification API"]
  node_email["Email delivery<br/>[EmailService.cs]"]
  node_ai["AI assistance"]
  node_aisvc["AI service<br/>[AIService.cs]"]
end

subgraph group_operations["Operations and insights"]
  node_reports["Reports"]
  node_adminapi["Administration<br/>[AdminController.cs]"]
  node_analytics["Demand insights"]
  node_reminder["Ride reminders"]
end

subgraph group_core["API and persistence"]
  node_database[("Application database<br/>[AppDbContext.cs]")]
end

node_rider(("Rider"))
node_driver(("Driver"))
node_admin(("Admin"))
node_mailserver{{"SMTP service"}}

node_rider -->|"register or sign in"| node_auth
node_driver -->|"register or sign in"| node_auth
node_auth -->|"delegates"| node_authsvc
node_authsvc -->|"reads and writes users"| node_database
node_authsvc -->|"sends OTP or reset"| node_email
node_rider -->|"manage profile"| node_users
node_driver -->|"manage profile and car"| node_users
node_users -->|"reads and writes"| node_database
node_users -->|"saves uploads"| node_files
node_rider -->|"find rides"| node_ridesapi
node_driver -->|"publish and manage rides"| node_ridesapi
node_ridesapi -->|"reads and writes rides"| node_database
node_rider -->|"request or manage booking"| node_booking
node_driver -->|"accept or decline"| node_booking
node_booking -->|"reads and writes bookings"| node_database
node_booking -->|"creates notifications"| node_notifications
node_booking -->|"sends booking emails"| node_email
node_rider -->|"request a ride"| node_demand
node_driver -->|"offer availability"| node_demand
node_admin -->|"notify matching drivers"| node_demand
node_demand -->|"reads and writes requests and availability"| node_database
node_admin -->|"view demand insights"| node_analytics
node_analytics -->|"reads demand and supply"| node_database
node_driver -->|"send location"| node_location
node_rider -->|"view trip location"| node_location
node_location -->|"reads and writes location history"| node_database
node_rider -->|"send trip message"| node_chat
node_driver -->|"send trip message"| node_chat
node_chat -->|"reads and writes messages"| node_database
node_rider -->|"connect to live chat"| node_chathub
node_driver -->|"connect to live chat"| node_chathub
node_rider -->|"rate trip"| node_ratings
node_driver -->|"rate trip"| node_ratings
node_ratings -->|"reads and writes ratings"| node_database
node_rider -->|"view notifications"| node_notifapi
node_notifapi -->|"reads notifications"| node_database
node_notifications -->|"writes notifications"| node_database
node_ai -->|"requests assistance"| node_aisvc
node_aisvc -->|"reads and writes chat logs"| node_database
node_admin -->|"manage platform"| node_adminapi
node_adminapi -->|"reads and writes platform records"| node_database
node_rider -->|"submit report"| node_reports
node_driver -->|"submit report"| node_reports
node_reports -->|"reads and writes reports"| node_database
node_reminder -->|"queries upcoming rides"| node_database
node_reminder -->|"sends ride reminders"| node_email
node_email -.->|"sends email"| node_mailserver

click node_auth "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/AuthController.cs"
click node_authsvc "https://github.com/majd-ba15/otw-backend/blob/main/Services/AuthService.cs"
click node_users "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/UsersController.cs"
click node_files "https://github.com/majd-ba15/otw-backend/blob/main/Services/FileService.cs"
click node_ridesapi "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/RidesController.cs"
click node_booking "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/BookingsController.cs"
click node_demand "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/DemandController.cs"
click node_location "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/LocationController.cs"
click node_chat "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/MessagesController.cs"
click node_chathub "https://github.com/majd-ba15/otw-backend/blob/main/Hubs/ChatHub.cs"
click node_ratings "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/RatingsController.cs"
click node_notifications "https://github.com/majd-ba15/otw-backend/blob/main/Services/NotificationService.cs"
click node_notifapi "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/NotificationsController.cs"
click node_email "https://github.com/majd-ba15/otw-backend/blob/main/Services/EmailService.cs"
click node_ai "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/ChatAIController.cs"
click node_aisvc "https://github.com/majd-ba15/otw-backend/blob/main/Services/AIService.cs"
click node_reports "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/ReportsController.cs"
click node_adminapi "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/AdminController.cs"
click node_analytics "https://github.com/majd-ba15/otw-backend/blob/main/Controllers/DemandController.cs"
click node_reminder "https://github.com/majd-ba15/otw-backend/blob/main/Services/RideReminderService.cs"
click node_database "https://github.com/majd-ba15/otw-backend/blob/main/Data/AppDbContext.cs"

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,node_authsvc,node_users,node_files toneBlue
class node_ridesapi,node_booking,node_demand,node_location toneAmber
class node_chat,node_chathub,node_ratings,node_notifications,node_notifapi,node_email,node_ai,node_aisvc toneMint
class node_reports,node_adminapi,node_analytics,node_reminder toneRose
class node_database,node_rider,node_driver,node_admin,node_mailserver toneIndigo
```

## Components

### Identity and profiles

- [Authentication](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/AuthController.cs): `Controllers/AuthController.cs`
- [Auth service](https://github.com/majd-ba15/otw-backend/blob/main/Services/AuthService.cs): `Services/AuthService.cs`
- [User profiles](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/UsersController.cs): `Controllers/UsersController.cs`
- [File storage](https://github.com/majd-ba15/otw-backend/blob/main/Services/FileService.cs): `Services/FileService.cs`

### Ride lifecycle

- [Ride discovery](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/RidesController.cs): `Controllers/RidesController.cs`
- [Bookings](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/BookingsController.cs): `Controllers/BookingsController.cs`
- [Demand matching](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/DemandController.cs): `Controllers/DemandController.cs`
- [Location updates](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/LocationController.cs): `Controllers/LocationController.cs`

### Trip engagement

- [Messaging](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/MessagesController.cs): `Controllers/MessagesController.cs`
- [Live chat](https://github.com/majd-ba15/otw-backend/blob/main/Hubs/ChatHub.cs): `Hubs/ChatHub.cs`
- [Ratings](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/RatingsController.cs): `Controllers/RatingsController.cs`
- [Notifications](https://github.com/majd-ba15/otw-backend/blob/main/Services/NotificationService.cs): `Services/NotificationService.cs`
- [Notification API](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/NotificationsController.cs): `Controllers/NotificationsController.cs`
- [Email delivery](https://github.com/majd-ba15/otw-backend/blob/main/Services/EmailService.cs): `Services/EmailService.cs`
- [AI assistance](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/ChatAIController.cs): `Controllers/ChatAIController.cs`
- [AI service](https://github.com/majd-ba15/otw-backend/blob/main/Services/AIService.cs): `Services/AIService.cs`

### Operations and insights

- [Reports](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/ReportsController.cs): `Controllers/ReportsController.cs`
- [Administration](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/AdminController.cs): `Controllers/AdminController.cs`
- [Demand insights](https://github.com/majd-ba15/otw-backend/blob/main/Controllers/DemandController.cs): `Controllers/DemandController.cs`
- [Ride reminders](https://github.com/majd-ba15/otw-backend/blob/main/Services/RideReminderService.cs): `Services/RideReminderService.cs`

### API and persistence

- [Application database](https://github.com/majd-ba15/otw-backend/blob/main/Data/AppDbContext.cs): `Data/AppDbContext.cs`

### Other components

- **Rider**
- **Driver**
- **Admin**
- **SMTP service**

## Connections

- Rider → Authentication: register or sign in
- Driver → Authentication: register or sign in
- Authentication → Auth service: delegates
- Auth service → Application database: reads and writes users
- Auth service → Email delivery: sends OTP or reset
- Rider → User profiles: manage profile
- Driver → User profiles: manage profile and car
- User profiles → Application database: reads and writes
- User profiles → File storage: saves uploads
- Rider → Ride discovery: find rides
- Driver → Ride discovery: publish and manage rides
- Ride discovery → Application database: reads and writes rides
- Rider → Bookings: request or manage booking
- Driver → Bookings: accept or decline
- Bookings → Application database: reads and writes bookings
- Bookings → Notifications: creates notifications
- Bookings → Email delivery: sends booking emails
- Rider → Demand matching: request a ride
- Driver → Demand matching: offer availability
- Admin → Demand matching: notify matching drivers
- Demand matching → Application database: reads and writes requests and availability
- Admin → Demand insights: view demand insights
- Demand insights → Application database: reads demand and supply
- Driver → Location updates: send location
- Rider → Location updates: view trip location
- Location updates → Application database: reads and writes location history
- Rider → Messaging: send trip message
- Driver → Messaging: send trip message
- Messaging → Application database: reads and writes messages
- Rider → Live chat: connect to live chat
- Driver → Live chat: connect to live chat
- Rider → Ratings: rate trip
- Driver → Ratings: rate trip
- Ratings → Application database: reads and writes ratings
- Rider → Notification API: view notifications
- Notification API → Application database: reads notifications
- Notifications → Application database: writes notifications
- AI assistance → AI service: requests assistance
- AI service → Application database: reads and writes chat logs
- Admin → Administration: manage platform
- Administration → Application database: reads and writes platform records
- Rider → Reports: submit report
- Driver → Reports: submit report
- Reports → Application database: reads and writes reports
- Ride reminders → Application database: queries upcoming rides
- Ride reminders → Email delivery: sends ride reminders
- Email delivery → SMTP service: sends email