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.

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.