🎓 Smart Campus Utility Hub

A unified platform for intelligent campus management — Streamline academic operations with AI-powered timetable generation, smart elective selection, and seamless event coordination.

📋 Table of Contents

Problem Statement
Overview
Features
Tech Stack
Project Structure
Quick Start
One-Command Setup
Documentation
Screenshots
Contributing
Roadmap

🎯 Problem Statement

University campuses face significant operational challenges with fragmented systems — timetable scheduling, elective allocation, and event management are handled through separate, often manual processes. This leads to:

Scheduling conflicts when rooms, teachers, or time slots are double-booked
Unfair elective allocation not based on objective criteria like CGPA
Poor event visibility with no central place for students to discover activities
High administrative overhead from managing everything in spreadsheets

Smart Campus Utility Hub solves these problems by providing a unified, web-based platform that automates intelligent timetable generation, CGPA-based elective allocation, and centralised event management — accessible to students, faculty, and admins from a single interface.

🌟 Overview

Smart Campus Utility Hub is a comprehensive, full-stack campus management platform designed to revolutionize how educational institutions handle scheduling, electives, and events. Built with modern web technologies, it provides a seamless experience for students, faculty, and administrators.

Key Highlights

🤖 AI-Powered Scheduling - Intelligent timetable generation with automatic conflict detection
🎯 Smart Allocation - CGPA-based elective selection with fair distribution algorithms
🎉 Event Management - Unified platform for campus events and club activities
🔒 Secure & Scalable - JWT authentication with enterprise-grade security
🎨 Modern UI/UX - Beautiful, responsive design with smooth animations

Platform Statistics

5,000+ Students Connected
100+ Campus Events Managed
50+ Active Clubs

✨ Features

📅 Timetable Management

Automated Generation - Backtracking algorithm for optimal scheduling
Conflict Detection - Real-time validation of scheduling conflicts
Room Allocation - Intelligent resource optimization
Export Options - Download timetables in multiple formats
Multi-View Support - Day, week, and month views

📚 Elective Selection System

CGPA-Based Allocation - Fair distribution based on academic performance
Preference Ranking - Students can prioritize their choices
Real-Time Availability - Live seat count updates
Subject Management - Comprehensive subject catalog with:
- Artificial Intelligence
- Data Warehousing & Data Mining
- Big Data Analytics
- Cloud Computing
- Machine Learning
- Network Security
- And more...

🎪 Campus Events & Clubs

Event Discovery - Browse and search campus events
RSVP Management - Easy registration and tracking
Club Activities - Manage club memberships and activities
Event Creation - Simple event posting interface
Notifications - Real-time updates for upcoming events

🔐 Authentication & Security

JWT Authentication - Secure token-based authentication
Role-Based Access - Student, Faculty, and Admin roles
Password Encryption - bcrypt hashing for user credentials
Rate Limiting - Protection against brute-force attacks
CORS & Helmet - Enhanced security headers

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
React	19+	UI Framework
TypeScript	5.x	Type Safety
Vite	7.x	Build Tool
Tailwind CSS	3.x/4.x	Styling
Framer Motion	12.x	Animations
React Router	7.x	Routing
TanStack Query	5.x	Data Fetching
Axios	1.12+	HTTP Client
Zustand	5.x	State Management
Radix UI	Latest	Accessible Components
Lucide React	0.4+	Icons
Lottie React	2.4+	Animations

Backend

Technology	Version	Purpose
Node.js	18+	Runtime
Express.js	5.x	Web Framework
PostgreSQL	13+	Database
JWT	9.x	Authentication
bcryptjs	3.x	Password Hashing
Joi	17.x	Validation
Winston	3.x	Logging
Helmet	7.x	Security
CORS	2.x	Cross-Origin Resource Sharing

DevOps & Tools

Bun - Fast JavaScript runtime (frontend alternative)
Jest - Testing framework
Supertest - API testing
Nodemon - Development server
ESLint - Code linting

📁 Project Structure

