ATLAS — Hostel Management System

A full-stack hostel management platform for educational institutions. Manages student profiles, attendance, leave applications, complaints, room allocation, canteen operations, and real-time notifications via Telegram.

---

Overview

ATLAS is a comprehensive hostel management system built as a monorepo, featuring role-based dashboards for Students, Wardens, Admins, Canteen Managers, and Caretakers. It streamlines operations from room allocation and attendance tracking to food ordering and complaint resolution, with optional Telegram bot integration for notifications.

---

Features

User Roles & Access

Role	Capabilities
Student	Profile, attendance, leaves, complaints, canteen wallet, food orders
Warden	Approve/reject leaves, mark attendance, manage complaints
Caretaker	Attendance marking, complaint tracking, leave oversight
Canteen Manager	Menu management, order processing, billing
Admin	User management, room allocation, reports, system configuration

Core Modules

• Authentication — JWT (access + refresh tokens), email verification, forgot/reset password
• Attendance — In/out time tracking, status (Present/Absent/Late), date-wise records
• Leave Management — Apply, approve/reject, status tracking
• Complaints — Create, track status (Pending/In Progress/Resolved), image attachments
• Room Management — Room allocation, capacity, floor-wise organization
• Canteen — Menu by category (Breakfast, Lunch, Dinner, Snacks, etc.), food ordering, billing, transaction history
• Notifications — Email (Nodemailer) and optional Telegram bot for real-time updates
• Reports — Dashboard stats, export to Excel/CSV

---

Tech Stack

Layer	Technologies
Frontend	React 19, Vite 7, Tailwind CSS 4, shadcn/ui, React Query, Zustand, React Router
Backend	Node.js, Express 5, Prisma ORM
Database	PostgreSQL
Auth	JWT, bcrypt
Validation	Zod
File Upload	Cloudinary, Multer
Email	Nodemailer
Bot	node-telegram-bot-api

---

Project Structure

ATLAS/
├── backend/                 # Express API
│   ├── prisma/              # Schema, migrations, seed
│   └── src/
│       ├── controllers/     # Request handlers
│       ├── services/        # Business logic
│       ├── routes/          # API routes
│       ├── middleware/      # Auth, validation, error handling
│       └── utils/           # Helpers, logger
│
├── frontend/                # React SPA
│   └── src/
│       ├── api/             # API clients
│       ├── components/      # Reusable UI
│       ├── pages/           # Role-based pages
│       ├── store/           # Zustand state
│       └── hooks/           # Custom hooks
│
└── README.md

---

Getting Started

Prerequisites

• Node.js 18+
• pnpm (or npm)
• PostgreSQL

1. Clone the repository

git clone https://github.com/himanshhhhuv/ATLAS.git
cd ATLAS

2. Backend setup

cd backend
cp .env.example .env
# Edit .env with DATABASE_URL, JWT secrets, etc.

pnpm install
pnpm prisma generate
pnpm prisma migrate dev
pnpm dev

API runs at http://localhost:5000

3. Frontend setup

cd frontend
cp .env.example .env  # if available, or create .env with VITE_API_URL
pnpm install
pnpm dev

App runs at http://localhost:5173

4. (Optional) Telegram Bot

See backend/TELEGRAM_BOT.md for setup instructions.

---

API Documentation

• API Routes — Full endpoint documentation
• Database Schema — Schema reference (if present)
• Health check: GET /health

---

License

MIT