CampusFix

Live at: CampusFix.in

A production-grade, microservice-backed Infrastructure Complaint Management System built specifically for college and university campuses. CampusFix replaces slow, paper-based complaint processes with a fast, transparent, and secure digital workflow.

---

Table of Contents

1. Overview
2. Live Demo & Access
3. System Architecture
4. In-Depth Technical Specifications
5. Key Features
6. Security & Compliance
7. Tech Stack
8. Local Development
9. Deployment Guide
10. Engineering Directives
11. Contributors

---

Overview

CampusFix is an enterprise-ready complaint management system engineered to streamline how campus issues (Infrastructure, Academics, General) are reported, tracked, and resolved.

It features a hybrid architecture:

• A lightning-fast Python/Flask monolithic core for authentication, UI serving, and business logic.
• A dedicated Java/Spring Boot microservice strictly handling heavy PDF/Excel enterprise reporting capabilities.

---

Live Demo & Access

Portal: https://campusfix.in

Role	Access Method
Student	Register natively using PRN/Email, or use One-Click Google OAuth.
Admin	Protected. Requires manual provisioning by the system administrator.

---

System Architecture

CampusFix utilizes a Clean Layered Architecture with strict separation of concerns, alongside a dedicated microservice for reporting.

High-Level Topology

Browser (Client)
  |
  +---> [ Python / Flask App ] (Port 5000) ---> MongoDB Atlas (Primary DB)
  |       |-- Models (CRUD)                      ^
  |       |-- Services (Business Logic)          |
  |       |-- Routes (Controllers)               |
  |       +-- Cloudinary (Media CDN)             |
  |                                              |
  +---> [ Java / Spring Boot ] (Port 8080) ------+
          +-- Reporting Microservice (PDF/Excel)

Directory Structure

CampusFix/
|-- app.py                   # Entry point (Flask app, error handlers, initialization)
|-- db.py                    # MongoDB connection & explicit index definitions
|-- models/                  # DB Layer (Strict CRUD operations only)
|-- routes/                  # Controller Layer (Thin HTTP shells, session parsing)
|-- services/                # Business Logic Layer (Workflows, auth, validation)
|-- utils/                   # Shared utilities (Security, File Handling, Limiter)
|-- templates/               # Jinja2 HTML templates
|-- static/                  # Vanilla CSS (Dark Glassmorphism) & Vanilla JS (SPA logic)
+-- campusfix-reports-java/  # Spring Boot Microservice for PDF/Excel generation

---

In-Depth Technical Specifications

1. Authentication Flow

Authentication is managed via securely signed Flask sessions. The system supports native PRN/Password authentication secured by bcrypt, as well as Google OAuth 2.0 via authlib. State tokens are used during OAuth flow to prevent CSRF attacks on the login process.

2. Media Upload Pipeline

All media uploads (Live Camera Photos and Live Videos) go through a multi-stage pipeline:

• Client-Side Compression: Real-time compression of photos via HTML5 Canvas and videos via the MediaRecorder API to minimize bandwidth.
• MIME Allowlist: Strictly filters for image/jpeg, image/png, image/webp, video/mp4, video/webm, and video/quicktime.
• Server-Side Verification: A strict 25 MB payload limit is enforced. Before uploading, image bytes are verified using PIL.Image.verify() to catch embedded executable binaries masquerading as images.
• Cloudinary Streaming: Files are never written to the local disk. They are streamed directly into Cloudinary, with automatic thumbnail generation for videos.

3. Asynchronous Email Delivery

To prevent slow HTTP responses during complaint submission or password resets, the email system utilizes the Brevo REST API (HTTPS/443). Emails are dispatched in a background daemon thread (threading.Thread(target=_worker, daemon=True)) ensuring the user interface responds instantly while notifications are processed asynchronously.

4. Database Architecture

The primary database is MongoDB Atlas.

• Indexes: Explicit indexes are defined in db.py on fields like student_id, status, and prn to prevent collection scans.
• Concurrency: Uses MongoDB atomic modifiers ($set, $push, $inc) exclusively. Read-modify-write patterns in Python are forbidden to avoid race conditions.

---

Key Features

For Students

• Hybrid Authentication: Secure registration linked directly to the student registry. Supports Google OAuth and native PRN + Password authentication.
• Categorized Filing: Submit complaints for Infrastructure, Academics, or Other issues.
• Live Media Capture: In-browser live camera and video capture, heavily compressed to keep uploads fast and bandwidth low.
• Real-Time Tracking: Visual pipeline tracking from "Filed" to "With Admin" to "Resolved/Rejected".
• Transparent Feedback: Direct resolution messages or rejection reasons provided by admins.

