🚀 CaseTrack - Smart Complaint Management System

CaseTrack is a full-stack, enterprise-grade Smart Complaint Management System designed to streamline, categorize, and track grievances within organizations. Featuring role-based dashboards, automated AI-powered complaint classification, email updates, and real-time in-app notifications, CaseTrack turns manual ticket resolution into an automated, transparent, and structured workflow.

---

🏗️ System Architecture & Workflow

CaseTrack implements a highly secure, role-restricted dashboard for three distinct types of users:

1. Users (Complainants): Can register, log in, submit complaints with text descriptions, and track the status/resolution of their tickets in real time.
2. Staff (Resolvers): Assigned to specific departments. They can view tickets assigned to them, manage ticket states (in-progress, resolved, rejected), and write resolution notes.
3. Admins (Managers): Complete overview of all complaints. Admins assign pending tickets to appropriate staff members, manage system-wide users, create new admin accounts, and view global analytics.

🔄 Complaint Resolution Pipeline (Workflow)

graph TD
User([User]) -->|Submits Complaint| App[React Frontend]
App -->|POST /api/complaints| Server[Express Backend]
Server -->|Processes with| AI[Gemini API / Keyword Fallback]
AI -->|Determines Category, Priority, Dept| DB[(PostgreSQL Database)]
DB -->|Triggers Alert| Admin([Admin Dashboard])
Admin -->|Assigns Staff Member| Staff([Staff Resolver])
Staff -->|Updates Status / Adds Note| DB
DB -->|Triggers Email Notification| Nodemailer[Nodemailer Email Service]
Nodemailer -->|Status Update Alert| User
DB -->|Updates In-App Feed| Bell[Notification Bell]

Loading

🗄️ Database Schema ERD

