Fixify is an enterprise-grade academic software engineering platform designed to modernize how educational institutions report, track, resolve, and audit computer-lab maintenance issues. The system unifies QR-based mobile complaint logging, interactive 2D laboratory floorplans, automated SLA escalation, ticket lifecycle management, computer workstation inventory, and tamper-proof audit trails into a cohesive, secure web application.
Project Status: Active development & production deployable. Fixify supports both instant local development (with salted scrypt password authentication) and hybrid cloud deployment (Cloudflare Workers reverse-proxy gateway + Render Node 24 Web Service + MongoDB Atlas replica set + Cloudinary + Firebase Authentication).
- The Problem
- The Solution
- Core Capabilities
- User Roles
- Ticket Workflow & Lifecycle
- System Architecture & Deployment
- Technology Stack
- Folder Structure
- Project Documentation
- Getting Started
- Environment Configuration
- Available Scripts
- Testing & Quality Assurance
- Operational Notes & Considerations
- Contributing
- Team
- License
Educational computer laboratories support hundreds of students daily for coursework, practical examinations, programming labs, and research. Traditional informal maintenance reporting (paper registers, verbal notices, unsorted emails) creates critical operational bottlenecks:
- Lost & Untracked Complaints: Requests are forgotten, neglected, or left without assigned ownership.
- Duplicate Reports: Multiple students submit separate complaints for the same broken computer workstation.
- Downtime & SLA Breaches: Broken machines remain out of service for weeks with no automated escalation or visibility.
- Safety Hazards: Serious electrical faults (sparks, burning smells, damaged wiring) are treated as routine tickets rather than urgent emergencies.
- Lack of Asset History: Technicians cannot review previous component failures or recurring hardware issues for a workstation.
- Absence of Accountability: Administrators lack reliable data on repair resolution times, laboratory failure frequencies, or staff workloads.
Fixify delivers a centralized, responsive, role-based IT maintenance ecosystem tailored to college laboratory environments:
- Instant QR Code Entry: Students scan a physical QR code mounted in any computer lab, instantly opening the mobile reporting interface with the laboratory context preloaded.
- Interactive 2D Lab Floorplans: Users select the exact physical workstation via interactive floorplan hotspot maps reflecting real PCCOE laboratory layouts.
- Automated Safety Shield: Real-time keyword analysis flags hazardous electrical faults, displays immediate user safety guidance, and auto-elevates tickets to
CRITICALpriority. - Intelligent Auto-Assignment: Tickets route automatically to the designated lab assistant with the lowest active workload.
- Enforced State Machine: Multi-step ticket progression requires diagnostic notes and mandatory physical testing verification (
testedOk === true) before closure. - Automated SLA Escalation: Background cron workers continuously monitor unacknowledged tickets and escalate overdue issues directly to departmental authorities.
- Tamper-Proof Audit History: Append-only database logging records all state changes, administrative overrides, and authentication events.
- Lab-Specific Placards: High-resolution SVG/PNG printable placards encoding
${CLIENT_URL}/report?lab=<labCode>. - Interactive Visual Floorplans: Integrated 2D map views (
LabInteractiveMap) with real laboratory floorplans from/labs/(e.g. LAB-5401, LAB-5305, LAB-5308, etc.) and clickable workstation hotspots. - Streamlined Submission Flow: Mobile-first, four-step reporting workflow: select workstation, pick issue category (
HARDWARE,SOFTWARE,NETWORK,ELECTRICAL,OTHER), provide description, and optionally upload photo evidence. - Collision Protection (BR-3): MongoDB partial unique index prevents concurrent or duplicate active tickets on the same computer until the existing ticket is closed.
- Real-Time Keyword Engine: Scans descriptions for hazard terms (
burning,smoke,shock,short circuit,spark,exposed wire,fire,blast,heat). - Emergency Modal Warning: Instantly triggers an intrusive safety dialog (
ElectricalSafetyModal) directing students to immediately step away from the equipment. - Priority Escalation: Automatically marks the incident as
CRITICALpriority and dispatches urgent notifications to lab staff.
- Standardized Identification: Sequential annual ticket identifiers (
FIX-YYYY-000001) generated atomically via database counters. - Strict 10-State Machine: Explicit state transitions prevent unauthorized jumps (
OPEN→ASSIGNED→ACCEPTED→IN_PROGRESS→RESOLVED→CLOSED, with branching forESCALATED,AWAITING_PARTS,REJECTED, andCANCELLED). - Workload-Aware Auto-Assignment (BR-4): Automatically identifies lab assistants assigned to the lab and delegates tickets to the assistant with the lowest active ticket volume.
- Quality-Guaranteed Closure (BR-8): Closing a ticket strictly requires assistant confirmation that the workstation tested OK (
testedOk === true) and non-empty resolution notes. - Live Ticket Timeline: Full audit history of status updates, actor identities, timestamps, and technician notes (
TicketTimelineModal).
- Background Cron Engine: Periodically evaluates unacknowledged and pending tickets past the institutional SLA threshold (default: 24 hours).
- Free-Host Idle Wake Recovery: Automatically runs an escalation check on server startup to catch overdue tickets after waking from cloud hosting idle sleep.
- Departmental Escalation: Transitions overdue tickets to
ESCALATEDstatus with system alerts routed to Department Authorities.
- Official 12-Lab Roster: Pre-configured roster (
OFFICIAL_LAB_ROSTER) mapped to the PCCOE IT Engineering building, complete with laboratory codes, room numbers, and workstation layouts. - Granular Computer Records: Asset tags, labels, hardware specifications (CPU, RAM, storage, GPU, OS), warranty tracking, operational status (
ACTIVE,UNDER_MAINTENANCE,RETIRED), and full repair histories. - Admin Management Consoles: Dedicated interfaces for managing computers (
AdminComputers), laboratories (AdminLabs), and academic departments (AdminDepartments).
- Dual Authentication Modes:
- Firebase Authentication: Google OAuth + Email/Password with email verification and institutional domain gating.
- Local Development Mode: Salted scrypt password hashing for rapid offline development without third-party cloud dependencies.
- Strict Institutional Domain Whitelist (BR-10): Restricts access to authorized college domains (e.g.,
pccoepune.org,pccoe.org), rejecting public email domains in production. - Student PRN Validation: Enforces institutional permanent registration numbers using regex validation.
- Sliding Session Security: Signed
httpOnlyJWT session cookies (15-minute sliding expiry + 8-hour maximum session ceiling). - Inactivity Guard: Interactive idle timer modal (
IdleTimeoutModal) displaying a 2-minute countdown before automatic logout. - Reverse-Proxy Gateway Verification: Backend routes are guarded by a shared gateway secret (
x-fixify-gateway/EDGE_PROXY_SECRET) to prevent origin bypass. - Campus NAT-Friendly Rate Limiting: Keyed primarily by authenticated user ID (
req.user.id), preserving accessibility on shared campus networks. - CSRF Defense: Custom header verification (
X-Requested-With: XMLHttpRequest/X-CSRF-Token) on all mutating endpoints.
- KPI Dashboard: Real-time visibility into open complaints, resolution statistics, user distribution, and equipment maintenance warnings.
- Tamper-Proof Audit Logging: Append-only collection (
AuditLog) protected against modifications and deletions at schema, middleware, and query levels. - Staff Provisioning Pipeline: CLI script (
scripts/provision-staff.ts) and secured API (/api/v1/provision-staff) to bootstrap or synchronize staff accounts fromcredentials.env. - Dynamic Institutional Settings: Configurable escalation timeouts and inventory warning thresholds.
Fixify implements role-based access control (RBAC) enforced on both client routes and backend middleware:
| Role | Access Scope & Responsibilities |
|---|---|
STUDENT |
Report lab complaints via QR or portal, select workstations on 2D map, track personal complaint history and timeline updates. |
FACULTY |
Report lab issues, track department complaints, access expedited review workflows. |
LAB_ASSISTANT |
Access Assistant Dashboard, accept assigned tickets, diagnose issues, log repair notes, verify workstation testing, and close tickets. |
HOD |
High-level departmental overview, read-only analytics, maintenance performance indicators, and equipment reliability reports. |
ADMIN |
Manage users, departments, laboratories, computer inventory, system settings, staff provisioning, and audit logs. |
Tickets follow a finite state machine ensuring complete traceability from initial scan to final closure:

