# cs455-carpooling/campus_ridepooling_automation architecture

> Architecture diagram of the GitHub repository cs455-carpooling/campus_ridepooling_automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cs455-carpooling/campus_ridepooling_automation
- Repository: https://github.com/cs455-carpooling/campus_ridepooling_automation

## Overview

Campus Ride-Pooling is a Next.js application for IIT Kanpur students to offer rides, request seats, coordinate trips, split fares, and manage post-trip feedback and safety reports. The main journey runs from account/profile setup through ride creation and matching, owner approval, trip coordination, and settlement tracking; payment itself stays external. Operations staff administer configuration, incidents, complaints, and enforcement. AI offers recommendations and chatbot assistance, with advisory complaint analysis. README-level workflow statements support the broad domain links; source excerpts specifically show chatbot request dispatch and realtime server wiring, while unsampled modules are represented at their exact tree paths.

Main entry points: [`apps/web/src/app/api/rides`](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/api/rides) (Ride APIs), [`apps/web/src/app/api/chatbot/route.ts`](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/app/api/chatbot/route.ts) (Chatbot endpoint), [`apps/web/src/app`](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app) (Account and profile UI), [`apps/web/src/lib/trip.ts`](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/trip.ts) (Trip coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_accounts["Accounts and access"]
  node_account_ui["Account and profile UI"]
  node_auth_api["Account APIs"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_profile["Profiles<br/>[profile-data.ts]"]
end

subgraph group_rides["Ride pooling"]
  node_ride_ui["Ride workflows"]
  node_ride_api["Ride APIs"]
  node_ride_search["Ride search<br/>[ride-search.ts]"]
  node_ride_options["Ride options<br/>[ride-options.ts]"]
  node_requests["Seat requests<br/>[join-requests.ts]"]
end

subgraph group_trip["Trip and safety"]
  node_trip_ops["Trip coordination<br/>[trip.ts]"]
  node_settlement["Fare settlement"]
  node_reports["Ratings and complaints<br/>[complaints.ts]"]
  node_realtime["Live coordination<br/>[server.mjs]"]
end

subgraph group_assistance["AI assistance"]
  node_recommendations["Ride recommendations"]
  node_chatbot_api["Chatbot endpoint<br/>[route.ts]"]
  node_chatbot["Chatbot assistant<br/>[chatbot.ts]"]
  node_chatbot_model["Gemini interpretation<br/>[chatbot-gemini.ts]"]
  node_chat_audit["Chatbot audit<br/>[chatbot-audit.ts]"]
end

subgraph group_operations["Operations"]
  node_admin_ui["Admin console"]
  node_admin_api["Administration APIs"]
  node_admin_logic["Admin operations<br/>[admin-actions.ts]"]
end

node_student(("Student"))
node_admin(("Administrator"))
node_web["Web application"]
node_socket_io["Socket.IO"]
node_database[("PostgreSQL")]
node_gemini["Gemini API"]

node_student -->|"uses"| node_web
node_admin -->|"uses"| node_web
node_web -->|"routes to"| node_account_ui
node_account_ui -->|"submits credentials"| node_auth_api
node_auth_api -.->|"authenticates"| node_auth
node_auth -.->|"reads and writes"| node_database
node_account_ui -->|"manages profile"| node_profile
node_student -->|"offers or finds"| node_ride_ui
node_ride_ui -->|"submits ride actions"| node_ride_api
node_ride_api -.->|"searches rides"| node_ride_search
node_ride_api -->|"loads options"| node_ride_options
node_ride_api -->|"manages requests"| node_requests
node_requests -->|"returns request state"| node_ride_api
node_ride_api -->|"advances trip"| node_trip_ops
node_trip_ops -->|"records shares"| node_settlement
node_trip_ops -->|"enables feedback"| node_reports
node_student -->|"coordinates live"| node_realtime
node_realtime -->|"hosts"| node_socket_io
node_student -->|"requests suggestions"| node_recommendations
node_recommendations -->|"searches candidates"| node_ride_search
node_student -->|"sends query"| node_chatbot_api
node_chatbot_api -->|"processes message"| node_chatbot
node_chatbot_api -->|"loads options"| node_ride_options
node_chatbot -->|"interprets request"| node_chatbot_model
node_chatbot_model -.->|"calls model"| node_gemini
node_chatbot_api -->|"logs requests"| node_chat_audit
node_admin -->|"reviews operations"| node_admin_ui
node_admin_ui -->|"submits decisions"| node_admin_api
node_admin_api -.->|"applies controls"| node_admin_logic
node_admin_logic -.->|"audits changes"| node_database

click node_web "https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app"
click node_account_ui "https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app"
click node_auth_api "https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/api/auth"
click node_auth "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/auth.ts"
click node_profile "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/profile-data.ts"
click node_ride_ui "https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/(app)/rides"
click node_ride_api "https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/api/rides"
click node_ride_search "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ride-search.ts"
click node_ride_options "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ride-options.ts"
click node_requests "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/join-requests.ts"
click node_trip_ops "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/trip.ts"
click node_settlement "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/payment-settlement.ts"
click node_reports "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/complaints.ts"
click node_realtime "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/server.mjs"
click node_recommendations "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/recommendation-pipeline.ts"
click node_chatbot_api "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/app/api/chatbot/route.ts"
click node_chatbot "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/chatbot.ts"
click node_chatbot_model "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/chatbot-gemini.ts"
click node_chat_audit "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/chatbot-audit.ts"
click node_admin_ui "https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/admin"
click node_admin_api "https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/api/admin"
click node_admin_logic "https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/admin-actions.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_account_ui,node_auth_api,node_auth,node_profile toneBlue
class node_ride_ui,node_ride_api,node_ride_search,node_ride_options,node_requests,node_database toneAmber
class node_trip_ops,node_settlement,node_reports,node_realtime,node_gemini toneMint
class node_recommendations,node_chatbot_api,node_chatbot,node_chatbot_model,node_chat_audit toneRose
class node_admin_ui,node_admin_api,node_admin_logic,node_student,node_admin,node_socket_io toneIndigo
class node_web toneTeal
```

## Components

### Accounts and access

- [Account and profile UI](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app): `apps/web/src/app`
- [Account APIs](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/api/auth): `apps/web/src/app/api/auth`
- [Authentication](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/auth.ts): `apps/web/src/lib/auth.ts`
- [Profiles](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/profile-data.ts): `apps/web/src/lib/profile-data.ts`

### Ride pooling

- [Ride workflows](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/(app)/rides): `apps/web/src/app/(app)/rides`
- [Ride APIs](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/api/rides): `apps/web/src/app/api/rides`
- [Ride search](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ride-search.ts): `apps/web/src/lib/ride-search.ts`
- [Ride options](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ride-options.ts): `apps/web/src/lib/ride-options.ts`
- [Seat requests](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/join-requests.ts): `apps/web/src/lib/join-requests.ts`

### Trip and safety

- [Trip coordination](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/trip.ts): `apps/web/src/lib/trip.ts`
- [Fare settlement](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/payment-settlement.ts): `apps/web/src/lib/payment-settlement.ts`
- [Ratings and complaints](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/complaints.ts): `apps/web/src/lib/complaints.ts`
- [Live coordination](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/server.mjs): `apps/web/server.mjs`

### AI assistance

- [Ride recommendations](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/recommendation-pipeline.ts): `apps/web/src/lib/ai/recommendation-pipeline.ts`
- [Chatbot endpoint](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/app/api/chatbot/route.ts): `apps/web/src/app/api/chatbot/route.ts`
- [Chatbot assistant](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/chatbot.ts): `apps/web/src/lib/ai/chatbot.ts`
- [Gemini interpretation](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/chatbot-gemini.ts): `apps/web/src/lib/ai/chatbot-gemini.ts`
- [Chatbot audit](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/ai/chatbot-audit.ts): `apps/web/src/lib/ai/chatbot-audit.ts`

### Operations

- [Admin console](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/admin): `apps/web/src/app/admin`
- [Administration APIs](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app/api/admin): `apps/web/src/app/api/admin`
- [Admin operations](https://github.com/cs455-carpooling/campus_ridepooling_automation/blob/master/apps/web/src/lib/admin-actions.ts): `apps/web/src/lib/admin-actions.ts`

### Other components

- **Student**
- **Administrator**
- [Web application](https://github.com/cs455-carpooling/campus_ridepooling_automation/tree/master/apps/web/src/app): `apps/web/src/app`
- **Socket.IO**
- **PostgreSQL**
- **Gemini API**

## Connections

- Student → Web application: uses (evidence: `README.md`)
- Administrator → Web application: uses (evidence: `README.md`)
- Web application → Account and profile UI: routes to (evidence: `README.md`)
- Account and profile UI → Account APIs: submits credentials (evidence: `README.md`)
- Account APIs → Authentication: authenticates
- Authentication → PostgreSQL: reads and writes
- Account and profile UI → Profiles: manages profile (evidence: `README.md`)
- Student → Ride workflows: offers or finds (evidence: `README.md`)
- Ride workflows → Ride APIs: submits ride actions (evidence: `README.md`)
- Ride APIs → Ride search: searches rides
- Ride APIs → Ride options: loads options
- Ride APIs → Seat requests: manages requests (evidence: `README.md`)
- Seat requests → Ride APIs: returns request state (evidence: `README.md`)
- Ride APIs → Trip coordination: advances trip (evidence: `README.md`)
- Trip coordination → Fare settlement: records shares (evidence: `README.md`)
- Trip coordination → Ratings and complaints: enables feedback (evidence: `README.md`)
- Student → Live coordination: coordinates live (evidence: `README.md`)
- Live coordination → Socket.IO: hosts (evidence: `apps/web/server.mjs`)
- Student → Ride recommendations: requests suggestions (evidence: `README.md`)
- Ride recommendations → Ride search: searches candidates (evidence: `apps/web/src/lib/ai/recommendation-pipeline.ts`)
- Student → Chatbot endpoint: sends query (evidence: `README.md`)
- Chatbot endpoint → Chatbot assistant: processes message (evidence: `apps/web/src/app/api/chatbot/route.ts`)
- Chatbot endpoint → Ride options: loads options (evidence: `apps/web/src/app/api/chatbot/route.ts`)
- Chatbot assistant → Gemini interpretation: interprets request (evidence: `apps/web/src/lib/ai/chatbot.ts`)
- Gemini interpretation → Gemini API: calls model
- Chatbot endpoint → Chatbot audit: logs requests (evidence: `apps/web/src/app/api/chatbot/route.ts`)
- Administrator → Admin console: reviews operations (evidence: `README.md`)
- Admin console → Administration APIs: submits decisions (evidence: `README.md`)
- Administration APIs → Admin operations: applies controls
- Admin operations → PostgreSQL: audits changes