erDiagram
USERS {
SERIAL id PK
TEXT name
TEXT email UK
TEXT password
TEXT role "user | staff | admin"
TEXT department
BOOLEAN isActive
TIMESTAMP lastLogin
TIMESTAMP createdAt
TIMESTAMP updatedAt
}
COMPLAINTS {
SERIAL id PK
TEXT title
TEXT description
TEXT category
TEXT priority
TEXT status "pending | in-progress | resolved | rejected"
TEXT aiCategory
TEXT aiPriority
TEXT aiSuggestedDepartment
TEXT aiSentiment
TEXT aiSummary
INTEGER submittedBy FK
INTEGER assignedTo FK
TEXT resolutionNote
TIMESTAMP createdAt
TIMESTAMP updatedAt
}
NOTIFICATIONS {
SERIAL id PK
INTEGER recipient FK
TEXT title
TEXT message
TEXT type
BOOLEAN isRead
INTEGER relatedComplaint FK
TIMESTAMP createdAt
}
USERS ||--o{ COMPLAINTS : "submits"
USERS ||--o{ COMPLAINTS : "is assigned to"
USERS ||--o{ NOTIFICATIONS : "receives"
COMPLAINTS ||--o{ NOTIFICATIONS : "triggers"

Loading

---

🛠️ Technology Stack

Backend

• Core Engine: Node.js, Express.js
• Database: PostgreSQL (using pg pool, automatic schema setup and key camelization on boot)
• Authentication & Security: JSON Web Tokens (JWT), BcryptJS for password hashing, Helmet for secure HTTP headers, Express-Rate-Limit for API rate limiting
• AI Core: Google Gemini API (@google/generative-ai) with a robust keyword-based local classifier fallback to ensure 100% uptime even if API quotas are exhausted
• Notification Services: Nodemailer (SMTP integration for automated confirmation, assignment, and resolution alerts)

Frontend

• Framework & Build Tool: React 19, Vite, ES6+ JavaScript
• Styling Engine: Tailwind CSS v4 (offering high-speed layouts and clean, modern themes)
• Navigation: React Router DOM (v7)
• Analytics & Data Vis: Recharts (rendering dynamic charts for complaint categories, priority shares, resolution rates)
• User Alerts: React Hot Toast (beautiful responsive notifications)
• HTTP Client: Axios (configured with global interceptors for JWT injection and automated 401 session logout)

---

📂 Project Directory Structure

CaseTrack/
├── backend/
│ ├── config/
│ │ └── db.js # PostgreSQL config, table schema initialization & key camelization
│ ├── controllers/
│ │ ├── authController.js # Auth routines: Login, register, profile, user managers
│ │ ├── complaintController.js # Complaint management: submit, assign, status update, delete
│ │ ├── dashboardController.js # Aggregations for Recharts visualizations
│ │ └── notificationController.js # Read/delete operations for user alert feed
│ ├── middleware/
│ │ └── auth.js # JWT verification & role protection middleware
│ ├── models/ # Deprecated (moved to database configuration setup)
│ ├── routes/
│ │ ├── authRoutes.js
│ │ ├── complaintRoutes.js
│ │ ├── dashboardRoutes.js
│ │ └── notificationRoutes.js
│ ├── utils/
│ │ ├── emailService.js # SMTP config & html layout handlers
│ │ └── geminiAI.js # Gemini API interface with local fallback rules
│ ├── .env.example # Template configuration for environment settings
│ ├── package.json
│ └── server.js # Entry point: Server settings, limits, helmet & health check
├── frontend/
│ ├── public/ # Static client resources
│ ├── src/
│ │ ├── components/
│ │ │ ├── ComplaintForm.jsx # Standardized user form for submitting cases
│ │ │ ├── Navbar.jsx # Dynamic role-responsive header navigation bar
│ │ │ ├── NotificationBell.jsx # Sidebar dropdown with current notifications
│ │ │ └── ProtectedRoute.jsx # Guard routing wrapper
│ │ ├── context/
│ │ │ └── AuthContext.jsx # Top-level global auth session state provider
│ │ ├── pages/
│ │ │ ├── AdminDashboard.jsx # Admin control board, assignments panel, user controls, charts
│ │ │ ├── Login.jsx
│ │ │ ├── Register.jsx
│ │ │ ├── StaffPanel.jsx # Staff resolver terminal
│ │ │ ├── UserDashboard.jsx # Complainant portal to review status
│ │ │ └── NotFound.jsx # Fallback 404 page
│ │ ├── utils/
│ │ │ └── api.js # Axios client setup (interceptor-wrapped)
│ │ ├── App.jsx # Application route mappings & styles wrapper
│ │ └── index.css # Tailwind v4 import & global styles
│ ├── package.json
│ └── vite.config.js
└── README.md # Project documentation

---

🚀 Installation & Local Setup

Follow these steps to set up CaseTrack on your local environment:

Prerequisites

• Node.js (v18.x or higher)
• PostgreSQL instance (local server or cloud host like Neon / Supabase)
• Google Gemini API Key (optional, fallback is automatically used if absent)
• SMTP Server / Credentials (e.g., Gmail App Password for email dispatches)

Step 1: Clone the Repository

git clone https://github.com/your-username/CaseTrack.git
cd CaseTrack

Step 2: Configure the Backend Environment

1. Navigate to the backend folder:

   cd backend

2. Copy the example environment template:

   cp .env.example .env

3. Open .env and fill in your details:

   PORT=5000DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname>?sslmode=requireJWT_SECRET=your_jwt_secret_hereGEMINI_API_KEY=your_gemini_api_key_hereEMAIL_USER=your_email_user@gmail.comEMAIL_PASS=your_gmail_app_passwordNODE_ENV=development

Step 3: Run the Backend

1. Install backend dependencies:

   npm install

2. Start the development server (runs auto-watch modes):

   npm run dev

   Note: Upon successful connection, the tables will be created automatically in your PostgreSQL database.

Step 4: Run the Frontend

1. Open a new terminal window and navigate to the frontend folder:

   cd frontend

2. Install frontend dependencies:

   npm install

3. Start the Vite development server:

   npm run dev

4. Open http://localhost:5173 in your web browser.

---

📡 API Endpoint Reference

Authentication (/api/auth)

HTTP Method	Endpoint	Access Level	Description
POST	/api/auth/register	Public	Register a new User account
POST	/api/auth/login	Public	Authenticate user & return JWT token
GET	/api/auth/profile	Authenticated	Fetch active user credentials
PUT	/api/auth/profile	Authenticated	Edit user personal information
GET	/api/auth/users	Admin	Retrieve all registered users
PUT	/api/auth/users/:id	Admin	Edit roles, activation state or details of a user
GET	/api/auth/staff	Admin	Retrieve all members with 'staff' role
POST	/api/auth/create-admin	Admin (only)	Provision a new Admin account

Complaints (/api/complaints)

HTTP Method	Endpoint	Access Level	Description
POST	/api/complaints	User	Submit a new complaint (auto-analyzed)
GET	/api/complaints/my	User	Fetch complaints submitted by active user
GET	/api/complaints	Admin, Staff	Retrieve all system complaints (Staff: only assigned)
GET	/api/complaints/:id	Authenticated	Retrieve specific complaint details
PUT	/api/complaints/:id/status	Admin, Staff	Update status & add resolution notes
PUT	/api/complaints/:id/assign	Admin	Assign a complaint to a specific Staff resolver
DELETE	/api/complaints/:id	Admin	Permanently delete a complaint

Notifications (/api/notifications)

HTTP Method	Endpoint	Access Level	Description
GET	/api/notifications	Authenticated	Retrieve notification feed for active user
PUT	/api/notifications/read-all	Authenticated	Mark all notifications as read
PUT	/api/notifications/:id/read	Authenticated	Mark a specific notification as read
DELETE	/api/notifications	Authenticated	Wipe notification feed completely
DELETE	/api/notifications/:id	Authenticated	Delete a single notification from feed

Dashboard Analytics (/api/dashboard)

HTTP Method	Endpoint	Access Level	Description
GET	/api/dashboard/stats	Authenticated	Returns analytics & aggregation datasets

---

🔒 Security Best Practices Implemented

• XSS & HTTP Header Protections: Configured through Helmet middleware.
• DDoS/Brute-Force Shielding: Standard endpoints restricted to 200 requests/15 mins; Authentication endpoints capped at 50 requests/15 mins.
• SQL Injection Prevention: Parameterized SQL queries utilized across all database operations.
• Access Route Guards: Custom Router wrapper (ProtectedRoute) on client and middleware check validation (protect, authorize) on the API layer.

---

📄 License

This project is licensed under the ISC License. Feel free to fork, modify, and distribute as needed.