support_backend/docs/01-product-vision-and-principles.md

# 01 — Product Vision & Principles

## 1. What SupportHub is (and isn't)

SupportHub is an **AI-First Customer Support + Ticket Management + Problem Resolution + Support Orchestration Platform**. It is not a basic helpdesk, not a generic chatbot wrapper, and not a second identity/RBAC system.

It integrates with one or more existing SaaS platforms that already own:

- Users, tenants/organizations
- Products, product registration, product access
- Subscriptions/purchases, permissions, RBAC
- Authentication
- User↔tenant and user↔product relationships

SupportHub never rebuilds any of the above. It integrates with the SaaS through secure APIs and per-product integration credentials.

## 2. Core business idea

A customer using any registered SaaS product reports a problem. SupportHub attempts to resolve it with a **product-aware AI Support Agent** before any human is involved. The agent:

1. Understands the customer's problem
2. Identifies the affected product
3. Identifies the feature/module
4. Classifies the problem
5. Searches relevant product knowledge
6. Searches known issues and failure cases
7. Diagnoses the likely cause
8. Provides product-specific guidance
9. Executes approved tools/actions when appropriate
10. Asks the customer to follow instructions when required
11. Verifies whether the problem was actually solved
12. Marks the case AI-resolved on success
13. Escalates to human support when it cannot safely or confidently solve it

**The customer never needs to understand the internal support hierarchy** — they just report a problem and see progress toward a resolution.

## 3. Reference example: DocuQube

Used throughout this guide as the canonical example product.

**Scenario:** Customer uploads a PDF to DocuQube. PDF upload succeeds, OCR succeeds, HTML conversion fails. Customer clicks Help/Support inside DocuQube.

```
Ticket:    DQB-2026-00567
Product:   DocuQube
Customer:  Tenant/User from SaaS (via external reference)
Problem:   PDF to HTML conversion failed
Status:    AI_ANALYZING
```

This ticket is created **immediately**, at the start of the journey — not after AI gives up. See [04 — Ticketing & Problem Management](./04-ticketing-and-problem-management.md).

## 4. System ownership boundary

| Owned by existing SaaS (authoritative) | Owned by SupportHub (authoritative) |
|---|---|
| User identity | Support sessions |
| Tenant identity | Tickets |
| Product identity | Problems |
| Product access / subscription | Support teams, agents, skills/capabilities |
| Product permissions / RBAC | Support hierarchy |
| Authentication | Routing, assignment |
| | SLA, escalation |
| | Investigation, root cause, solution, verification, resolution |
| | Support messages, attachments |
| | Knowledge, runbooks |
| | Support audit, support analytics |

SupportHub stores `externalUserId`, `externalTenantId`, `externalProductId` as **references only** — it never becomes a second SaaS-style identity/tenant/RBAC platform.

## 5. Business model

| SaaS decides | SupportHub decides |
|---|---|
| Who owns the product | How support is delivered |
| Which tenant has access | How problems are classified |
| Which features are purchased | How AI handles them |
| Which permissions exist | Which support team handles them |
| | How tickets are assigned |
| | How SLA is enforced |
| | When escalation happens |
| | How resolution is recorded |

Support is **enabled by default** for any product registered in the SaaS — treated as a platform capability of the product, not an opt-in the customer must separately configure, unless/until premium support tiers are introduced as a business rule. The customer never creates a separate SupportHub account.

## 6. UX principle by persona

| Persona | Experience should be |
|---|---|
| **Customer** | Simple, guided, trustworthy, product-aware. Never sees internal hierarchy, assignment algorithms, agent workload, escalation rules, internal notes, or routing logic. |
| **Agent** | Information-dense, fast, operational, context-rich. Continues from AI context — never restarts diagnosis from zero. |
| **Admin** | Configurable, visual, rule-driven, auditable. |

### Customer journey (happy path)
```
Problem → AI help → Guided solution → Verification → Resolved
```

### Customer journey (escalation path)
```
Problem → AI attempts → Escalation → Human Support → Resolution
```

### Critical UI rule
The customer should **not** land on a generic "ticket system." The first thing they see is a **Support Center** with "How can we help you?" — they describe a problem, and the system absorbs all the complexity behind that single interaction.

## 7. Landing page positioning (if a public SupportHub site is needed)

- Positioning: *"AI-first support and intelligent resolution platform."*
- Hero: *"Resolve customer problems before they become support tickets."*
- Explain: product-aware AI, guided troubleshooting, human support orchestration, capability-based assignment, SLA, escalation, SaaS integration.
- **Do not** position this as a basic helpdesk.

## 8. Engineering rules (non-negotiable)

**Never:**
- Hardcode support hierarchy, SLA values, escalation paths, or assignment decisions
- Duplicate SaaS RBAC inside SupportHub
- Put Prisma queries in controllers, or business logic in routes
- Allow the AI unrestricted backend access
- Store large files in PostgreSQL
- Use in-memory SLA timers (e.g., `setTimeout`) for production enforcement
- Create giant global services, circular module dependencies, or deep cross-module imports

**Always:**
- Use configuration-driven logic for anything the business can change without a deploy
- Keep module boundaries clear, exposed only via each module's public `index.ts`
- Validate all input; audit all important operations
- Test concurrent operations (assignment races, idempotent job handlers)
- Preserve full AI history and full resolution history
- Keep problem and ticket as separate, related entities
- Verify actual resolution with evidence, not customer assertion, wherever possible
- Keep the SaaS as the sole identity/access authority

## 9. Final architectural principle

```
PROBLEM → UNDERSTAND → KNOWLEDGE → DIAGNOSE → GUIDE → VERIFY → RESOLVE

If AI cannot resolve:
PROBLEM → HUMAN SUPPORT → ORCHESTRATE → ASSIGN → SLA
        → INVESTIGATE → ROOT CAUSE → SOLUTION → VERIFY → RESOLVE → CLOSE
```

SupportHub is: **AI-first, problem-centric, configuration-driven, product-aware, human-assisted, SLA-aware, escalation-aware, multi-product, API-integrated, enterprise-ready.**