OPEN: Newly submitted complaint awaiting assignment (fallback when no assistant is configured).ASSIGNED: Assigned to a specific lab assistant based on least active workload.ACCEPTED: Acknowledged by the lab assistant.IN_PROGRESS: Physical diagnostics, software remediation, or component replacement underway.ESCALATED: Escalated to Department Authority due to SLA timeout, complexity, or component requirements.AWAITING_PARTS: Hardware requisition approved and waiting for inventory fulfillment.RESOLVED: Repair completed; awaiting final workstation operational testing.CLOSED: Fully resolved and verified with physical testing confirmation and resolution notes.REJECTED: Declared non-actionable or invalid with mandatory explanatory justification.CANCELLED: Withdrawn by the reporting student or administrator prior to repair commencement.
Fixify is architected for seamless local operation and high-availability cloud deployment:

- Cloudflare Workers: Serves the frontend single-page application from edge storage with client-side routing fallback. Reverse-proxies
/api,/socket.io,/labs,/uploads, and/healthto the backend. - Gateway Secret Defense: The Cloudflare Worker injects a shared
x-fixify-gatewayheader (EDGE_PROXY_SECRET). The Express backend rejects any direct traffic bypassing the proxy. - Same-Site Cookie Security: Because requests route through the shared Cloudflare domain, session cookies operate as first-party
SameSite=Laxcookies, avoiding third-party cookie restrictions across modern mobile browsers. - Wake-Up Detection: The Cloudflare worker gracefully detects cold starts on free Render instances, returning structured retry responses rather than raw timeouts.
| Layer | Technologies |
|---|---|
| Frontend Framework | React 18, TypeScript, Vite |
| Styling & UI Primitives | Tailwind CSS, Radix UI Primitives, Lucide Icons |
| State & Data Fetching | TanStack Query (React Query v5), Axios |
| Form Management | React Hook Form, Zod Validation |
| Data Visualization | Recharts (Admin analytics & metrics) |
| Backend Runtime | Node.js (20+ local, Node 24 on Render), Express, TypeScript, tsx |
| Database & ODM | MongoDB 7+ (Replica Set required for ACID transactions), Mongoose 8 |
| Authentication | Firebase Authentication (Web & Admin SDK), Local Scrypt Password Engine |
| Real-Time Engine | Socket.IO (room segregation by user, lab, department, and role) |
| Media Storage | Cloudinary SDK (cloud storage), Multer (multipart upload handling) |
| Logging & Utilities | Pino, Pino-Pretty, NanoID, QRCode |
| Scheduled Tasks | node-cron (automated SLA escalation checking) |
| Cloud Deployment | Cloudflare Workers (wrangler), Render Web Service (render.yaml) |
| Testing Suites | Vitest, Supertest, mongodb-memory-server, Playwright |
Fixify.git/
├── .github/
│ └── workflows/
│ └── ci.yml
├── client/
│ ├── public/
│ │ ├── favicon.svg
│ │ └── labs/ # All laboratory layout references
│ ├── src/
│ │ ├── components/
│ │ │ ├── auth/
│ │ │ ├── layout/
│ │ │ ├── profile/
│ │ │ ├── ui/
│ │ │ ├── LabInteractiveMap.tsx
│ │ │ ├── ElectricalSafetyModal.tsx
│ │ │ ├── IdleTimeoutModal.tsx
│ │ │ ├── ProtectedRoute.tsx
│ │ │ └── TicketTimelineModal.tsx
│ │ ├── config/
│ │ │ └── lab-layouts.config.ts
│ │ ├── context/
│ │ │ ├── AuthContext.tsx
│ │ │ ├── SocketContext.tsx
│ │ │ └── ThemeContext.tsx
│ │ ├── features/
│ │ │ └── complaints/
│ │ ├── lib/
│ │ │ ├── axios.ts
│ │ │ ├── email-verification.ts
│ │ │ ├── firebase.ts
│ │ │ └── utils.ts
│ │ ├── pages/
│ │ │ ├── admin/
│ │ │ ├── AssistantDashboard.tsx
│ │ │ ├── CompleteProfile.tsx
│ │ │ ├── Login.tsx
│ │ │ ├── MyComplaints.tsx
│ │ │ ├── PendingApproval.tsx
│ │ │ ├── Profile.tsx
│ │ │ ├── ReportComplaint.tsx
│ │ │ ├── Signup.tsx
│ │ │ └── VerifyEmail.tsx
│ │ ├── types/
│ │ ├── App.tsx
│ │ ├── index.css
│ │ └── main.tsx
│ ├── .env.example
│ ├── package.json
│ ├── tailwind.config.js
│ ├── tsconfig.json
│ └── vite.config.ts
├── server/
│ ├── src/
│ │ ├── common/
│ │ │ ├── config/
│ │ │ ├── database/
│ │ │ ├── errors/
│ │ │ ├── middleware/
│ │ │ ├── models/
│ │ │ ├── services/
│ │ │ ├── socket/
│ │ │ └── utils/
│ │ ├── modules/
│ │ │ ├── admin/
│ │ │ ├── audit/
│ │ │ ├── auth/
│ │ │ ├── computers/
│ │ │ ├── departments/
│ │ │ ├── laboratories/
│ │ │ ├── notifications/
│ │ │ ├── profile/
│ │ │ ├── qr/
│ │ │ ├── settings/
│ │ │ ├── tickets/
│ │ │ ├── upload/
│ │ │ └── users/
│ │ ├── app.ts
│ │ └── server.ts
│ ├── test/ # Backend unit and integration tests
│ ├── .env.example
│ ├── package.json
│ └── tsconfig.json
├── docs/
│ ├── diagrams/ # Mermaid architecture and workflow diagrams
│ ├── images/ # Generated architecture diagram images
│ ├── ui/ # UI screenshots and design references
│ ├── ASSUMPTIONS.md
│ ├── DEPLOY.md
│ ├── IMPLEMENTATION_PLAN.md
│ ├── RUN.md
│ ├── SRS.md
│ └── TRACEABILITY.md
├── labs/ # Original laboratory layout references
├── deploy/
│ └── cloudflare-worker.mjs
├── e2e/ # End-to-end tests
├── scripts/
│ ├── build-cloudflare.mjs
│ ├── dev.mjs
│ ├── e2e-server.ts
│ ├── prepare-hosting-env.mjs
│ ├── provision-staff.ts
│ ├── render-diagrams.mjs
│ └── seed.ts
├── .gitignore
├── .prettierrc
├── credentials.env.example
├── LICENSE
├── README.md
├── package.json
├── package-lock.json
├── playwright.config.ts
├── playwright.verification.config.ts
├── render.yaml
└── wrangler.jsonc
The docs/ directory contains full engineering specifications and guides:
docs/SRS.md— Complete Software Requirements Specification conforming to IEEE 29148-2018.docs/TRACEABILITY.md— Requirement Traceability Matrix mapping REQ-1.1 through BR-10 to code and tests.docs/DEPLOY.md— Complete Production Deployment Guide for Cloudflare Workers and Render.docs/RUN.md— Comprehensive Local Setup Guide for both Local Password and Firebase Auth modes.docs/ASSUMPTIONS.md— Architectural invariants, security resolutions, and resolved assumptions.docs/IMPLEMENTATION_PLAN.md— Phase-by-phase implementation blueprint.
Ensure you have installed:
- Node.js:
20.12.0or higher (v24recommended for production). - npm:
10.xor higher. - MongoDB:
7.xor higher (configured with a replica set for multi-document ACID transactions), or a free MongoDB Atlas cluster.
Fixify supports an offline development mode using salted scrypt password authentication.
-
Clone and Install Dependencies:
git clone https://github.com/Ashutoshmore24/Fixify.git cd Fixify npm install -
Configure Environment Files:
# Copy environment templates cp server/.env.example server/.env cp client/.env.example client/.env cp credentials.env.example credentials.env(On Windows Command Prompt, use
copy; on PowerShell, useCopy-Item) -
Set Local Auth Mode:
- In
server/.env:AUTH_MODE=local MONGODB_URI=yourmongodb_uri_string JWT_SECRET=super_secret_local_dev_key_at_least_32_chars_long
- In
client/.env:VITE_AUTH_MODE=local VITE_API_BASE_URL=http://localhost:5000/api/v1 VITE_SOCKET_URL=http://localhost:5000
- In
-
Set Staff Passwords: Open
credentials.envand supply passwords for the administrator and lab assistants. -
Seed Database & Laboratories:
npm run seed
This provisions the 7 default staff accounts, creates the official 12 laboratories, and registers their workstation computers.
-
Start Development Servers:
npm run dev
- Frontend: http://localhost:5173
- Backend API: http://localhost:5000
To run Fixify with Google Sign-In and email verification:
- Follow steps 1 and 2 above.
- In
server/.envandclient/.env, setAUTH_MODE=firebaseandVITE_AUTH_MODE=firebase. - Create a project in the Firebase Console and enable Email/Password and Google providers.
- Download your Firebase Admin private key, save it as
server/serviceAccountKey.json, and reference it inserver/.env:FIREBASE_SERVICE_ACCOUNT_PATH=./serviceAccountKey.json - Add your Firebase web configuration values to
client/.env. - Run
npm run seedandnpm run dev.
Fixify is configured for seamless deployment on Cloudflare Workers and Render:
-
Deploy Frontend to Cloudflare Workers:
npm run build:cloudflare npx wrangler login npm run deploy:cloudflare
-
Deploy Backend to Render:
- Create a Web Service using
render.yamlas a Blueprint. - Run the environment preparation utility:
node scripts/prepare-hosting-env.mjs https://fixify.fixify-monorepo.workers.dev
- Import the generated
deploy/render.envinto Render.
- Create a Web Service using
-
Link Edge Gateway:
npx wrangler secret put BACKEND_ORIGIN npx wrangler secret put EDGE_PROXY_SECRET
For detailed instructions, consult
docs/DEPLOY.md.
| Variable | Description | Default / Example |
|---|---|---|
NODE_ENV |
Application environment (development, production, test) |
development |
AUTH_MODE |
Authentication provider (firebase or local) |
firebase |
PORT |
Backend listening port | 5000 |
CLIENT_URL |
Allowed origin for CORS & cookie issuance | http://localhost:5173 |
SERVER_URL |
Public API base address | http://localhost:5000 |
MONGODB_URI |
MongoDB connection string (replica set required) | mongodb://127.0.0.1:27017/fixify?replicaSet=rs0 |
JWT_SECRET |
Secret key for signed session JWTs (min 32 chars in prod) | random_secret_string |
COOKIE_SECRET |
Secret key for signed cookies | cookie_secret_string |
EDGE_PROXY_SECRET |
Gateway secret matching Cloudflare Worker proxy | shared_proxy_secret |
ALLOWED_EMAIL_DOMAINS |
Permitted institutional email domains | institutional email domains |
ADMIN_EMAIL |
Default administrator account email | youradmin_email |
ESCALATION_TIMEOUT_HOURS |
Unacknowledged ticket SLA timeout | 24 |
CLOUDINARY_CLOUD_NAME |
Cloudinary cloud identifier (optional locally) | your_cloud_name |
CLOUDINARY_API_KEY |
Cloudinary API access key | your_api_key |
CLOUDINARY_API_SECRET |
Cloudinary API secret | your_api_secret |
| Variable | Description | Default / Example |
|---|---|---|
VITE_API_BASE_URL |
REST API endpoint URL | http://localhost:5000/api/v1 |
VITE_SOCKET_URL |
Socket.IO server URL | http://localhost:5000 |
VITE_AUTH_MODE |
Client authentication mode (firebase or local) |
firebase |
VITE_FIREBASE_API_KEY |
Firebase Web API key | AIzaSy... |
VITE_FIREBASE_AUTH_DOMAIN |
Firebase Auth domain | fixify-pccoe.firebaseapp.com |
VITE_FIREBASE_PROJECT_ID |
Firebase Project ID | fixify-pccoe |
VITE_APP_NAME |
Institutional branding application name | Fixify |
Run scripts from the monorepo root:
| Command | Workspace | Description |
|---|---|---|
npm run dev |
Root | Concurrently runs backend and Vite client using scripts/dev.mjs. |
npm run dev:server |
server |
Starts backend server with tsx watch for auto-reloading. |
npm run dev:client |
client |
Starts Vite development server for the React frontend. |
npm run build |
Workspaces | Builds TypeScript distribution bundles for client and server. |
npm run build:cloudflare |
Root | Prepares and bundles client distribution for Cloudflare Workers. |
npm run deploy:cloudflare |
Root | Deploys static assets and edge worker via Wrangler. |
npm run seed |
Root | Seeds official PCCOE departments, 12 labs, workstations, and staff accounts. |
npm run lint |
Workspaces | Executes ESLint across client and server workspaces. |
npm run typecheck |
Workspaces | Performs full TypeScript compilation checks (tsc --noEmit). |
npm run test |
server |
Runs the Vitest test suite (unit, integration, and security tests). |
npm run test:e2e |
Root | Executes Playwright end-to-end browser tests. |
npm run test:verification |
Root | Runs the Playwright full verification test suite. |
npm run docs:diagrams |
Root | Re-renders Mermaid documentation diagrams to static media. |
Fixify maintains rigorous test coverage spanning all architectural boundaries:
- Backend Testing with Vitest: Over 27 test suites in
server/test/verifying atomic counters, duplicate ticket prevention (BR-3), auto-assignment workloads (BR-4), closure requirements (BR-8), immutable audit logs, rate-limiting, and CORS policies. - In-Memory Replica Sets: Integration tests run with
mongodb-memory-serverconfigured with multi-document transaction replica sets, avoiding external database dependencies during CI/CD. - End-to-End Testing with Playwright: Browser tests in
e2e/validate complete user journeys including QR scan navigation, complaint submission, assistant review, and email verification.
To run tests:
# Run unit and integration tests
npm test
# Run browser E2E tests
npm run test:e2e- MongoDB Replica Set Requirement: Fixify uses multi-document ACID transactions for ticket assignment, inventory decrementing, and staff provisioning. Local MongoDB instances must be initiated as a replica set (
--replSet rs0). - Free Cloud Tier Behavior: When deployed on Render's free tier, the backend sleeps after inactivity and may require 45–60 seconds to wake on initial access. The Cloudflare edge worker catches waking responses and instructs clients to retry.
- Persistent Media Storage: Free cloud compute disks are ephemeral. Media attachments in production are uploaded to Cloudinary, ensuring persistence across server restarts.
- Domain Gating: When
NODE_ENV=production,ALLOWED_EMAIL_DOMAINSstrictly rejects public email providers (e.g.gmail.com,yahoo.com), ensuring only validated institutional accounts can authenticate.
Contributions and issue reports are welcome.
- Fork the repository and create a feature branch (
git checkout -b feature/improvement). - Adhere to existing code conventions and formatting standards (
npm run lint). - Ensure all tests and TypeScript compiler checks pass (
npm run typecheck && npm test). - Update documentation in
docs/andREADME.mdif workflows or configuration parameters are modified. - Submit a pull request detailing the problem and proposed implementation.
Fixify was developed as a software engineering capstone project by :
| Team Member | Details | Focus Area |
|---|---|---|
| Ashutosh Sanjay More | B.Tech -IT, PCCoE | Backend architecture, ticket state machine, 2D lab floorplans, security & deployment |
| Aniket Ashokrao Gawande | B.Tech -IT, PCCoE | Database modeling, asset management & data integrity |
| Atharv Sampat Shinde | B.Tech -IT, PCCoE | Frontend architecture, real-time UI |
This project is licensed under the MIT License.