Getting Started

Version: 1.0.1

Prerequisites

• Node.js 18 or higher
• A Supabase project (free tier works)

Installation

1. Clone and install dependencies

git clone <your-repo-url>
cd Complaint-Managment-System
npm install

2. Configure environment variables

Copy the example file and edit it:

cp .env.example .env.local

Never commit .env or .env.local to version control.

3. Set up the database

1. Open your Supabase project → SQL Editor
2. Open the file database/cms-schema.sql from this project
3. Paste the entire file and click Run

This creates all tables, permissions, default admin user, complaint types, and optional sample complaints.

4. Configure Supabase Storage (for uploads)

Create two storage buckets in Supabase:

Set bucket policies to allow public read access for image URLs (or configure as needed for your deployment).

5. Start the development server

npm run dev

Open http://localhost:3000 in your browser.

First Login

Use the default admin credentials created by the database schema:

• Email: admin@admin.com
• Password: admin123

After login you land on the Dashboard. The sidebar shows all menu items for admin users.

Try Demo Mode (no database)

If you want to explore the product without Supabase, use the standalone demo:

cd demo-mode
npm install
npm run dev

Open the Demo Mode login screen and choose an account card. Sample complaints and workflows are already filled in. Demo Mode is deployed separately from the production app.

Available Scripts

Deployment (Vercel)

1. Push the project to GitHub
2. Import the repository in Vercel
3. Add all environment variables from .env.example
4. Run database/cms-schema.sql on your production Supabase project
5. Deploy

Pre-deploy checklist:

• Strong JWT_SECRET set
• cms-schema.sql applied on Supabase
• npm run build passes locally
• Default admin password changed
• Storage buckets created

Typical Workflow (Day-to-Day Use)

1. Login with your assigned credentials
2. Check the Dashboard for open complaints and priorities
3. Go to Complaints to view, add, or update complaints
4. Attach images as evidence when creating or editing a complaint
5. Use Resolution Workflow (or the Workflow button on a complaint row) to record how a complaint was resolved
6. Copy a customer message from the complaint actions menu to send to the customer
7. Print a complaint summary from the detail view when needed
8. Admins manage users, permissions, complaint types, and business branding from Settings

Sidebar Basics

• Click the chevron at the top of the sidebar to collapse/expand it
• Collapsed mode shows icons only; hover for flyout submenus
• Settings submenu includes Profile, Users and Access (admin), Complaint Type, theme toggle, and Sign out
• The sidebar footer shows the app version (e.g. v1.0.1)
• Your sidebar state (collapsed/expanded) and theme preference are saved in the browser

App version & changelog

See App Version Details for the current version table and bump checklist.

How to bump a release

1. Decide the new version (e.g. 1.1.0) and today’s date.
2. Update APP_VERSION / APP_VERSION_DATE in both appConfig files.
3. Set the same version in both package.json files.
4. Update APP-VERSION.md and add a section at the top of CHANGELOG.md.
5. Deploy — the sidebar will show v{new version}.

Page guides

Step-by-step docs for every screen (with screenshots):

• Login
• Dashboard
• Complaints
• Complaint Print
• Resolution Workflow
• Profile
• Users and Access
• Complaint Type

Full index: README · index.md.