# SupportHub — Master Architecture & Implementation Guide

**System:** AI-First Customer Support + Ticket Management + Problem Resolution + Support Orchestration Platform
**Status:** Blueprint / pre-implementation
**Scope:** This guide consolidates the full product and engineering specification into a build-ready reference.

---

## How this guide is organized

| # | Document | Covers |
|---|----------|--------|
| 01 | [Product Vision & Principles](./01-product-vision-and-principles.md) | Core idea, example flow, system ownership boundaries, business model, UX principles, engineering rules, landing page |
| 02 | [Integration & Security](./02-integration-and-security.md) | Product integration model, credentials, service-to-service auth, request contracts, RBAC boundary, secrets |
| 03 | [AI Support Architecture](./03-ai-support-architecture.md) | AI-first flow, knowledge system, RAG, diagnosis, tools, runbooks, guided UX, verification, AI safety |
| 04 | [Ticketing & Problem Management](./04-ticketing-and-problem-management.md) | Ticket lifecycle, problem entity, investigation, root cause, solution, verification, resolution, messages, attachments |
| 05 | [Orchestration, SLA & Escalation](./05-orchestration-sla-escalation.md) | Orchestration engine, dynamic hierarchy, capability matching, assignment, SLA, escalation |
| 06 | [Database Schema](./06-database-schema.md) | Full entity catalog, field-level detail, relationships |
| 07 | [Backend Architecture](./07-backend-architecture.md) | Tech stack, module structure, request flow, events, jobs, audit |
| 08 | [Frontend Architecture](./08-frontend-architecture.md) | Customer, agent, admin frontends; real-time UX |
| 09 | [Testing, Observability & CI/CD](./09-testing-observability-cicd.md) | Test strategy, critical E2E flows, logging/metrics, Jenkins pipeline |
| 10 | [Implementation Roadmap](./10-implementation-roadmap.md) | 11-phase delivery plan, success criteria, open business decisions |
| 11 | [Architect's Additions: Gaps & Recommendations](./11-architect-additions-gaps-and-recommendations.md) | Production concerns not in the original spec — idempotency, webhooks, RLS, prompt injection, AI cost governance, CSAT, data retention, and more |

---

## One-paragraph summary

SupportHub sits behind any number of existing SaaS products and never owns identity, tenancy, product access, subscriptions, or RBAC — that authority stays with the existing SaaS. When a customer reports a problem from inside a product, SupportHub creates a durable ticket immediately, then routes the problem to a **product-aware AI Support Agent** that classifies it, retrieves scoped knowledge (RAG), diagnoses a likely cause with a confidence score, and either executes approved tools or guides the customer through a controlled runbook. Resolution is only recorded after **actual verification**, not a customer's say-so. When AI can't safely or confidently resolve the problem, it escalates — with full context — into a **configuration-driven orchestration engine** that picks the right dynamic support hierarchy node, matches capability before availability, assigns an agent through a pluggable concurrency-safe strategy, and enforces SLA policies that respect business calendars and pause/resume correctly. Everything (assignment, escalation, SLA, knowledge, resolution) is audit-logged and reportable.

## Core end-to-end flow

```
Customer → Product App → Support Center → SupportHub API
    → Ticket/Case created (status: NEW)
    → AI understands problem → classifies → retrieves knowledge
    → Diagnosis (with confidence) → Direct solution OR guided runbook
    → Customer action → System verification
         ├─ Verified solved   → AI_RESOLVED → (confirm) → RESOLVED → CLOSED
         └─ Not solved/low confidence → HUMAN_ESCALATION
                → Orchestration Engine (capability → hierarchy → team)
                → Assignment (strategy-based, concurrency-safe)
                → SLA applied (business-calendar aware)
                → Investigation → Root Cause → Solution → Verification
                → Resolution → Customer confirmation → CLOSED
```

## Non-negotiable boundaries (repeated throughout this guide because they matter most)

- **SaaS is the only source of truth** for users, tenants, products, product access, subscriptions, permissions, RBAC, and authentication. SupportHub stores only external references (`externalUserId`, `externalTenantId`, `externalProductId`).
- **SupportHub is the only source of truth** for tickets, problems, support org structure, routing/assignment, SLA, escalation, investigation/root cause/solution/verification/resolution, knowledge, and support audit trail.
- **AI recommends; deterministic policy decides.** The LLM never gets unrestricted backend access, never invents troubleshooting steps or product behavior, and never executes a high-risk action without a permission and policy check.
- **Nothing is hardcoded** that the spec calls out as configurable: support hierarchy, SLA values, escalation paths, assignment strategy, routing rules. All of it is admin-configurable data, not code.
- **Verification is evidence-based**, not customer-confirmation-based, wherever a system signal is available.

## Reading order recommendation

If you're briefing an engineering team from scratch, read in document order (01 → 10). If you're validating a specific subsystem, jump directly to the relevant document — each is self-contained with cross-references back to this index.