smart-campus-utility-hub/
│
├── .github/                          # GitHub configuration
│   ├── workflows/
│   │   └── lint.yml                  # CI: lint + type-check + tests
│   ├── ISSUE_TEMPLATE/               # Issue templates (bug, feature, good-first-issue)
│   └── PULL_REQUEST_TEMPLATE.md
│
├── smart-campus-backend/             # Node.js / Express API
│   ├── src/
│   │   ├── app.js                    # Express application entry point
│   │   ├── config/
│   │   │   └── db.js                 # PostgreSQL connection pool
│   │   ├── middleware/
│   │   │   ├── auth.middleware.js    # JWT authentication
│   │   │   ├── errorHandler.js       # Global error handling
│   │   │   └── validation.js         # Request validation helpers
│   │   └── components/
│   │       ├── users/                # User registration & authentication
│   │       ├── timetable/            # Timetable generation (backtracking)
│   │       ├── electives/            # CGPA-based elective selection
│   │       └── campus-events/        # Events & club management
│   ├── sql/
│   │   ├── schema.sql                # Full database schema
│   │   └── migrate.js                # Migration runner
│   ├── __tests__/                    # Jest test suites
│   ├── .env.example                  # Environment variable template
│   └── package.json
│
├── smart-campus-frontend/            # React + TypeScript frontend (Vite)
│   ├── src/
│   │   ├── components/
│   │   │   ├── ui/                   # shadcn/ui base components
│   │   │   ├── landing/              # Landing page sections
│   │   │   └── animations/           # Lottie / Framer Motion components
│   │   ├── pages/
│   │   │   ├── Landing.tsx           # Public landing page
│   │   │   ├── Auth.tsx              # Login / Registration
│   │   │   ├── student/              # Student dashboard & features
│   │   │   └── admin/                # Admin panel
│   │   ├── services/                 # API service layer (Axios)
│   │   ├── contexts/                 # React context providers
│   │   ├── hooks/                    # Custom React hooks
│   │   └── lib/
│   │       └── axios.ts              # Configured Axios instance
│   ├── .env.example                  # Environment variable template
│   └── package.json
│
├── docs/
│   ├── ISSUES.md                     # 20 pre-written NSoC GitHub issues
│   └── LABELS.md                     # GitHub label strategy
│
├── scripts/
│   └── setup.sh                      # One-command local setup script
│
├── docker-compose.yml                # Docker multi-service stack
├── CONTRIBUTING.md                   # Contribution guide
├── ROADMAP.md                        # Project roadmap (Phase 1/2/3)
└── README.md

🚀 Quick Start

Prerequisites

Node.js 18+ (Download)
PostgreSQL 13+ (Download)
npm 9+ or bun (optional)
Git (Download)

Installation

Clone the repository

git clone https://github.com/KanavCode/smart-campus-utility-hub.git
cd smart-campus-utility-hub

Backend Setup

# Navigate to backend
cd smart-campus-backend

# Install dependencies
npm install

# Create .env file from the example
cp .env.example .env
# Edit .env with your DB credentials and JWT_SECRET

# Run database migrations
npm run db:migrate

# Start development server
npm run dev

The backend will run on http://localhost:5000

Frontend Setup

# Navigate to frontend
cd ../smart-campus-frontend

# Install dependencies
npm install

# Create .env file from the example
cp .env.example .env
# VITE_API_BASE_URL=http://localhost:5000/api

# Start development server
npm run dev

The frontend will run on http://localhost:5173

Database Configuration

Create a PostgreSQL database and run the schema:

psql -U your_username -d your_database -f smart-campus-backend/sql/schema.sql

Or use the migration script:

cd smart-campus-backend
npm run db:migrate

⚡ One-Command Setup

The quickest way to get everything running locally:

# Automated setup (Node.js + PostgreSQL required)
chmod +x scripts/setup.sh
./scripts/setup.sh

Or with Docker (no local PostgreSQL needed):

# Copy and configure environment
cp smart-campus-backend/.env.example smart-campus-backend/.env
cp smart-campus-frontend/.env.example smart-campus-frontend/.env

# Start all services
docker compose up --build

This starts PostgreSQL, the backend API, and the frontend dev server automatically.

📖 Documentation

Backend API Documentation

Comprehensive API documentation is available in the backend directory:

📄 smart-campus-backend/API_DOCUMENTATION.md
📄 smart-campus-backend/README.md

Frontend Documentation

📄 smart-campus-frontend/INTEGRATION_GUIDE.md
📄 smart-campus-frontend/README.md

API Endpoints

Authentication

POST /api/auth/register - User registration
POST /api/auth/login - User login

Timetable

GET /api/timetable - Get timetable
POST /api/timetable/generate - Generate timetable
GET /api/timetable/conflicts - Check conflicts

Electives

GET /api/electives - Get available electives
POST /api/electives/select - Submit preferences
POST /api/electives/allocate - Admin allocation

Events

GET /api/events - Get all events
POST /api/events - Create event
GET /api/events/:id - Get event details
POST /api/events/:id/rsvp - RSVP to event

For detailed request/response examples, see Backend API Documentation.

🎨 Screenshots

Landing Page

Modern, animated landing page with feature highlights and testimonials.

Student Dashboard

Comprehensive dashboard with timetable, electives, and events management.

Admin Panel

Powerful admin interface for managing users, subjects, timetables, and events.

Timetable View

