Resolvo — Campus Issue Management System

A premium, full-stack platform that streamlines student grievance tracking through a structured, role-based escalation workflow.

About the Project

Resolvo is a campus issue management system built to solve a real problem faced by educational institutions: student complaints and concerns often get lost or unresolved because there is no clear, transparent channel to raise, track, and escalate them.

Resolvo provides:

A structured, role-based dashboard for Students, Faculty Advisors, Heads of Department (HoD), and Administrators.
An automated escalation engine that routes issues to the right authority at each stage.
Full audit trails so every action taken on an issue is recorded with actor and timestamp.
A modern, responsive UI with dark mode support, glassmorphism card design, and smooth animations.

Key Features

Feature	Description
🔐 Role-Based Access Control	Four roles (Student, Faculty, HoD, Admin) each with tailored dashboards and permissions
📝 Issue Submission	Students submit issues with title, description, category, and optional proof image
🔄 Smart Escalation	Issues automatically route from Faculty → HoD → Admin as needed
📊 Live Status Tracking	Issues progress through Pending → In Progress → Resolved
👥 Invite Code System	Role-specific invite codes control who can register and with which role
⬆️ Voting	Students can upvote public issues to highlight high-priority concerns
💬 Feedback	Students submit academic, teacher, and infrastructure feedback
🌙 Dark Mode	Toggleable dark/light theme stored per session
🔒 JWT Authentication	Stateless, token-based authentication with 24-hour expiry
📁 File Uploads	Proof images attached to issues, served from `/uploads`

Tech Stack

Layer	Technology
Frontend	HTML5, CSS3 (custom variables, Flexbox, Grid), JavaScript ES6+
Frontend UI	FontAwesome icons, Google Fonts (Poppins)
Backend	Node.js, Express.js v4
Database	MongoDB (via Mongoose v9)
Authentication	JSON Web Tokens (`jsonwebtoken`)
Password Hashing	`bcryptjs`
File Uploads	`multer`
Environment Config	`dotenv`
Dev Server	`nodemon`
Deployment	Vercel (serverless backend + static frontend)

Codebase Structure

Resolvo/
│
├── package.json              # Root monorepo — build/dev scripts
├── vercel.json               # Vercel deployment configuration
│
├── backend/                  # Express.js API server (Node.js)
│   ├── server.js             # Entry point — starts Express, mounts routes
│   ├── package.json          # Backend dependencies
│   ├── .env.example          # Template for required environment variables
│   │
│   ├── config/
│   │   └── db.js             # MongoDB connection (Mongoose)
│   │
│   ├── models/               # Mongoose schemas (data layer)
│   │   ├── User.js           # User accounts (all roles)
│   │   ├── Issue.js          # Issue tickets with history & escalation
│   │   ├── InviteCode.js     # Role-specific registration codes
│   │   └── Feedback.js       # Student feedback entries
│   │
│   ├── controllers/          # Business logic (MVC controllers)
│   │   ├── authController.js     # Registration, login, invite generation
│   │   ├── issueController.js    # CRUD, escalation, voting
│   │   ├── userController.js     # Profile management, password change
│   │   ├── adminController.js    # Admin stats, user/issue management
│   │   └── feedbackController.js # Submit & retrieve feedback
│   │
│   ├── routes/               # Express route definitions
│   │   ├── auth.js           # /api/auth/*
│   │   ├── issues.js         # /api/issues/*
│   │   ├── user.js           # /api/users/*
│   │   ├── admin.js          # /api/admin/*
│   │   └── feedback.js       # /api/feedback/*
│   │
│   ├── middleware/
│   │   └── auth.js           # JWT verification middleware
│   │
│   └── uploads/              # Uploaded proof images (runtime directory)
│
└── frontend/                 # Static HTML/CSS/JS client
    ├── index.html            # Login page (app entry point)
    ├── signup.html           # Registration page
    ├── style.css             # Global stylesheet
    ├── api-config.js         # Dynamic API base URL (local vs. Vercel)
    │
    ├── auth.js               # Client-side login/signup logic
    ├── app.js                # Shared utilities & theme toggle
    ├── dashboard.js          # Shared dashboard data-fetching helpers
    ├── admin.js              # Admin-specific client logic
    │
    ├── student-dashboard.html    # Student home — public issues & stats
    ├── faculty-dashboard.html    # Faculty home — assigned issues
    ├── hod-dashboard.html        # HoD home — escalated issues
    ├── admin-dashboard.html      # Admin home — campus-wide stats
    ├── admin-issues.html         # Admin issue management table
    ├── department-issues.html    # Departmental issue view
    ├── assigned-issues.html      # Issues assigned to current user
    ├── my-issues.html            # Student's own submitted issues
    ├── submit-issue.html         # Issue submission form
    ├── profile.html              # User profile & password change
    ├── users.html                # Admin user management
    └── feedback.html             # Feedback submission form