For Administrators

• SPA Dashboard: Lightning-fast navigation using Vanilla JS Single Page Application architecture. No page reloads between Analytics, Complaints, and Staff views.
• Rich Data Analytics: Live charts (Donut, Radial, Line) tracking complaint volume, resolution speed, and department-wise statistics.
• One-Click Triage: Resolve or reject complaints directly from the dashboard, requiring mandatory feedback to the student.
• Enterprise Reporting: Download beautifully styled, aggregated PDF and Excel reports generated by the Java microservice.
• Automated Alerts: Brevo-powered email notifications triggered upon specific status changes.

---

Security & Compliance

Operating with zero-tolerance for vulnerabilities, CampusFix implements strict security protocols:

Security Domain	Implementation
Input Sanitization	markupsafe.escape() on all strings. Direct request.form trust is prohibited.
CSRF Protection	Global app.before_request(csrf_protect) enforcement. Hidden tokens in all forms.
Authentication	Cryptographically signed Flask sessions. Bcrypt password hashing. No server-side memory caches.
Authorization	Strict @login_required + @role_required decorators on all protected routes.
File Upload Quarantine	Direct-to-Cloudinary streaming. MIME checking + PIL.Image.verify() to block executable binaries.
Rate Limiting	Flask-Limiter on auth routes to prevent brute-force and enumeration attacks.
Data Leak Prevention	no_cache_authenticated hooks prevent browser "Back" button exploits post-logout.

---

Tech Stack

Component	Technology
Core Backend	Python 3.11+, Flask 3.1
Reporting Engine	Java 17+, Spring Boot, iText (PDF), Apache POI (Excel)
Database	MongoDB Atlas (NoSQL)
Frontend UI	Vanilla HTML5, CSS3, Vanilla JS (Dark Glassmorphism Design)
Authentication	Bcrypt, Google OAuth 2.0
Media CDN	Cloudinary (Direct Streaming)
Email Delivery	Brevo REST API
Hosting	Render (Gunicorn 1 worker / 2 threads for Flask, Docker for Java)

---

Local Development

Prerequisites

• Python 3.11+
• Java 17+ and Maven 3.9+
• MongoDB Atlas Cluster (Free Tier)
• Cloudinary Account
• Brevo Account

1. Setup Python Backend

# Clone the repository
git clone https://github.com/your-org/CampusFix.git
cd CampusFix

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
# (Add MONGO_URI, CLOUDINARY_URL, BREVO_API_KEY, FLASK_SECRET_KEY, GOOGLE_CLIENT_ID/SECRET)

Run the application:

python app.py

Flask runs on http://localhost:5000

2. Setup Java Reporting Microservice

# In a new terminal window
cd campusfix-reports-java

# Ensure MONGO_URI environment variable is set
export MONGO_URI="your-mongodb-uri"

# Run Spring Boot
mvn spring-boot:run

Java service runs on http://localhost:8080

---

Deployment Guide

CampusFix is designed to be deployed on Render.com.

1. Python Web Service

• Environment: Python 3
• Build Command: pip install -r requirements.txt
• Start Command: gunicorn app:app --workers 1 --threads 2
• Env Vars: Set all keys from .env

2. Java Web Service

• Environment: Docker
• Root Directory: campusfix-reports-java
• Env Vars: MONGO_URI
• Health Check: /api/reports/health

---

Engineering Directives

All contributors must adhere to AGENTS.md, which enforces the following:

1. Layer Rules: models/ is for DB operations only. routes/ cannot import the DB directly. All logic goes in services/.
2. Atomic DB Operations: Use $set, $push, and $inc to avoid race conditions. No read-modify-write loops in Python.
3. Mandatory Pagination: Use get_complaints_paginated() for large data sets. Do not load entire collections into memory.
4. Design Integrity: Maintain the Dark Glassmorphism UI (#121212 backgrounds, rgba(255, 255, 255, 0.05) blur). No external CSS frameworks (e.g., Tailwind, Bootstrap) are permitted.

---

Contributors

• Avadhut Satpute
• Prajyot Patil
• Komal Satam
• Sujal Munj

---

Built for Campuses. Deployed at CampusFix.in
Copyright 2026 CampusFix