# vayu-401/hostelmate architecture

> Architecture diagram of the GitHub repository vayu-401/hostelmate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vayu-401/hostelmate
- Repository: https://github.com/vayu-401/hostelmate

## Overview

HostelMate is a role-based hostel management platform for students, wardens, and parents. Users sign in, then use role-specific dashboards to manage hostel activity; the documented architecture sends client requests over REST to an Express API, whose routes handle domain operations and persist data. Major capabilities include attendance, complaints, leave, fees, rooms, mess, visitors, notices, lost-and-found, AI, and live notifications. The route inventory is documented by server registration; unsampled feature implementations and most client-to-route mappings are represented at subsystem level rather than inferred individually.

Main entry points: [`apps/server/src/index.js`](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/index.js) (REST API server), [`apps/server/src/routes/attendance.js`](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/attendance.js) (Attendance), [`apps/server/src/routes/payments.js`](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/payments.js) (Fees and payments), [`apps/server/src/middleware/auth.js`](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/middleware/auth.js) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Role-based client"]
  node_login["Sign in<br/>[page.tsx]"]
  node_roleui["Role dashboards"]
  node_clientauth["Supabase client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_server["REST API server<br/>[index.js]"]
  node_auth["Authentication<br/>[auth.js]"]
  node_rbac["Role access<br/>[rbac.js]"]
end

subgraph group_operations["Hostel operations"]
  node_attendance["Attendance<br/>[attendance.js]"]
  node_complaints["Complaints and AI<br/>[complaints.js]"]
  node_leaves["Leave requests<br/>[leaves.js]"]
  node_payments["Fees and payments<br/>[payments.js]"]
  node_rooms["Rooms and transfers<br/>[rooms.js]"]
  node_community["Community services"]
end

subgraph group_platform["Data and integrations"]
  node_supabase[("Supabase data<br/>[supabase.js]")]
  node_redis[("Redis cache<br/>[redis.js]")]
  node_socket["Live events<br/>[socket.js]"]
  node_notify["Notifications<br/>[notify.js]"]
  node_razorpay["Razorpay payments<br/>[razorpay.js]"]
  node_ai["AI services<br/>[openai.js]"]
end

node_user(("Hostel user"))

node_user -->|"signs in"| node_login
node_login -->|"creates client"| node_clientauth
node_user -.->|"uses dashboards"| node_roleui
node_roleui -->|"REST requests"| node_server
node_server -->|"mounts route"| node_attendance
node_server -->|"mounts route"| node_complaints
node_server -->|"mounts route"| node_leaves
node_server -->|"mounts route"| node_payments
node_server -->|"mounts route"| node_rooms
node_server -->|"mounts routes"| node_community
node_attendance -->|"authenticates"| node_auth
node_payments -->|"authenticates"| node_auth
node_rooms -->|"authenticates"| node_auth
node_auth -->|"checks user"| node_supabase
node_attendance -->|"reads and writes"| node_supabase
node_payments -->|"reads and writes"| node_supabase
node_rooms -->|"reads and writes"| node_supabase
node_attendance -->|"uses cache"| node_redis
node_attendance -->|"emits events"| node_socket
node_attendance -->|"creates notifications"| node_notify
node_payments -->|"creates notifications"| node_notify
node_payments -->|"creates and verifies orders"| node_razorpay
node_complaints -.->|"AI support"| node_ai

click node_login "https://github.com/vayu-401/hostelmate/blob/main/apps/client/app/(auth)/login/page.tsx"
click node_roleui "https://github.com/vayu-401/hostelmate/tree/main/apps/client/app/(dashboard)"
click node_clientauth "https://github.com/vayu-401/hostelmate/blob/main/apps/client/lib/supabase/client.ts"
click node_server "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/index.js"
click node_auth "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/middleware/auth.js"
click node_rbac "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/middleware/rbac.js"
click node_attendance "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/attendance.js"
click node_complaints "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/complaints.js"
click node_leaves "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/leaves.js"
click node_payments "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/payments.js"
click node_rooms "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/rooms.js"
click node_community "https://github.com/vayu-401/hostelmate/tree/main/apps/server/src/routes"
click node_supabase "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/supabase.js"
click node_redis "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/redis.js"
click node_socket "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/socket.js"
click node_notify "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/notify.js"
click node_razorpay "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/razorpay.js"
click node_ai "https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/openai.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_login,node_roleui,node_clientauth,node_user toneBlue
class node_server,node_auth,node_rbac toneAmber
class node_attendance,node_complaints,node_leaves,node_payments,node_rooms,node_community toneMint
class node_supabase,node_redis,node_socket,node_notify,node_razorpay,node_ai toneRose
```

## Components

### Role-based client

- [Sign in](https://github.com/vayu-401/hostelmate/blob/main/apps/client/app/(auth)/login/page.tsx): `apps/client/app/(auth)/login/page.tsx`
- [Role dashboards](https://github.com/vayu-401/hostelmate/tree/main/apps/client/app/(dashboard)): `apps/client/app/(dashboard)`
- [Supabase client](https://github.com/vayu-401/hostelmate/blob/main/apps/client/lib/supabase/client.ts): `apps/client/lib/supabase/client.ts`

### API and access

- [REST API server](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/index.js): `apps/server/src/index.js`
- [Authentication](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/middleware/auth.js): `apps/server/src/middleware/auth.js`
- [Role access](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/middleware/rbac.js): `apps/server/src/middleware/rbac.js`

### Hostel operations

- [Attendance](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/attendance.js): `apps/server/src/routes/attendance.js`
- [Complaints and AI](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/complaints.js): `apps/server/src/routes/complaints.js`
- [Leave requests](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/leaves.js): `apps/server/src/routes/leaves.js`
- [Fees and payments](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/payments.js): `apps/server/src/routes/payments.js`
- [Rooms and transfers](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/routes/rooms.js): `apps/server/src/routes/rooms.js`
- [Community services](https://github.com/vayu-401/hostelmate/tree/main/apps/server/src/routes): `apps/server/src/routes`

### Data and integrations

- [Supabase data](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/supabase.js): `apps/server/src/config/supabase.js`
- [Redis cache](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/redis.js): `apps/server/src/config/redis.js`
- [Live events](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/socket.js): `apps/server/src/config/socket.js`
- [Notifications](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/notify.js): `apps/server/src/config/notify.js`
- [Razorpay payments](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/razorpay.js): `apps/server/src/config/razorpay.js`
- [AI services](https://github.com/vayu-401/hostelmate/blob/main/apps/server/src/config/openai.js): `apps/server/src/config/openai.js`

### Other components

- **Hostel user**

## Connections

- Hostel user → Sign in: signs in (evidence: `apps/client/app/(auth)/login/page.tsx`)
- Sign in → Supabase client: creates client (evidence: `apps/client/app/(auth)/login/page.tsx`)
- Hostel user → Role dashboards: uses dashboards
- Role dashboards → REST API server: REST requests
- REST API server → Attendance: mounts route (evidence: `apps/server/src/index.js`)
- REST API server → Complaints and AI: mounts route (evidence: `apps/server/src/index.js`)
- REST API server → Leave requests: mounts route (evidence: `apps/server/src/index.js`)
- REST API server → Fees and payments: mounts route (evidence: `apps/server/src/index.js`)
- REST API server → Rooms and transfers: mounts route (evidence: `apps/server/src/index.js`)
- REST API server → Community services: mounts routes (evidence: `apps/server/src/index.js`)
- Attendance → Authentication: authenticates (evidence: `apps/server/src/routes/attendance.js`)
- Fees and payments → Authentication: authenticates (evidence: `apps/server/src/routes/payments.js`)
- Rooms and transfers → Authentication: authenticates (evidence: `apps/server/src/routes/rooms.js`)
- Authentication → Supabase data: checks user (evidence: `apps/server/src/middleware/auth.js`)
- Attendance → Supabase data: reads and writes (evidence: `apps/server/src/routes/attendance.js`)
- Fees and payments → Supabase data: reads and writes (evidence: `apps/server/src/routes/payments.js`)
- Rooms and transfers → Supabase data: reads and writes (evidence: `apps/server/src/routes/rooms.js`)
- Attendance → Redis cache: uses cache (evidence: `apps/server/src/routes/attendance.js`)
- Attendance → Live events: emits events (evidence: `apps/server/src/routes/attendance.js`)
- Attendance → Notifications: creates notifications (evidence: `apps/server/src/routes/attendance.js`)
- Fees and payments → Notifications: creates notifications (evidence: `apps/server/src/routes/payments.js`)
- Fees and payments → Razorpay payments: creates and verifies orders (evidence: `apps/server/src/routes/payments.js`)
- Complaints and AI → AI services: AI support
