docs: update README with architecture, environments, commands, and project structure

2026-08-20 16:21:21 +05:30
parent f4c71d6ef3
commit 4ffdc3b48b
1 changed files with 193 additions and 0 deletions
@@ -0,0 +1,193 @@
+# 🎧 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.