Smart Campus OS

Smart Campus OS is a production-style full-stack university platform that connects students, faculty, and admins in one place. It covers smart attendance, campus resources, hostels, complaints, notes, forums, event ticketing, notifications, and an AI-powered campus assistant.

Author: Aayush Sharma

30s Workflow Animation

The animation loops through the full flow: user login, React frontend, Express API, MongoDB data layer, core campus modules, and AI-powered notifications.

If your viewer does not autoplay it, open project-workflow-30s.svg directly.

3D Demo Preview

3D Demo Gallery

Event Poster

Stack

Layer	Technology
Frontend	React 19, Vite, Tailwind CSS v4, React Router, Axios, Socket.io client, Recharts, react-hot-toast, html5-qrcode
Backend	Node.js, Express, Mongoose, JWT, Socket.io, QRCode, Nodemailer, Cloudinary, OpenAI, Razorpay, Stripe
Database	MongoDB
Deployment	Docker Compose, nginx, Vercel, Render

Key Modules

• Smart attendance with rolling QR, geofence checks, and attendance prediction
• Resource booking for library, labs, rooms, and shared campus infrastructure
• Student utilities such as notes, forum, lost and found, peers, and bookmarks
• Admin workflows for complaints, notices, approvals, hostels, and analytics
• Event management with QR tickets, organizer tools, and payment hooks
• AI Campus Brain for feed summaries, chatbot support, and smart suggestions

Project Structure

Path	What it contains	Purpose
backend/src/app.js	Express app, middleware, route mounting	Main API bootstrap
backend/src/config/	DB, Cloudinary, production config	Environment and infrastructure setup
backend/src/controllers/	Auth, event, campus, admin handlers	Request/response business logic
backend/src/models/	Mongoose schemas for users, bookings, attendance, hostels, forum, and more	Database layer
backend/src/routes/	index.js, campusRoutes.js	REST API entry points
backend/src/services/	OpenAI, email, notifications	External service integrations
backend/src/sockets/	Socket.io initialization	Realtime notifications and chat events
backend/src/utils/	QR, geo, logging, uploads, validators	Shared backend helpers
backend/src/scripts/	Seed scripts	Demo and initial data setup
backend/public/images/	Hostel and campus image assets	Backend-served static visuals
frontend/src/pages/	admin, auth, faculty, public, shared, student	Route-level screens
frontend/src/components/	Layout, cards, QR scanner, chat, gallery	Reusable UI building blocks
frontend/src/context/	Auth and theme providers	Global client state
frontend/src/hooks/	Custom hooks such as campus socket handling	Reusable client logic
frontend/src/lib/	API client helpers	Frontend data access layer
frontend/public/	Poster, icons, favicon, payment QR, hostel images	Public-facing static assets
docs/	API, Docker, and security docs	Supporting project documentation
docs/images/	README visual assets	Demo illustrations for documentation
scripts/	Deployment helpers	Repo-level automation
docker-compose.yml	Multi-service local stack	Local container orchestration

Prerequisites

• Node.js 18+
• MongoDB local instance or MongoDB Atlas

Local Setup

1. Start the backend

cd backend
copy .env.example .env
# Required: MONGODB_URI, JWT_SECRET
# Optional: OPENAI_API_KEY, CLOUDINARY_*, CLIENT_URL
npm install
npm run dev

API and Socket.io run at http://localhost:5000.

2. Start the frontend

cd frontend
copy .env.example .env
# Default socket URL is already set in .env.example
npm install
npm run dev

The Vite app runs at http://localhost:3001 and proxies /api to the backend.

3. Seed demo data

cd backend
npm run seed

Role	Email	Password
Student	demo.student@campus.edu	demo1234
Faculty	demo.faculty@campus.edu	demo1234
Admin	demo.admin@campus.edu	demo1234

The seed also creates an active CS301 attendance session near 28.6139, 77.209 with an approximate 200 m radius. Faculty can open the rolling QR from the attendance page, and students can test the scan flow with matching coordinates.

Optional Integrations

• OPENAI_API_KEY enables richer AI chat, summaries, and assistant responses.
• CLOUDINARY_* enables real file storage for uploads and image handling.
• Stripe and Razorpay support the event payment flow already wired into the project.

AI Campus Brain APIs

• GET /api/campus/ai/brain-feed for personalized campus feed insights
• POST /api/campus/ai/chat for the student assistant chat flow
• GET /api/campus/ai/attendance-prediction for attendance risk checks
• GET /api/campus/resources/suggest-slots for low-crowd booking suggestions

Socket.io joins each user room as user:<id> and emits campus_notification events when new in-app notifications are created.

Docker

From the repo root:

docker compose up --build

• SPA: http://localhost:8080
• API: http://localhost:5000
• MongoDB: localhost:27017

Set a strong JWT_SECRET in docker-compose.yml before using this setup beyond local demos.

Deployment Notes

Frontend on Vercel

1. Create a project with frontend as the root directory.
2. Set VITE_SOCKET_URL to your public API origin when needed.
3. Add rewrites so /api/* reaches the backend, or switch the frontend API client to an absolute backend URL.

Backend on Render

1. Create a MongoDB Atlas cluster and place the URI in MONGODB_URI.
2. Deploy backend as a web service with npm install and npm start.
3. Set JWT_SECRET, CLIENT_URL, and any optional integration keys.
4. Enable WebSockets for Socket.io support.

API Documentation

See docs/API.md for full route details. Campus-specific endpoints are grouped under /api/campus/*.

Scripts

Command	Location	Purpose
npm run dev	backend	Start the API and WebSocket server with nodemon
npm run seed	backend	Seed demo users and campus data
npm run dev	frontend	Start the Vite development server
npm run build	frontend	Create a production frontend build

License

MIT - built for learning, prototyping, and hackathon demos.