support_backend/docs/05-orchestration-sla-escalation.md

05 — Orchestration, SLA & Escalation

This is the central decision-making subsystem for human support. It is entirely configuration-driven — no hardcoded L1 → L2 → L3 → L4 levels anywhere.

1. Orchestration engine

Determines, for every escalated ticket: what problem is this, what capability is needed, which support path, which team, which agents, which assignment strategy, which SLA, which escalation policy.

Product → Problem Type → Category → Priority → Severity
        → Required Capability → Business Rules
        → Dynamic Support Hierarchy → Team → Eligible Agents
        → Assignment Strategy → SLA → Escalation Policy

2. Dynamic support hierarchy

Administrators configure arbitrary support nodes — different products can have completely different hierarchies, and changing one must never require a code change.

Example:

DocuQube Support
├── General Support
├── Document Processing
│   ├── OCR Specialist
│   └── Conversion Specialist
└── Engineering
    ├── Backend
    └── Infrastructure

A hierarchy node's fields:

interface HierarchyNode {
  id: string;
  name: string;
  parentId?: string;
  order: number;
  team: string;
  skills: string[];              // capability tags this node covers
  productScope: string[];
  categoryScope: string[];
  priorityScope: string[];
  assignmentStrategy: AssignmentStrategy;
  slaPolicyId: string;
  escalationPolicyId: string;
  entryConditions: RuleExpression;
  exitConditions: RuleExpression;
  active: boolean;
}

3. Capability and skill matching

Capability is evaluated before availability. Example:

Rahul: DocuQube, PDF, Conversion
Aamir: Billing, Payments
Sahil: Infrastructure, DevOps

Problem: DocuQube PDF conversion failure → Eligible: Rahul

Only after the eligible set is computed does the system consider: active state, availability, working hours, current workload, team, hierarchy node.

4. Assignment engine

Must be pluggable. Supported strategies:

Strategy	Behavior
ROUND_ROBIN	Cycles through eligible agents only; must be concurrency-safe
LEAST_LOADED	Picks the eligible agent with lowest current workload
SKILL_BASED	Weighted match on skill depth, not just presence
MANUAL	Human picks the assignee
DIRECT	Explicit target (e.g. reassign to a named agent)
PRIORITY_BASED	Priority ticket preempts queue position

Round robin only operates over the eligible-agent set (post capability-match), and must be concurrency-safe — two tickets arriving simultaneously must never corrupt the round-robin cursor or double-assign. Use a database-level lock/transaction or an atomic Redis operation, not an in-memory counter.

Assignment history must be recorded for every assignment and reassignment (who, when, why, strategy used).

5. SLA engine

SLA policies are configuration, never a hardcoded number. Policies may depend on: product, category, problem type, priority, severity, support node, customer type, business calendar.

SLA types to support

• First response SLA
• Investigation SLA
• Resolution SLA
• Customer response SLA
• States: warning, pause, resume, breach, completion

Business-calendar awareness

Support business hours, weekends, holidays, time zones, and per-team schedules. Do not compute enterprise SLA as createdAt + N hours — that ignores calendars entirely and will silently violate real commitments.

SLA pause/resume

IN_PROGRESS → WAITING_FOR_CUSTOMER → SLA PAUSED
WAITING_FOR_CUSTOMER → IN_PROGRESS → SLA RESUMES

SLA calculations must be durable — never dependent on an in-memory timer that resets on a process restart. Use durable jobs (BullMQ) with persisted due-times recomputed against the business calendar, not setTimeout.

6. Escalation engine

Escalation is rule-driven, not if L1 then L2.

Example rule:

IF resolution SLA breached AND priority = critical
THEN move to configured escalation node, notify manager, create escalation event

Escalation triggers

• First response breach
• Resolution breach
• Investigation breach
• Inactivity
• Priority increase
• Customer escalation request
• Repeated reopen
• Manual escalation
• Product defect identified
• External dependency timeout
• Critical incident

All escalation events must be auditable.

7. End-to-end human support flow

Ticket → Orchestration → Capability → Support Hierarchy → Team
       → Eligible Agents → Assignment → SLA
       → Investigation → Root Cause → Solution → Verification
       → Resolution → Closure

Re-escalation when an agent can't solve it:

Current Support Node → Evaluate escalation rules → Target Support Node
                     → Target Team → Availability → Assignment → Continue SLA

8. Module implication

Because this subsystem contains genuine decision logic (not just CRUD), the orchestration module needs the extended internal structure — engine/, rules/, strategies/, calculators/ — in addition to the standard controller/service/repository layers. See 07 — Backend Architecture.