Architecture Overview

Resolvo follows a classic MVC (Model-View-Controller) pattern on the backend and a role-based static SPA on the frontend.

Browser (HTML/CSS/JS)
        │
        │  HTTP / REST (x-auth-token header)
        ▼
  Express.js Router
        │
        ├── auth.js middleware  ── JWT validation
        │
        ├── /api/auth      → authController.js
        ├── /api/issues    → issueController.js
        ├── /api/users     → userController.js
        ├── /api/admin     → adminController.js
        └── /api/feedback  → feedbackController.js
                │
                ▼
         Mongoose ODM
                │
                ▼
         MongoDB Atlas

Key design decisions:

Stateless JWT Auth — No server-side sessions. Each request carries a signed token containing userId, role, department, section, and batch. The auth middleware decodes and attaches this to req.user.
Auto-Assignment — When a student submits an issue, the backend queries for a faculty member in the same department/section/batch and assigns the issue automatically (falls back to HoD if no faculty is found).
Escalation Levels — escalationLevel on the Issue document drives routing: 1 = Faculty, 2 = HoD, 3 = Admin.
Audit Trail — Every status change or escalation appends an entry to the history array on the issue document.
Invite Code Security — Users can only register with a valid, unused invite code. Codes encode role, department, section, and batch, preventing unauthorized sign-ups.

User Flow

1. Authentication

Open index.html (login page)
  ├── Admin  → fixed credentials (admin@resolvo.com / Admin@123)
  └── Others → must have a valid invite code
         │
         ▼
   Backend validates credentials / invite code
         │
         ▼
   JWT token issued (24h expiry)
   Stored in localStorage
         │
         ▼
   Redirect to role-specific dashboard

2. Student — Submitting an Issue

Student Dashboard (student-dashboard.html)
  │
  ├── View public issues from other students (upvote to signal priority)
  └── Click "Submit Issue"
          │
          ▼
   submit-issue.html
   Fill: title (≥10 chars), description (≥20 chars), category, optional image
          │
          ▼
   POST /api/issues  (multipart form)
          │
          ▼
   Backend auto-assigns to Faculty in same department/section/batch
   escalationLevel = 1
          │
          ▼
   Issue appears in "My Issues" (my-issues.html)
   Status: Pending

3. Issue Escalation

Faculty Dashboard
  ├── View assigned issues (escalationLevel = 1)
  ├── Update status → "In Progress" / "Resolved"
  └── Escalate to HoD
           │
           ▼ escalationLevel = 2
  HoD Dashboard
  ├── View escalated issues
  ├── Update status → "Resolved"
  └── Escalate to Admin
           │
           ▼ escalationLevel = 3
  Admin Dashboard
  ├── View all campus issues
  ├── Update status → "Resolved"
  └── Delete issues

4. Feedback

Student → feedback.html
  ├── Academic Feedback  (select subject, rating, comments)
  ├── Teacher Feedback   (teaching quality, communication, punctuality 1–5)
  └── Infrastructure     (category: fan/projector/cleanliness etc., rating)
         │
         ▼
  POST /api/feedback
  Summary available to Admin via GET /api/feedback/summary

Setup Instructions

Prerequisites

