# swapnaniltripathy/spotfree architecture

> Architecture diagram of the GitHub repository swapnaniltripathy/spotfree, 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/swapnaniltripathy/spotfree
- Repository: https://github.com/swapnaniltripathy/spotfree

## Overview

SpotFree is a campus room-discovery and management product. Users enter through the Next.js app, browse room availability or identify a room, inspect details, then reserve or update status where permitted; recommendations, QR/manual identification, history, timetable, notifications, and profile functions are distinct branches. The frontend context and mock data provide the evidenced room state, while a separate Express backend exposes OTP, authentication, and room API routes backed by database utilities. The README describes backend integration as a roadmap; sampled source does not establish that the frontend calls these endpoints.

Main entry points: [`frontend/context/SpotFreeContext.tsx`](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/context/SpotFreeContext.tsx) (Application state), [`backend/server.js`](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/server.js) (Express API), [`frontend/components/screens/RoomIdentifiedScreen.tsx`](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/RoomIdentifiedScreen.tsx) (Identified room), [`frontend/app/page.tsx`](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/app/page.tsx) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["App entry<br/>[page.tsx]"]
  node_shell["App shell<br/>[AppShell.tsx]"]
end

subgraph group_domain["Room workflows"]
  node_availability["Room discovery"]
  node_details["Room details"]
  node_recommend["Room recommendation"]
  node_qr["QR identification"]
  node_manual["Manual identification"]
  node_identified["Identified room"]
  node_status["Status updates"]
  node_reservation["Reservation controls"]
  node_history["Status history"]
  node_timetable["Timetable"]
  node_notifications["Notifications"]
  node_profile["Profile<br/>[ProfileScreen.tsx]"]
  node_admin["Room administration"]
end

subgraph group_backend["Backend services"]
  node_api["Express API<br/>[server.js]"]
  node_auth["Auth routes<br/>[auth.js]"]
  node_otp["OTP routes<br/>[otp.js]"]
  node_roomsapi["Room routes<br/>[rooms.js]"]
  node_session["Session handling<br/>[session.js]"]
  node_scheduler["Room scheduler<br/>[scheduler.js]"]
end

subgraph group_state["State and persistence"]
  node_context["Application state"]
  node_ui["UI preferences<br/>[UIPrefsContext.tsx]"]
  node_mock["Mock domain data<br/>[mockData.ts]"]
  node_db[("Database access<br/>[db.js]")]
end

node_user(("Campus user"))

node_user -->|"opens"| node_app
node_app -->|"reads state"| node_context
node_app -->|"renders"| node_shell
node_shell -->|"shows screen"| node_availability
node_availability -->|"reads rooms"| node_context
node_details -->|"reads room"| node_context
node_recommend -->|"requests match"| node_context
node_qr -->|"identifies room"| node_context
node_manual -->|"identifies room"| node_context
node_identified -->|"reads room"| node_context
node_status -->|"updates status"| node_context
node_reservation -->|"validates booking"| node_context
node_history -->|"reads history"| node_context
node_timetable -->|"reads schedule"| node_context
node_notifications -->|"reads notices"| node_context
node_profile -->|"reads profile"| node_context
node_admin -->|"manages rooms"| node_context
node_context -->|"loads initial data"| node_mock
node_availability -->|"opens room"| node_details
node_qr -->|"passes identity"| node_identified
node_manual -->|"passes identity"| node_identified
node_identified -->|"starts update"| node_status
node_api -->|"dispatches"| node_auth
node_api -->|"dispatches"| node_otp
node_api -->|"dispatches"| node_roomsapi
node_api -->|"initializes"| node_db
node_api -->|"starts"| node_scheduler
node_auth -->|"uses sessions"| node_session
node_auth -->|"queries users"| node_db
node_session -->|"finds user"| node_db

