# manyruumpus/cs455-iitk-campus-duo- architecture

> Architecture diagram of the GitHub repository manyruumpus/cs455-iitk-campus-duo-, 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/manyruumpus/cs455-iitk-campus-duo-
- Repository: https://github.com/manyruumpus/cs455-iitk-campus-duo-

## Overview

Campus Duo is a student platform for verified IIT Kanpur students to find compatible study partners and reserve study spaces. The main workflow is authentication, profile setup, deterministic partner discovery, and capacity-aware booking; social features, administration, and a bounded AI assistant provide distinct supporting capabilities. The graph follows documented API and architecture relationships plus sampled route wiring. Several feature implementations were not sampled, so their internal calls are not inferred.

Main entry points: [`backend/src/config/db.ts`](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/config/db.ts) (Database Access), [`frontend/src/app/routes.tsx`](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/frontend/src/app/routes.tsx) (Application Routes), [`backend/src/services/agentService.ts`](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/agentService.ts) (Governed AI Assistant), [`backend/src/services/authService.ts`](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/authService.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Student and Admin App"]
  node_web["Web Application<br/>[App.tsx]"]
  node_routes["Application Routes<br/>[routes.tsx]"]
  node_student_features["Student Features"]
  node_auth_features["Authentication UI"]
  node_admin_features["Admin Features"]
end

subgraph group_api["Backend API"]
  node_auth_api["Auth API<br/>[auth.ts]"]
  node_profile_api["Profile API<br/>[profile.ts]"]
  node_discovery_api["Discovery API<br/>[discovery.ts]"]
  node_booking_api["Booking API<br/>[booking.ts]"]
  node_agent_api["Agent API<br/>[agent.ts]"]
  node_admin_api["Admin API<br/>[admin.ts]"]
end

subgraph group_domain["Core Domain Services"]
  node_auth_service["Authentication<br/>[authService.ts]"]
  node_profile_service["Profile Management<br/>[profileService.ts]"]
  node_discovery_service["Partner Discovery"]
  node_scoring["Compatibility Scoring<br/>[scoringEngine.ts]"]
  node_booking_service["Space Booking<br/>[bookingService.ts]"]
  node_agent_service["Governed AI Assistant<br/>[agentService.ts]"]
  node_admin_service["Administration<br/>[adminService.ts]"]
end

subgraph group_platform["Persistence and Integrations"]
  node_email["Email Delivery<br/>[emailService.ts]"]
  node_db_access["Database Access<br/>[db.ts]"]
  node_booking_repo["Booking Repository<br/>[bookingRepo.ts]"]
  node_postgres[("PostgreSQL")]
  node_ollama["Ollama Provider<br/>[ollamaLlmClient.ts]"]
  node_hf["Hugging Face Provider"]
end

node_student(("Student"))
node_admin(("Administrator"))
node_llm_service["External Inference"]

node_web -->|"mounts routes"| node_routes
node_routes -->|"routes to"| node_auth_features
node_routes -->|"routes to"| node_student_features
node_routes -->|"routes to"| node_admin_features
node_student -->|"uses"| node_web
node_admin -->|"uses"| node_web
node_auth_api -->|"delegates to"| node_auth_service
node_profile_api -->|"delegates to"| node_profile_service
node_discovery_api -->|"delegates to"| node_discovery_service
node_booking_api -->|"delegates to"| node_booking_service
node_agent_api -->|"delegates to"| node_agent_service
node_admin_api -->|"delegates to"| node_admin_service
node_auth_service -->|"sends OTP"| node_email
node_auth_service -->|"reads and writes"| node_db_access
node_profile_service -->|"persists profile"| node_db_access
node_discovery_service -.->|"scores matches"| node_scoring
node_booking_service -->|"delegates queries"| node_booking_repo
node_booking_service -->|"uses transactions"| node_db_access
node_agent_service -->|"scores candidates"| node_scoring
node_agent_service -->|"selects provider"| node_ollama
node_agent_service -->|"selects provider"| node_hf
node_ollama -->|"requests inference"| node_llm_service
node_hf -->|"requests inference"| node_llm_service
node_admin_service -.->|"uses database"| node_db_access
node_booking_repo -.->|"reads and writes"| node_postgres
node_db_access -->|"connects to"| node_postgres

click node_web "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/frontend/src/app/App.tsx"
click node_routes "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/frontend/src/app/routes.tsx"
click node_student_features "https://github.com/manyruumpus/cs455-iitk-campus-duo-/tree/main/frontend/src/features/student"
click node_auth_features "https://github.com/manyruumpus/cs455-iitk-campus-duo-/tree/main/frontend/src/features/auth"
click node_admin_features "https://github.com/manyruumpus/cs455-iitk-campus-duo-/tree/main/frontend/src/features/admin"
click node_auth_api "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/auth.ts"
click node_profile_api "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/profile.ts"
click node_discovery_api "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/discovery.ts"
click node_booking_api "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/booking.ts"
click node_agent_api "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/agent.ts"
click node_admin_api "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/admin.ts"
click node_auth_service "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/authService.ts"
click node_profile_service "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/profileService.ts"
click node_discovery_service "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/discoveryService.ts"
click node_scoring "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/scoringEngine.ts"
click node_booking_service "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/bookingService.ts"
click node_agent_service "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/agentService.ts"
click node_admin_service "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/adminService.ts"
click node_email "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/emailService.ts"
click node_db_access "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/config/db.ts"
click node_booking_repo "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/repository/bookingRepo.ts"
click node_ollama "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/ollamaLlmClient.ts"
click node_hf "https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/huggingFaceLlmClient.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_web,node_routes,node_student_features,node_auth_features,node_admin_features toneBlue
class node_auth_api,node_profile_api,node_discovery_api,node_booking_api,node_agent_api,node_admin_api toneAmber
class node_auth_service,node_profile_service,node_discovery_service,node_scoring,node_booking_service,node_agent_service,node_admin_service toneMint
class node_email,node_db_access,node_booking_repo,node_postgres,node_ollama,node_hf toneRose
class node_student,node_admin,node_llm_service toneIndigo
```

## Components

### Student and Admin App

- [Web Application](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Application Routes](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/frontend/src/app/routes.tsx): `frontend/src/app/routes.tsx`
- [Student Features](https://github.com/manyruumpus/cs455-iitk-campus-duo-/tree/main/frontend/src/features/student): `frontend/src/features/student`
- [Authentication UI](https://github.com/manyruumpus/cs455-iitk-campus-duo-/tree/main/frontend/src/features/auth): `frontend/src/features/auth`
- [Admin Features](https://github.com/manyruumpus/cs455-iitk-campus-duo-/tree/main/frontend/src/features/admin): `frontend/src/features/admin`

### Backend API

- [Auth API](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Profile API](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/profile.ts): `backend/src/routes/profile.ts`
- [Discovery API](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/discovery.ts): `backend/src/routes/discovery.ts`
- [Booking API](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/booking.ts): `backend/src/routes/booking.ts`
- [Agent API](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/agent.ts): `backend/src/routes/agent.ts`
- [Admin API](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/routes/admin.ts): `backend/src/routes/admin.ts`

### Core Domain Services

- [Authentication](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/authService.ts): `backend/src/services/authService.ts`
- [Profile Management](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/profileService.ts): `backend/src/services/profileService.ts`
- [Partner Discovery](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/discoveryService.ts): `backend/src/services/discoveryService.ts`
- [Compatibility Scoring](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/scoringEngine.ts): `backend/src/services/scoringEngine.ts`
- [Space Booking](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/bookingService.ts): `backend/src/services/bookingService.ts`
- [Governed AI Assistant](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/agentService.ts): `backend/src/services/agentService.ts`
- [Administration](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/adminService.ts): `backend/src/services/adminService.ts`

### Persistence and Integrations

- [Email Delivery](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/emailService.ts): `backend/src/services/emailService.ts`
- [Database Access](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/config/db.ts): `backend/src/config/db.ts`
- [Booking Repository](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/repository/bookingRepo.ts): `backend/src/repository/bookingRepo.ts`
- **PostgreSQL**
- [Ollama Provider](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/ollamaLlmClient.ts): `backend/src/services/ollamaLlmClient.ts`
- [Hugging Face Provider](https://github.com/manyruumpus/cs455-iitk-campus-duo-/blob/main/backend/src/services/huggingFaceLlmClient.ts): `backend/src/services/huggingFaceLlmClient.ts`

### Other components

- **Student**
- **Administrator**
- **External Inference**

## Connections

- Web Application → Application Routes: mounts routes (evidence: `frontend/src/app/App.tsx`)
- Application Routes → Authentication UI: routes to (evidence: `frontend/src/app/routes.tsx`)
- Application Routes → Student Features: routes to (evidence: `frontend/src/app/routes.tsx`)
- Application Routes → Admin Features: routes to (evidence: `frontend/src/app/routes.tsx`)
- Student → Web Application: uses
- Administrator → Web Application: uses
- Auth API → Authentication: delegates to (evidence: `backend/src/routes/auth.ts`)
- Profile API → Profile Management: delegates to (evidence: `backend/src/routes/profile.ts`)
- Discovery API → Partner Discovery: delegates to (evidence: `backend/src/routes/discovery.ts`)
- Booking API → Space Booking: delegates to (evidence: `backend/src/routes/booking.ts`)
- Agent API → Governed AI Assistant: delegates to (evidence: `backend/src/routes/agent.ts`)
- Admin API → Administration: delegates to (evidence: `backend/src/routes/admin.ts`)
- Authentication → Email Delivery: sends OTP (evidence: `backend/src/services/authService.ts`)
- Authentication → Database Access: reads and writes (evidence: `backend/src/services/authService.ts`)
- Profile Management → Database Access: persists profile
- Partner Discovery → Compatibility Scoring: scores matches
- Space Booking → Booking Repository: delegates queries (evidence: `backend/src/services/bookingService.ts`)
- Space Booking → Database Access: uses transactions (evidence: `backend/src/services/bookingService.ts`)
- Governed AI Assistant → Compatibility Scoring: scores candidates (evidence: `backend/src/services/agentService.ts`)
- Governed AI Assistant → Ollama Provider: selects provider (evidence: `backend/src/services/agentService.ts`)
- Governed AI Assistant → Hugging Face Provider: selects provider (evidence: `backend/src/services/agentService.ts`)
- Ollama Provider → External Inference: requests inference (evidence: `backend/src/services/ollamaLlmClient.ts`)
- Hugging Face Provider → External Inference: requests inference (evidence: `backend/src/services/huggingFaceLlmClient.ts`)
- Administration → Database Access: uses database
- Booking Repository → PostgreSQL: reads and writes
- Database Access → PostgreSQL: connects to