Technical Reference

Version: 1.0.1

Architecture, API routes, database schema, and storage configuration for developers and system administrators.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        Browser                               │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │ AuthContext │  │ Page UI      │  │ Supabase Client     │ │
│  │ (JWT cookie)│  │ (permissions)│  │ (direct CRUD)       │ │
│  └──────┬──────┘  └──────────────┘  └──────────┬──────────┘ │
└─────────┼──────────────────────────────────────┼────────────┘
          │                                      │
          ▼                                      ▼
┌─────────────────────┐              ┌───────────────────────┐
│  Next.js API Routes │              │  Supabase             │
│  /api/auth/*        │              │  ├── PostgreSQL       │
│  /api/users/*       │              │  └── Storage buckets  │
│  /api/business-*    │              └───────────────────────┘
│  /api/complaints/*  │
└─────────────────────┘

Key design decisions:

• Authentication — Custom JWT session in httpOnly cookie (courier_session), not Supabase Auth
• Authorization — Role + per-page permissions checked in UI; admin-only routes on API
• Data access — Complaints, workflows, types read/written via Supabase anon client from browser
• Uploads — Server-side API routes upload to Supabase Storage

Tech Stack

Project Structure

Complaint-Managment-System/
├── app/                        # Next.js App Router pages & API
│   ├── api/                    # Server API routes
│   ├── complaints/             # Complaints pages
│   ├── dashboard/              # Redirects to /
│   ├── login/                  # Login page
│   ├── profile/                # User profile & business branding
│   ├── resolution-workflow/    # Resolution workflow page
│   └── settings/               # Admin settings pages
├── components/                 # React components
│   ├── complaints/             # Print view, etc.
│   └── dashboard/              # Dashboard home
├── context/                    # AuthContext provider
├── database/                   # SQL schema file
├── Documentation/              # This documentation
├── lib/                        # Shared utilities & data access
├── public/                     # Static assets (sw.js)
└── middleware.ts               # Auth middleware

API Routes

Authentication

Session cookie: courier_session — httpOnly, 7-day expiry, secure in production.

Users (Admin Only for Write)

Create user body:

{
  "name": "Agent Name",
  "email": "agent@company.com",
  "password": "securepass",
  "role": "editor",
  "permissions": [
    { "page_key": "complaints", "can_view": true, "can_edit": true, "can_delete": false }
  ]
}

Business Profile

File Uploads

Database Schema

Run database/cms-schema.sql once in Supabase SQL Editor.

Tables

app_users

user_permissions

complaints

complaint_images

resolution_workflows

complaint_types

app_business_profile

Relationships

app_users ──1:*── user_permissions
app_users ──0:1── app_business_profile (updated_by)
complaints ──1:*── complaint_images
complaints ──1:*── resolution_workflows
complaint_types (standalone lookup)

Row Level Security (RLS)

All data tables have permissive anon policies (full CRUD for anon role). Application-level security is enforced via JWT session and UI permissions, not Supabase Auth RLS.

Supabase Storage Buckets

Environment Variables

Auth Flow (Technical)

1. POST /api/auth/login { email, password }
2. Server: SELECT from app_users WHERE email = ?
3. bcrypt.compare(password, password_hash)
4. jose.SignJWT({ userId, email, role }) → courier_session cookie
5. Client: AuthContext.refreshSession() → GET /api/auth/me
6. Response: { user, permissions[] }
7. UI: canView/canEdit/canDelete helpers available globally
8. Middleware: verify JWT on each request (except /login, /api/auth/*)

Key Library Files

Complaint ID Generation

Format: CMP-##### (zero-padded 5 digits)

Algorithm (lib/complaints.ts):

1. Fetch highest existing complaint_id matching CMP-%
2. Parse numeric suffix
3. Increment by 1
4. Pad to 5 digits

Example sequence: CMP-00001, CMP-00002, … CMP-00100

Theme System

ThemeInit component applies dark class before first paint to prevent flash.

Production Integrations

When NODE_ENV === 'production':

• Vercel Speed Insights — performance monitoring
• Vercel Analytics — usage analytics

Both are loaded in app/layout.tsx.

Service Worker

public/sw.js is a minimal stub that prevents 404 errors from browser PWA detection. The app does not use offline caching.

Error Handling

• app/error.tsx — Client-side error boundary with "Try again" button
• API routes return JSON { error: "message" } with appropriate HTTP status codes
• Page components show inline error banners with Retry for data fetch failures