Interactive timetable with drag-and-drop functionality and conflict detection.

Elective Selection

Intuitive elective selection interface with preference ranking.

🧪 Testing

Backend Tests

cd smart-campus-backend

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Frontend Tests

cd smart-campus-frontend

# TypeScript type check
npx tsc --noEmit

# Lint
npm run lint

🗺️ Roadmap

See ROADMAP.md for the full project roadmap across three phases:

Phase 1 (Q2 2026) — Stability & open-source readiness
Phase 2 (Q3 2026) — New features (iCal export, waitlists, OAuth)
Phase 3 (Q4 2026+) — Scaling, Redis caching, CI/CD pipeline

🏗️ Architecture

Backend Architecture

┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Express.js │ ◄── Middleware (Auth, CORS, Helmet)
└──────┬──────┘
       │
       ├─── /api/auth ──► User Authentication
       ├─── /api/timetable ──► Timetable Generation
       ├─── /api/electives ──► Elective Selection
       └─── /api/events ──► Event Management
              │
              ▼
       ┌──────────────┐
       │  PostgreSQL  │
       └──────────────┘

Frontend Architecture

┌─────────────┐
│   Router    │
└──────┬──────┘
       │
       ├─── Landing ──► Public landing page
       ├─── Auth ──► Login/Register
       ├─── Student Dashboard ──► Student features
       └─── Admin Dashboard ──► Admin features
              │
              ├─── TanStack Query ──► Data fetching
              ├─── Zustand ──► State management
              └─── Axios ──► API communication

🤝 Contributing

We welcome contributions from the community! Whether it's bug fixes, feature additions, or documentation improvements. This project participates in NSoC 2026.

👉 Read the full contribution guide: CONTRIBUTING.md

How to Contribute

Fork the repository
Create a feature branch
```
git checkout -b feat/your-feature-name
```

Commit with Conventional Commits

git commit -m "feat(timetable): add iCal export endpoint"

Push and open a Pull Request
```
git push origin feat/your-feature-name
```

Good First Issues

Looking for a place to start? Check out issues labelled good first issue or browse the pre-written issues in docs/ISSUES.md.

🐛 Troubleshooting

Common Issues

Database Connection Error

# Check PostgreSQL is running
psql -U postgres -c "SELECT version();"

# Verify .env DATABASE_URL is correct
# Format: postgresql://user:password@localhost:5432/database

Frontend API Connection Failed

# Ensure backend is running on correct port
# Verify VITE_API_URL in .env matches backend port
# Check CORS configuration in backend

Port Already in Use

# Find and kill process using port 5000
lsof -ti:5000 | xargs kill -9

# Or change port in .env file

For more troubleshooting, see Backend Troubleshooting Guide.

📞 Support

Team

Smart Campus Team

Mann
Kanav
Kavya
Kirtan

Contact

GitHub Issues: Report a bug
Discussions: Ask questions

🙏 Acknowledgments

React - UI Framework
Express.js - Backend Framework
PostgreSQL - Database
Tailwind CSS - Styling
Radix UI - Component Primitives
Framer Motion - Animations

Made with ❤️ by the Smart Campus Team

⭐ Star this repository if you find it helpful!

Report Bug · Request Feature · Documentation · Contributing

Name		Name	Last commit message	Last commit date
Latest commit History 132 Commits
.github		.github
docs		docs
scripts		scripts
smart-campus-backend		smart-campus-backend
smart-campus-frontend		smart-campus-frontend
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
ROADMAP.md		ROADMAP.md
docker-compose.yml		docker-compose.yml
test-connection.html		test-connection.html

Folders and files

Latest commit

History

Repository files navigation

🎓 Smart Campus Utility Hub

📋 Table of Contents

🎯 Problem Statement

🌟 Overview

Key Highlights

Platform Statistics

✨ Features

📅 Timetable Management

📚 Elective Selection System

🎪 Campus Events & Clubs

🔐 Authentication & Security

🛠️ Tech Stack

Frontend

Backend

DevOps & Tools

📁 Project Structure

🚀 Quick Start

Prerequisites

Installation

Database Configuration

⚡ One-Command Setup

📖 Documentation

Backend API Documentation

Frontend Documentation

API Endpoints

Authentication

Timetable

Electives

Events

🎨 Screenshots

Landing Page

Student Dashboard

Admin Panel

Timetable View

Elective Selection

🧪 Testing

Backend Tests

Frontend Tests

🗺️ Roadmap

🏗️ Architecture

Backend Architecture

Frontend Architecture

🤝 Contributing

How to Contribute

Good First Issues

🐛 Troubleshooting

Common Issues

📞 Support

Team

Contact

🙏 Acknowledgments

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages