support_backend/docs/00-INDEX.md

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	Core idea, example flow, system ownership boundaries, business model, UX principles, engineering rules, landing page
02	Integration & Security	Product integration model, credentials, service-to-service auth, request contracts, RBAC boundary, secrets
03	AI Support Architecture	AI-first flow, knowledge system, RAG, diagnosis, tools, runbooks, guided UX, verification, AI safety
04	Ticketing & Problem Management	Ticket lifecycle, problem entity, investigation, root cause, solution, verification, resolution, messages, attachments
05	Orchestration, SLA & Escalation	Orchestration engine, dynamic hierarchy, capability matching, assignment, SLA, escalation
06	Database Schema	Full entity catalog, field-level detail, relationships
07	Backend Architecture	Tech stack, module structure, request flow, events, jobs, audit
08	Frontend Architecture	Customer, agent, admin frontends; real-time UX
09	Testing, Observability & CI/CD	Test strategy, critical E2E flows, logging/metrics, Jenkins pipeline
10	Implementation Roadmap	11-phase delivery plan, success criteria, open business decisions
11	Architect's Additions: Gaps & Recommendations	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.