# 🎧 SupportHub Web (`supporthub-web`)

Enterprise-grade Next.js App Router frontend for **SupportHub** — an omni-channel customer support, automated ticketing, SLA tracking, and problem management platform. Built to integrate seamlessly with parent SaaS platforms via API.

---

## 🌟 Architecture & SaaS Integration Model

SupportHub is designed as a modular, API-first support platform:

- **SaaS Identity & Entitlements**: User authentication, product access, purchased features, and user roles are delegated from your primary SaaS host application via secure tokens (`X-SaaS-User-Token`).
- **Knowledge-First Agent Workflow**: When a ticket is received from the SaaS application, support agents perform an initial analysis backed by automated Knowledge Base suggestions and scenario resolution protocols before escalating or closing tickets.
- **Role-Based Portals**:
  1. **`(public)`**: Public Help Center, KB search, and live System Operational Status.
  2. **`(customer)`**: Self-service support portal for end-users to log tickets, chat with AI Assistant, and track resolutions.
  3. **`(support)`**: High-velocity Agent Workspace with Ticket Workbench, Queue Dispatch, SLA monitoring, and Escalation Matrix.
  4. **`(admin)`**: Executive Platform Administration for managing Products, Teams, Agents, Routing Engine Rules, Assignment Policies, SLA Policies, and Audit Logs.

---

## 📂 Project Directory Structure

```text
supporthub-web/
├── public/
│   ├── favicon.ico
│   ├── manifest.webmanifest
│   ├── icons/
│   └── images/
│
├── src/
│   ├── app/
│   │   ├── (public)/
│   │   │   ├── page.tsx               # Public Landing
│   │   │   ├── help/page.tsx          # Help Center / KB
│   │   │   └── status/page.tsx        # System Status
│   │   │
│   │   ├── (customer)/
│   │   │   ├── layout.tsx
│   │   │   └── support/
│   │   │       ├── page.tsx           # Customer Support Overview
│   │   │       ├── ai/page.tsx        # AI Assistant Chat
│   │   │       ├── tickets/           # Customer Ticket List & Detail
│   │   │       └── new/page.tsx       # Submit Ticket
│   │   │
│   │   ├── (support)/
│   │   │   ├── layout.tsx
│   │   │   └── support/
│   │   │       ├── dashboard/page.tsx # Support Operations Dashboard
│   │   │       ├── agent-tickets/     # Ticket Workbench & Detail
│   │   │       ├── problems/page.tsx  # Root Cause & Problem Management
│   │   │       ├── queues/page.tsx    # Queue Dispatch
│   │   │       ├── sla/page.tsx       # SLA Breach Monitor
│   │   │       └── escalations/      # Escalation Matrix
│   │   │
│   │   ├── (admin)/
│   │   │   ├── layout.tsx
│   │   │   └── admin/
│   │   │       ├── dashboard/page.tsx # Admin Executive Dashboard
│   │   │       ├── products/page.tsx  # Products & Services Catalog
│   │   │       ├── teams/page.tsx     # Support Teams
│   │   │       ├── agents/page.tsx    # Agent Roster & Roles
│   │   │       ├── hierarchy/page.tsx # Org Hierarchy
│   │   │       ├── routing/page.tsx   # Automated Ticket Routing Rules
│   │   │       ├── assignments/       # Auto-Assignment Engine
│   │   │       ├── sla-policies/      # SLA Policy Builder
│   │   │       ├── escalation-policies/ # Escalation Policy Builder
│   │   │       ├── knowledge/page.tsx # KB Governance
│   │   │       ├── reports/page.tsx   # Analytics Reports
│   │   │       ├── audit/page.tsx     # Compliance Audit Logs
│   │   │       └── settings/page.tsx  # Platform Settings
│   │   │
│   │   ├── error.tsx
│   │   ├── global-error.tsx
│   │   ├── loading.tsx
│   │   └── not-found.tsx
│   │
│   ├── features/                      # Domain Modules (ai-support, tickets, problems, orchestration, etc.)
│   ├── components/                    # UI Design System (ui, forms, tables, charts, navigation, feedback)
│   ├── lib/                           # Core utilities (api, auth, query, websocket, env, utils)
│   ├── hooks/
│   ├── stores/
│   ├── providers/
│   ├── types/
│   ├── constants/
│   ├── theme/
│   └── styles/
│
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── Dockerfile
├── .dockerignore
├── .env.example
├── .env.template
├── .env.development
├── .env.test
├── .env.production
├── .gitignore
├── eslint.config.mjs
├── prettier.config.mjs
├── vitest.config.ts
├── playwright.config.ts
├── next.config.mjs
├── middleware.ts
├── tsconfig.json
└── package.json
```

---

## ⚙️ Environment Configurations

SupportHub Web comes pre-configured with distinct environment presets:

| Environment | Web App URL | Backend API URL | Config File |
| :--- | :--- | :--- | :--- |
| **Development** | `https://support-dev.maskantech.in` | `https://supportdev-api.maskantech.in/api/v1` | `.env.development` |
| **Test** | `https://support-test.maskantech.in` | `https://supportdtest-api.maskantech.in/api/v1` | `.env.test` |
| **Production** | `https://support.maskantech.in` | `https://support-api.maskantech.in/api/v1` | `.env.production` |

---

## 🚀 Getting Started & CLI Scripts

### 1. Install Dependencies
```bash
npm install
```

### 2. Development Server
Run local development server on `http://localhost:3000`:
```bash
npm run dev
```

### 3. Environment-Specific Builds
Build the optimized application bundle targeting specific environment presets:
```bash
# Build for Development Environment
npm run build:dev

# Build for Test Environment
npm run build:test

# Build for Production Environment
npm run build:prod
```

### 4. Run Production Server
Serve the compiled production build on `http://localhost:3000`:
```bash
npm run start
```

### 5. Testing & Code Quality
```bash
# Run Unit & Integration Tests (Vitest)
npm test

# Run Watch Mode
npm run test:watch

# Run End-to-End Tests (Playwright)
npm run test:e2e

# Run Type Checker
npm run typecheck

# Run Linter
npm run lint
```

---

## 🐳 Docker Container Deployment

Build and run SupportHub Web inside a lightweight, multi-stage Docker container:

```bash
# 1. Build Docker Image
docker build -t supporthub-web:latest .

# 2. Run Container using Production Environment Settings
docker run -d -p 3000:3000 --env-file .env.production --name supporthub-web supporthub-web:latest
```

---

## 📄 License
Internal Proprietary Software — SupportHub Team.