Node.js v16 or later (v18 LTS recommended) — nodejs.org
npm v8 or later (bundled with Node.js)
MongoDB Atlas account (free tier is sufficient) — mongodb.com/atlas
A modern web browser (Chrome, Firefox, Edge)

Installation

# 1. Clone the repository
git clone https://github.com/mariaspatani/Resolvo.git
cd Resolvo

# 2. Install backend dependencies
cd backend
npm install

The frontend uses no npm packages — it is pure HTML/CSS/JS served directly.

Configuration

Create a .env file inside the backend/ directory by copying the example:

cp backend/.env.example backend/.env

Then open backend/.env and fill in your values (see Environment Variables for details):

PORT=5000
MONGO_URI=mongodb+srv://<your-mongodb-username>:<your-secure-password>@cluster0.xxxxx.mongodb.net/resolvoDB?retryWrites=true&w=majority
JWT_SECRET=your_long_random_secret_here

Running Locally

Option A — Backend + Frontend separately (recommended for development)

# Terminal 1: start the backend API server
cd backend
npm run dev       # uses nodemon — auto-restarts on file changes

# Terminal 2: open the frontend
# Simply open frontend/index.html in your browser, OR
# serve it with any static server, e.g.:
npx serve frontend

Option B — Run both concurrently from the root

# From repo root
npm run dev

The backend listens on http://localhost:5000.
The frontend, when opened on port 5500 (e.g. VS Code Live Server), automatically points its API calls to http://localhost:5000/api via api-config.js.

Building for Production

Resolvo is deployed on Vercel. The vercel.json at the root handles everything:

