Hostel Management System

A full-stack web application for managing hostel operations — student registrations, room allocations, and daily attendance tracking. The backend is powered by Spring Boot and uses Google Sheets as the database, making data accessible and editable directly from a spreadsheet without any database hosting costs.

---

Table of Contents

• Overview
• Architecture
• Project Structure
• Features
• Prerequisites
• Google Sheets Setup
• Backend Setup
• Frontend Setup
• Running the App
• API Reference
• Data Models
• Google Sheets Structure
• Tech Stack

---

Overview

The system has three core modules:

• Students — register, update, and remove hostel residents
• Rooms — manage rooms across blocks with capacity and occupancy tracking
• Attendance — mark daily check-in/check-out status per student with date-range queries

All data is stored in a Google Sheet, giving non-technical staff full visibility and easy export (CSV, Excel, PDF) without ever touching the application.

---

Architecture

Browser (Next.js :3000)
        │
        │  /api/* (Next.js rewrites → proxy)
        ▼
Spring Boot REST API (:8080)
        │
        │  Google Sheets API v4
        ▼
Google Sheets Spreadsheet
  ├── Students sheet
  ├── Rooms sheet
  └── Attendance sheet

The Next.js next.config.mjs rewrites all /api/* requests to http://localhost:8080/api/*, so the frontend never hardcodes the backend port directly in component code.

---

Project Structure

Hostel-Management-System/
│
├── Hostel-backend-main/                         # Spring Boot backend
│   ├── pom.xml                                  # Maven dependencies
│   └── src/main/
│       ├── java/com/hostelmanagement/
│       │   ├── HostelManagementApplication.java # Entry point
│       │   ├── config/
│       │   │   └── GoogleSheetsConfig.java      # Google Sheets API bean
│       │   ├── controller/
│       │   │   ├── StudentController.java        # /api/students endpoints
│       │   │   ├── RoomController.java           # /api/rooms endpoints
│       │   │   └── AttendanceController.java     # /api/attendance endpoints
│       │   ├── model/
│       │   │   ├── Student.java                  # Student entity + sheet row mapping
│       │   │   ├── Room.java                     # Room entity + sheet row mapping
│       │   │   └── AttendanceRecord.java         # Attendance entity + sheet row mapping
│       │   └── service/
│       │       ├── GoogleSheetsService.java      # Low-level read/write/delete helpers
│       │       ├── StudentService.java           # Student CRUD logic
│       │       ├── RoomService.java              # Room CRUD + availability logic
│       │       └── AttendanceService.java        # Attendance CRUD + date range logic
│       └── resources/
│           ├── application.properties            # Server + Google Sheets config
│           └── google-sheets-credentials.json   # ← Place your service account key here
│
└── Hostel-frontend-main/                        # Next.js frontend
    ├── app/
    │   ├── page.tsx                              # Dashboard — stats, check-ins, occupancy
    │   ├── layout.tsx                            # Root layout
    │   ├── students/page.tsx                     # Students list + management
    │   ├── rooms/page.tsx                        # Rooms list + management
    │   ├── attendance/page.tsx                   # Attendance table + marking
    │   └── api/                                  # Next.js Route Handlers (mock fallback)
    │       ├── students/route.ts
    │       ├── rooms/route.ts
    │       └── attendance/route.ts
    ├── components/
    │   ├── add-student-dialog.tsx                # Form dialog — add new student
    │   ├── add-room-dialog.tsx                   # Form dialog — add new room
    │   ├── take-attendance-dialog.tsx            # Bulk attendance marking dialog
    │   └── ui/                                   # shadcn/ui component library
    ├── lib/
    │   ├── api-client.ts                         # Axios wrapper for all backend calls
    │   └── utils.ts
    ├── next.config.mjs                           # Proxy rewrites /api/* → :8080
    └── package.json

---

Features

Dashboard

• Live stats: total students, available rooms, present today, number of blocks
• Recent check-ins table (last 5 present students for the day)
• Per-block room occupancy progress bars

Students

• Add students with name, email, phone, address, emergency contact, room assignment
• Validates room exists and is available before registration
• Edit and delete student records

Rooms

• Add rooms with block, floor, capacity, type (standard / deluxe / suite), and status
• Filter by block or status
• View available rooms at a glance

Attendance

• Bulk attendance marking via searchable, filterable student table with checkboxes
• Filter by block or search by name/ID
• View attendance by date or date range
• Query per-student attendance history

---

Prerequisites

Tool	Version	Notes
Java	17+	Required for Spring Boot 3.x
Maven	3.6+	Bundled via ./mvnw wrapper
Node.js	18+	For Next.js frontend
Google Cloud account	—	For Sheets API credentials

---

Google Sheets Setup

1. Create the spreadsheet

Go to Google Sheets, create a new spreadsheet named "Hostel Management System", and add three sheets (tabs): Students, Rooms, Attendance.

2. Get the Spreadsheet ID

From the URL: https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit — copy the YOUR_SPREADSHEET_ID portion.

3. Create a service account

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable the Google Sheets API
4. Go to IAM & Admin → Service Accounts → Create service account
5. Download the JSON key file and rename it google-sheets-credentials.json

4. Share the sheet with the service account

Open the spreadsheet → Share → add the service account email (found inside the JSON file, e.g. name@project.iam.gserviceaccount.com) with Editor access.

5. Place credentials in the backend

Hostel-backend-main/src/main/resources/google-sheets-credentials.json

---

Backend Setup

cd Hostel-backend-main

Update src/main/resources/application.properties with your spreadsheet ID:

google.sheets.spreadsheet.id=YOUR_SPREADSHEET_ID_HERE
google.sheets.service.account.email=your-service-account@project.iam.gserviceaccount.com
google.sheets.project.id=your-gcp-project-id

Build and run:

./mvnw clean install
./mvnw spring-boot:run

The API will be available at http://localhost:8080.

On first startup, the app auto-creates header rows in each sheet if they are empty.

---

Frontend Setup

cd Hostel-frontend-main
npm install

Optionally create a .env.local if the backend runs on a different host/port:

NEXT_PUBLIC_API_URL=http://localhost:8080

---

Running the App

Start the backend first, then the frontend in a separate terminal:

# Terminal 1 — Backend
cd Hostel-backend-main
./mvnw spring-boot:run

# Terminal 2 — Frontend
cd Hostel-frontend-main
npm run dev

Visit http://localhost:3000.

---

API Reference

Base URL: http://localhost:8080

All controllers use @CrossOrigin(origins = "*").

Students — /api/students

Method	Endpoint	Description
GET	/api/students	Get all students
GET	/api/students/{id}	Get student by ID
POST	/api/students	Create new student
PUT	/api/students/{id}	Update student
DELETE	/api/students/{id}	Delete student
GET	/api/students/room/{room}	Get students by room
GET	/api/students/block/{block}	Get students by block

Rooms — /api/rooms

Method	Endpoint	Description
GET	/api/rooms	Get all rooms
GET	/api/rooms/{id}	Get room by ID
POST	/api/rooms	Create new room
PUT	/api/rooms/{id}	Update room
DELETE	/api/rooms/{id}	Delete room
GET	/api/rooms/block/{block}	Get rooms by block
GET	/api/rooms/status/{status}	Get rooms by status
GET	/api/rooms/available	Get all available rooms

Attendance — /api/attendance

Method	Endpoint	Description
GET	/api/attendance	Get all attendance records
GET	/api/attendance/{id}	Get record by ID
GET	/api/attendance/date?date=YYYY-MM-DD	Get attendance for a specific date
POST	/api/attendance	Save attendance for a date
GET	/api/attendance/student/{studentId}	Get attendance by student
GET	/api/attendance/range?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD	Get attendance by date range
DELETE	/api/attendance/{id}	Delete an attendance record

POST /api/attendance request body:

{
  "date": "2024-08-15",
  "attendance": {
    "ST001": true,
    "ST002": false,
    "ST003": true
  }
}

---

Data Models

Student

Field	Type	Description
id	String	Unique student ID (e.g. ST001)
name	String	Full name
email	String	Email address
phone	String	Phone number
address	String	Permanent address
emergencyContact	String	Emergency contact number
room	String	Assigned room (e.g. A-101)
joiningDate	String	Date of joining (YYYY-MM-DD)

Room

Field	Type	Description
id	String	Unique room ID
roomNumber	String	Room identifier (e.g. A-101)
block	String	Block label (A / B / C / D)
floor	String	Floor number
capacity	int	Maximum occupants
occupants	int	Current occupants
status	String	available / occupied / maintenance

AttendanceRecord

Field	Type	Description
id	String	Unique record ID
date	String	Date (YYYY-MM-DD)
studentId	String	Student reference
name	String	Student name (denormalized)
room	String	Student's room at time of record
checkInTime	String	Check-in time or - if absent
checkOutTime	String	Check-out time or - if absent
status	String	present / absent

---

Google Sheets Structure

The application auto-initializes headers on first run:

Students sheet

| ID | Name | Email | Phone | Address | Emergency Contact | Room | Joining Date |

Rooms sheet

| ID | Room Number | Block | Floor | Capacity | Occupants | Status |

Attendance sheet

| ID | Date | Student ID | Name | Room | Check In Time | Check Out Time | Status |

---

Tech Stack

Backend

Technology	Version	Role
Spring Boot	3.1.0	REST API framework
Java	17	Runtime
Maven	—	Build tool
Google Sheets API	v4-rev20220927	Data storage layer
google-auth-library	1.19.0	Service account OAuth2 auth
google-api-client	2.2.0	HTTP client for Google APIs

Frontend

Technology	Version	Role
Next.js	15.2.4	React framework (App Router)
React	19	UI library
TypeScript	5.x	Type safety
Tailwind CSS	3.x	Styling
shadcn/ui + Radix UI	—	Accessible component library
Axios	1.9.0	HTTP client for API calls
Recharts	2.15.0	Chart components
React Hook Form	7.x	Form state management
Zod	3.x	Schema validation
next-themes	0.4.4	Dark mode