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:

```ts
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](./07-backend-architecture.md#module-internal-structure).