# farhan-labib-afk/roadeo-web-app architecture

> Architecture diagram of the GitHub repository farhan-labib-afk/roadeo-web-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/farhan-labib-afk/roadeo-web-app
- Repository: https://github.com/farhan-labib-afk/roadeo-web-app

## Overview

Roadeo is a peer-to-peer car-rental marketplace. Renters search inventory using trip and cargo filters, inspect a car, and request a booking; owners manage listings and booking approvals, then both parties can message and review. Admins handle moderation and account controls. The frontend routes role-based workspaces and calls backend API capabilities; backend services use PostgreSQL. Cargo interpretation can use optional LLM configuration, and student verification/email are additional backend capabilities. Edges between unsampled route handlers and services are omitted or marked unverified; subsystem coverage follows the tree and README rather than implying every implementation call was inspected.

Main entry points: [`roadeo/backend/src/routes`](https://github.com/farhan-labib-afk/roadeo-web-app/tree/main/roadeo/backend/src/routes) (Marketplace routes), [`roadeo/backend/src/config/database.ts`](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/config/database.ts) (Database client), [`roadeo/frontend/src/app/App.tsx`](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/App.tsx) (Web application), [`roadeo/frontend/src/app/pages/CarSearch.tsx`](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/pages/CarSearch.tsx) (Search and car details)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend experience"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_role_routes["Role workspaces<br/>[routes.tsx]"]
  node_search_details["Search and car details<br/>[CarSearch.tsx]"]
  node_cargo_ui["Cargo assistant"]
  node_frontend_services["API client services"]
  node_auth_ui["Authentication state<br/>[AuthContext.tsx]"]
end

subgraph group_api["Backend API"]
  node_backend_app["HTTP application<br/>[app.ts]"]
  node_auth_routes["Authentication routes<br/>[auth.ts]"]
  node_market_routes["Marketplace routes"]
end

subgraph group_domain["Marketplace services"]
  node_auth_service["Identity and access<br/>[auth.service.ts]"]
  node_inventory_service["Inventory and listings"]
  node_car_service["Car management<br/>[car.service.ts]"]
  node_cargo_service["Cargo fit and estimates"]
  node_booking_service["Booking lifecycle<br/>[booking.service.ts]"]
  node_message_service["In-app messaging<br/>[message.service.ts]"]
  node_review_service["Ratings and reviews<br/>[review.service.ts]"]
  node_admin_service["Trust and moderation<br/>[admin.service.ts]"]
  node_student_service["Student verification<br/>[student.service.ts]"]
end

subgraph group_data["Persistence and integrations"]
  node_db_client["Database client<br/>[database.ts]"]
  node_schema["Marketplace schema<br/>[schema.ts]"]
  node_postgres[("PostgreSQL")]
end

node_actors(("Renter, owner, admin"))
node_llm(("LLM provider"))

node_actors -->|"use"| node_webapp
node_webapp -->|"renders"| node_role_routes
node_role_routes -->|"routes to"| node_search_details
node_search_details -->|"offers cargo filters"| node_cargo_ui
node_search_details -->|"uses"| node_frontend_services
node_webapp -->|"provides auth state"| node_auth_ui
node_frontend_services -->|"calls API"| node_backend_app
node_backend_app -->|"mounts"| node_auth_routes
node_backend_app -->|"mounts"| node_market_routes
node_auth_routes -->|"uses"| node_auth_service
node_market_routes -.->|"dispatches to"| node_inventory_service
node_market_routes -.->|"dispatches to"| node_car_service
node_market_routes -.->|"dispatches to"| node_booking_service
node_market_routes -.->|"dispatches to"| node_message_service
node_market_routes -->|"dispatches to"| node_review_service
node_market_routes -.->|"dispatches to"| node_admin_service
node_market_routes -.->|"dispatches to"| node_student_service
node_inventory_service -->|"uses cargo fit"| node_cargo_service
node_car_service -->|"uses cargo fit"| node_cargo_service
node_auth_service -->|"queries"| node_db_client
node_inventory_service -->|"queries"| node_db_client
node_car_service -->|"queries"| node_db_client
node_booking_service -.->|"queries"| node_db_client
node_message_service -.->|"queries"| node_db_client
node_review_service -->|"queries"| node_db_client
node_admin_service -->|"queries"| node_db_client
node_db_client -->|"connects"| node_postgres
node_llm -.->|"interprets needs"| node_cargo_service

click node_webapp "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/App.tsx"
click node_role_routes "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/routes.tsx"
click node_search_details "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/pages/CarSearch.tsx"
click node_cargo_ui "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/components/CargoAssistantField.tsx"
click node_frontend_services "https://github.com/farhan-labib-afk/roadeo-web-app/tree/main/roadeo/frontend/src/app/services"
click node_auth_ui "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/context/AuthContext.tsx"
click node_backend_app "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/app.ts"
click node_auth_routes "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/routes/auth.ts"
click node_market_routes "https://github.com/farhan-labib-afk/roadeo-web-app/tree/main/roadeo/backend/src/routes"
click node_auth_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/auth.service.ts"
click node_inventory_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/inventory.service.ts"
click node_car_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/car.service.ts"
click node_cargo_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/cargoFit.service.ts"
click node_booking_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/booking.service.ts"
click node_message_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/message.service.ts"
click node_review_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/review.service.ts"
click node_admin_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/admin.service.ts"
click node_student_service "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/student.service.ts"
click node_db_client "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/config/database.ts"
click node_schema "https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/db/schema.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_webapp,node_role_routes,node_search_details,node_cargo_ui,node_frontend_services,node_auth_ui toneBlue
class node_backend_app,node_auth_routes,node_market_routes toneAmber
class node_auth_service,node_inventory_service,node_car_service,node_cargo_service,node_booking_service,node_message_service,node_review_service,node_admin_service,node_student_service toneMint
class node_db_client,node_schema,node_postgres toneRose
class node_actors,node_llm toneIndigo
```

## Components

### Frontend experience

- [Web application](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/App.tsx): `roadeo/frontend/src/app/App.tsx`
- [Role workspaces](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/routes.tsx): `roadeo/frontend/src/app/routes.tsx`
- [Search and car details](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/pages/CarSearch.tsx): `roadeo/frontend/src/app/pages/CarSearch.tsx`
- [Cargo assistant](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/components/CargoAssistantField.tsx): `roadeo/frontend/src/app/components/CargoAssistantField.tsx`
- [API client services](https://github.com/farhan-labib-afk/roadeo-web-app/tree/main/roadeo/frontend/src/app/services): `roadeo/frontend/src/app/services`
- [Authentication state](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/frontend/src/app/context/AuthContext.tsx): `roadeo/frontend/src/app/context/AuthContext.tsx`

### Backend API

- [HTTP application](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/app.ts): `roadeo/backend/src/app.ts`
- [Authentication routes](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/routes/auth.ts): `roadeo/backend/src/routes/auth.ts`
- [Marketplace routes](https://github.com/farhan-labib-afk/roadeo-web-app/tree/main/roadeo/backend/src/routes): `roadeo/backend/src/routes`

### Marketplace services

- [Identity and access](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/auth.service.ts): `roadeo/backend/src/services/auth.service.ts`
- [Inventory and listings](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/inventory.service.ts): `roadeo/backend/src/services/inventory.service.ts`
- [Car management](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/car.service.ts): `roadeo/backend/src/services/car.service.ts`
- [Cargo fit and estimates](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/cargoFit.service.ts): `roadeo/backend/src/services/cargoFit.service.ts`
- [Booking lifecycle](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/booking.service.ts): `roadeo/backend/src/services/booking.service.ts`
- [In-app messaging](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/message.service.ts): `roadeo/backend/src/services/message.service.ts`
- [Ratings and reviews](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/review.service.ts): `roadeo/backend/src/services/review.service.ts`
- [Trust and moderation](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/admin.service.ts): `roadeo/backend/src/services/admin.service.ts`
- [Student verification](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/services/student.service.ts): `roadeo/backend/src/services/student.service.ts`

### Persistence and integrations

- [Database client](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/config/database.ts): `roadeo/backend/src/config/database.ts`
- [Marketplace schema](https://github.com/farhan-labib-afk/roadeo-web-app/blob/main/roadeo/backend/src/db/schema.ts): `roadeo/backend/src/db/schema.ts`
- **PostgreSQL**

### Other components

- **Renter, owner, admin**
- **LLM provider**

## Connections

- Renter, owner, admin → Web application: use (evidence: `README.md`)
- Web application → Role workspaces: renders (evidence: `roadeo/frontend/src/app/App.tsx`)
- Role workspaces → Search and car details: routes to (evidence: `roadeo/frontend/src/app/routes.tsx`)
- Search and car details → Cargo assistant: offers cargo filters (evidence: `roadeo/frontend/src/app/pages/CarSearch.tsx`)
- Search and car details → API client services: uses (evidence: `roadeo/frontend/src/app/pages/CarSearch.tsx`)
- Web application → Authentication state: provides auth state (evidence: `roadeo/frontend/src/app/App.tsx`)
- API client services → HTTP application: calls API (evidence: `README.md`)
- HTTP application → Authentication routes: mounts (evidence: `roadeo/backend/src/app.ts`)
- HTTP application → Marketplace routes: mounts (evidence: `roadeo/backend/src/app.ts`)
- Authentication routes → Identity and access: uses (evidence: `roadeo/backend/src/routes/auth.ts`)
- Marketplace routes → Inventory and listings: dispatches to
- Marketplace routes → Car management: dispatches to (evidence: `roadeo/backend/src/routes/cars.ts`)
- Marketplace routes → Booking lifecycle: dispatches to
- Marketplace routes → In-app messaging: dispatches to
- Marketplace routes → Ratings and reviews: dispatches to (evidence: `roadeo/backend/src/routes/reviews.ts`)
- Marketplace routes → Trust and moderation: dispatches to
- Marketplace routes → Student verification: dispatches to
- Inventory and listings → Cargo fit and estimates: uses cargo fit (evidence: `roadeo/backend/src/services/inventory.service.ts`)
- Car management → Cargo fit and estimates: uses cargo fit (evidence: `roadeo/backend/src/services/car.service.ts`)
- Identity and access → Database client: queries (evidence: `roadeo/backend/src/services/auth.service.ts`)
- Inventory and listings → Database client: queries (evidence: `roadeo/backend/src/services/inventory.service.ts`)
- Car management → Database client: queries (evidence: `roadeo/backend/src/services/car.service.ts`)
- Booking lifecycle → Database client: queries
- In-app messaging → Database client: queries
- Ratings and reviews → Database client: queries (evidence: `roadeo/backend/src/services/review.service.ts`)
- Trust and moderation → Database client: queries (evidence: `roadeo/backend/src/services/admin.service.ts`)
- Database client → PostgreSQL: connects (evidence: `roadeo/backend/src/config/database.ts`)
- LLM provider → Cargo fit and estimates: interprets needs