Builds the backend as a Node.js serverless function.
Serves the frontend/ directory as static assets.
Rewrites /api/* requests to the backend.

# Deploy with the Vercel CLI
npm i -g vercel
vercel

Usage Examples

Registering a New Student

Go to signup.html.
Enter your name, email (must end with @sjcetpalai.ac.in — this is the institution's domain enforced by the backend validator), username, and password.
Paste the invite code provided by your administrator (format: STU-CS-2024-A-XXXXXX).
On success you are redirected to student-dashboard.html.

Submitting an Issue

From the Student Dashboard, click Submit Issue.
Fill in the form:
- Title — at least 10 characters.
- Description — at least 20 characters describing the problem.
- Category — Academic, Infrastructure, Hostel, Library, or Other.
- Visibility — Public (visible to all students) or Private.
- Proof Image — optional file attachment.
Click Submit. The issue is automatically assigned to your Faculty Advisor.

Upvoting a Public Issue

On the Student Dashboard, public issues from your campus are listed. Click the ▲ Upvote button on any issue to signal its importance. Clicking again removes your vote.

Generating Invite Codes (Admin)

Log in as Admin (admin@resolvo.com / Admin@123).
Navigate to the Invite Codes section.
Select role, department, section, and batch, then click Generate.
Share the generated code with the intended user.

API Reference

All API routes are prefixed with /api. Protected routes require the header:

x-auth-token: <JWT token>

Authentication — `/api/auth`

Method	Endpoint	Auth	Description
POST	`/generate-invite`	None	Generate a new invite code
POST	`/register`	None	Register a new user with invite code
POST	`/login`	None	Log in and receive a JWT token

Issues — `/api/issues`

Method	Endpoint	Auth	Description
POST	`/`	✅	Submit a new issue (student)
GET	`/student`	✅	Get student's own issues + public issues
GET	`/faculty`	✅	Get issues assigned to the logged-in faculty
GET	`/hod`	✅	Get issues escalated to the logged-in HoD
GET	`/admin`	✅ Admin	Get all campus issues
PUT	`/status/:id`	✅	Update issue status
PUT	`/escalate/:id`	✅	Escalate issue to next level
DELETE	`/:id`	✅	Delete issue (owner or admin)
POST	`/vote/:id`	✅	Toggle upvote on an issue
DELETE	`/cleanup/all`	✅ Admin	Delete all issues

Users — `/api/users`

Method	Endpoint	Auth	Description
GET	`/`	✅ Admin	List all users
PUT	`/profile`	✅	Update own profile
PUT	`/change-password`	✅	Change own password

Admin — `/api/admin`

Method	Endpoint	Auth	Description
GET	`/stats`	✅ Admin	Campus-wide statistics
GET	`/users`	✅ Admin	List all users
PUT	`/users/:id`	✅ Admin	Update a user
DELETE	`/users/:id`	✅ Admin	Delete a user
GET	`/issues`	✅ Admin	List all issues
PUT	`/issues/:id/status`	✅ Admin	Update any issue's status
DELETE	`/issues/:id`	✅ Admin	Delete any issue
POST	`/invite-codes`	✅ Admin	Generate an invite code
GET	`/invite-codes`	✅ Admin	List all invite codes
DELETE	`/invite-codes/:id`	✅ Admin	Delete an invite code

Feedback — `/api/feedback`

Method	Endpoint	Auth	Description
POST	`/`	✅	Submit feedback
GET	`/summary`	✅	Get feedback summary

Environment Variables

All environment variables live in backend/.env. A template is provided at backend/.env.example.

Variable	Required	Default	Description
`PORT`	No	`5000`	Port the Express server listens on
`MONGO_URI`	Yes	—	MongoDB Atlas connection string
`JWT_SECRET`	Yes	—	Secret key used to sign and verify JWT tokens. Use a long, random string in production.

Example backend/.env:

PORT=5000
MONGO_URI=mongodb+srv://<your-mongodb-username>:<your-secure-password>@cluster0.abcde.mongodb.net/resolvoDB?retryWrites=true&w=majority
JWT_SECRET=a_very_long_and_random_secret_string_here

⚠️ Never commit your .env file to version control. It is already listed in .gitignore.

Contributing

Contributions are welcome! To contribute:

Fork the repository and create a new branch:
```
git checkout -b feature/your-feature-name
```
Make your changes, keeping commits small and focused.
Test your changes locally (backend and frontend).
Push your branch and open a Pull Request against main.
Describe what your PR changes and why.

Guidelines

Follow the existing code style (ES6+, consistent naming conventions).
Keep backend controllers thin — put complex logic in helper functions.
Do not commit .env files or credentials.
For significant changes, open an issue first to discuss the approach.

License

This project is licensed under the ISC License.

ISC License

Copyright (c) 2024 mariaspatani

Permission to use, copy, modify, and/or distribute this software for any purpose
with or without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

Built with ❤️ for a better campus experience.

Navigation Menu

Repository files navigation

Resolvo — Campus Issue Management System

Table of Contents

About the Project

Key Features

Tech Stack

Codebase Structure

Architecture Overview

User Flow

1. Authentication

2. Student — Submitting an Issue

3. Issue Escalation

4. Feedback

Setup Instructions

Prerequisites

Installation

Configuration

Running Locally

Building for Production

Usage Examples

Registering a New Student

Submitting an Issue

Upvoting a Public Issue

Generating Invite Codes (Admin)

API Reference

Authentication — `/api/auth`

Issues — `/api/issues`

Users — `/api/users`

Admin — `/api/admin`

Feedback — `/api/feedback`

Environment Variables

Contributing

Guidelines

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation

Resolvo — Campus Issue Management System

Table of Contents

About the Project

Key Features

Tech Stack

Codebase Structure

Architecture Overview

User Flow

1. Authentication

2. Student — Submitting an Issue

3. Issue Escalation

4. Feedback

Setup Instructions

Prerequisites

Installation

Configuration

Running Locally

Building for Production

Usage Examples

Registering a New Student

Submitting an Issue

Upvoting a Public Issue

Generating Invite Codes (Admin)

API Reference

Authentication — /api/auth

Issues — /api/issues

Users — /api/users

Admin — /api/admin

Feedback — /api/feedback

Environment Variables

Contributing

Guidelines

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Authentication — `/api/auth`

Issues — `/api/issues`

Users — `/api/users`

Admin — `/api/admin`

Feedback — `/api/feedback`