click node_app "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/app/page.tsx"
click node_shell "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/AppShell.tsx"
click node_availability "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/RoomAvailabilityScreen.tsx"
click node_details "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/RoomDetailsScreen.tsx"
click node_recommend "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/BestRoomRequirementsScreen.tsx"
click node_qr "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/ScanRoomQRScreen.tsx"
click node_manual "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/EnterRoomNumberScreen.tsx"
click node_identified "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/RoomIdentifiedScreen.tsx"
click node_status "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/UpdateRoomStatusScreen.tsx"
click node_reservation "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/ReservationWindow.tsx"
click node_history "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/StatusHistoryScreen.tsx"
click node_timetable "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/MyTimetableScreen.tsx"
click node_notifications "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/NotificationsScreen.tsx"
click node_profile "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/ProfileScreen.tsx"
click node_admin "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/ManageRoomsScreen.tsx"
click node_context "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/context/SpotFreeContext.tsx"
click node_ui "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/context/UIPrefsContext.tsx"
click node_mock "https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/lib/mockData.ts"
click node_api "https://github.com/swapnaniltripathy/spotfree/blob/main/backend/server.js"
click node_auth "https://github.com/swapnaniltripathy/spotfree/blob/main/backend/routes/auth.js"
click node_otp "https://github.com/swapnaniltripathy/spotfree/blob/main/backend/routes/otp.js"
click node_roomsapi "https://github.com/swapnaniltripathy/spotfree/blob/main/backend/routes/rooms.js"
click node_session "https://github.com/swapnaniltripathy/spotfree/blob/main/backend/lib/session.js"
click node_db "https://github.com/swapnaniltripathy/spotfree/blob/main/backend/lib/db.js"
click node_scheduler "https://github.com/swapnaniltripathy/spotfree/blob/main/backend/lib/scheduler.js"

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_app,node_shell,node_user toneBlue
class node_availability,node_details,node_recommend,node_qr,node_manual,node_identified,node_status,node_reservation,node_history,node_timetable,node_notifications,node_profile,node_admin toneAmber
class node_api,node_auth,node_otp,node_roomsapi,node_session,node_scheduler toneMint
class node_context,node_ui,node_mock,node_db toneRose
```

## Components

### Frontend experience

- [App entry](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [App shell](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/AppShell.tsx): `frontend/components/AppShell.tsx`

### Room workflows

- [Room discovery](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/RoomAvailabilityScreen.tsx): `frontend/components/screens/RoomAvailabilityScreen.tsx`
- [Room details](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/RoomDetailsScreen.tsx): `frontend/components/screens/RoomDetailsScreen.tsx`
- [Room recommendation](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/BestRoomRequirementsScreen.tsx): `frontend/components/screens/BestRoomRequirementsScreen.tsx`
- [QR identification](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/ScanRoomQRScreen.tsx): `frontend/components/screens/ScanRoomQRScreen.tsx`
- [Manual identification](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/EnterRoomNumberScreen.tsx): `frontend/components/screens/EnterRoomNumberScreen.tsx`
- [Identified room](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/RoomIdentifiedScreen.tsx): `frontend/components/screens/RoomIdentifiedScreen.tsx`
- [Status updates](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/UpdateRoomStatusScreen.tsx): `frontend/components/screens/UpdateRoomStatusScreen.tsx`
- [Reservation controls](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/ReservationWindow.tsx): `frontend/components/ReservationWindow.tsx`
- [Status history](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/StatusHistoryScreen.tsx): `frontend/components/screens/StatusHistoryScreen.tsx`
- [Timetable](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/MyTimetableScreen.tsx): `frontend/components/screens/MyTimetableScreen.tsx`
- [Notifications](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/NotificationsScreen.tsx): `frontend/components/screens/NotificationsScreen.tsx`
- [Profile](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/ProfileScreen.tsx): `frontend/components/screens/ProfileScreen.tsx`
- [Room administration](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/components/screens/ManageRoomsScreen.tsx): `frontend/components/screens/ManageRoomsScreen.tsx`

### Backend services

- [Express API](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/server.js): `backend/server.js`
- [Auth routes](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [OTP routes](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/routes/otp.js): `backend/routes/otp.js`
- [Room routes](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/routes/rooms.js): `backend/routes/rooms.js`
- [Session handling](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/lib/session.js): `backend/lib/session.js`
- [Room scheduler](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/lib/scheduler.js): `backend/lib/scheduler.js`

### State and persistence

- [Application state](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/context/SpotFreeContext.tsx): `frontend/context/SpotFreeContext.tsx`
- [UI preferences](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/context/UIPrefsContext.tsx): `frontend/context/UIPrefsContext.tsx`
- [Mock domain data](https://github.com/swapnaniltripathy/spotfree/blob/main/frontend/lib/mockData.ts): `frontend/lib/mockData.ts`
- [Database access](https://github.com/swapnaniltripathy/spotfree/blob/main/backend/lib/db.js): `backend/lib/db.js`

### Other components

- **Campus user**

## Connections

- Campus user → App entry: opens
- App entry → Application state: reads state
- App entry → App shell: renders
- App shell → Room discovery: shows screen
- Room discovery → Application state: reads rooms
- Room details → Application state: reads room
- Room recommendation → Application state: requests match
- QR identification → Application state: identifies room
- Manual identification → Application state: identifies room
- Identified room → Application state: reads room
- Status updates → Application state: updates status
- Reservation controls → Application state: validates booking
- Status history → Application state: reads history
- Timetable → Application state: reads schedule
- Notifications → Application state: reads notices
- Profile → Application state: reads profile
- Room administration → Application state: manages rooms
- Application state → Mock domain data: loads initial data
- Room discovery → Room details: opens room
- QR identification → Identified room: passes identity
- Manual identification → Identified room: passes identity
- Identified room → Status updates: starts update
- Express API → Auth routes: dispatches
- Express API → OTP routes: dispatches
- Express API → Room routes: dispatches
- Express API → Database access: initializes
- Express API → Room scheduler: starts
- Auth routes → Session handling: uses sessions
- Auth routes → Database access: queries users
- Session handling → Database access: finds user