PSA/ee/docs/plans/2026-02-03-sla-temporal-workflow-architecture/PRD.md

# PRD — SLA Temporal Workflow Architecture (CE/EE Split)

- Slug: `sla-temporal-workflow-architecture`
- Date: `2026-02-03`
- Status: Draft

## Summary

Move SLA time calculation and monitoring from the current pgboss-only polling approach to a dual-backend architecture where Enterprise Edition (EE) uses Temporal workflows for durable, event-driven SLA tracking while Community Edition (CE) continues using pgboss for periodic polling.

## Problem

The current SLA implementation uses a pgboss job (`sla-timer`) that polls every 5 minutes to check all active tickets for threshold crossings. This approach has limitations:

1. **Polling inefficiency**: Checking all tickets every 5 minutes regardless of their actual SLA deadlines
2. **Resolution granularity**: Can only detect breaches within 5-minute windows
3. **No per-ticket orchestration**: Cannot wake up precisely when a specific ticket's threshold is about to be crossed
4. **Limited durability**: Job failures require re-scanning all tickets rather than resuming per-ticket workflows
5. **Business hours complexity**: Minute-by-minute iteration for business hours calculations is inefficient for long periods

For EE customers with large ticket volumes and strict SLA requirements, a Temporal-based approach provides:
- Per-ticket workflow orchestration with durable timers
- Precise threshold notifications timed to exact business-hours-adjusted deadlines
- Workflow state queries for real-time SLA status
- Automatic retry and recovery

## Goals

1. **EE: Temporal-based SLA workflows** — Create a dedicated Temporal workflow per ticket that sleeps until each SLA threshold and wakes to send notifications or escalate
2. **CE: Keep pgboss polling** — Maintain the existing `sla-timer` job for CE edition with no changes to functionality
3. **Unified service interface** — Abstract the backend choice behind a common interface so SLA services remain edition-agnostic
4. **Business hours-aware timers** — Both backends must correctly calculate wake times respecting business hours, holidays, and pause states
5. **Graceful degradation** — EE falls back to pgboss if Temporal is unavailable

## Non-goals

- Changing the SLA data model or database schema
- Modifying the existing SLA policy configuration UI
- Adding new notification channels beyond what exists
- Real-time WebSocket push for SLA status updates
- Historical SLA analytics or reporting changes
- Migration tooling for existing tickets (new tickets get workflows; existing tickets continue with polling)

## Users and Primary Flows

### Primary Users
- **MSP technicians**: See accurate SLA status badges and receive timely threshold notifications
- **Board managers**: Receive escalation notifications at configured thresholds
- **System administrators**: Configure SLA policies, business hours, and escalation rules

### Primary Flows

#### Flow 1: Ticket Created (EE with Temporal)
1. Ticket is created with SLA policy assigned
2. `slaService.startSlaForTicket()` is called
3. Service detects EE edition and starts a `SlaTicketWorkflow` via Temporal
4. Workflow calculates response/resolution deadlines considering business hours
5. Workflow sleeps until first threshold (e.g., 50% of response time)
6. On wake, sends notification and sleeps until next threshold
7. Continues until ticket is resolved or SLA is breached

#### Flow 2: Ticket Created (CE with pgboss)
1. Ticket is created with SLA policy assigned
2. `slaService.startSlaForTicket()` is called
3. Service detects CE edition and records deadlines in ticket record
4. Existing `sla-timer` pgboss job polls every 5 minutes
5. Job calculates elapsed percentage and sends notifications for crossed thresholds

#### Flow 3: SLA Paused/Resumed
1. Ticket status changes to one configured to pause SLA (or awaiting_client)
2. `slaPauseService.pauseSla()` is called
3. **EE**: Signal sent to workflow to pause; workflow records pause start and cancels pending timers
4. **CE**: `sla_paused_at` timestamp set; polling job skips paused tickets
5. On resume: **EE**: Signal sent; workflow recalculates remaining time and sets new timers. **CE**: `sla_total_pause_minutes` incremented; polling resumes

#### Flow 4: Ticket Resolved
1. Ticket is closed/resolved
2. `slaService.recordResolution()` is called
3. **EE**: Signal sent to workflow to complete; workflow records met/breached status and terminates
4. **CE**: SLA fields updated; polling job naturally excludes resolved tickets

## UX / UI Notes

No UI changes required. The SLA status badges and notifications work identically regardless of backend. The only user-facing difference is potentially more precise notification timing in EE.

## Requirements

### Functional Requirements

#### FR-1: Edition Detection and Routing
- [ ] Create `SlaBackendFactory` that returns appropriate backend based on edition
- [ ] Factory checks `isEnterprise` from `server/src/lib/features.ts`
- [ ] Returns `TemporalSlaBackend` for EE, `PgBossSlaBackend` for CE

#### FR-2: Common SLA Backend Interface
- [ ] Define `ISlaBackend` interface with methods:
  - `startSlaTracking(ticketId, policyId, targets, schedule)`: Start tracking for a ticket
  - `pauseSla(ticketId, reason)`: Pause SLA timer
  - `resumeSla(ticketId)`: Resume SLA timer
  - `completeSla(ticketId, type: 'response' | 'resolution', met: boolean)`: Complete response or resolution
  - `cancelSla(ticketId)`: Cancel SLA tracking (ticket deleted or policy removed)
  - `getSlaStatus(ticketId)`: Get current SLA status

#### FR-3: Temporal Workflow for EE (SlaTicketWorkflow)
- [ ] Create `sla-ticket-workflow.ts` in `ee/temporal-workflows/src/workflows/`
- [ ] Workflow input: ticket ID, tenant ID, policy targets, business hours schedule
- [ ] Workflow maintains state: current phase (response/resolution), pause state, notified thresholds
- [ ] Workflow uses Temporal timers (`sleep()`) to wake at threshold times
- [ ] On wake: send notification via activity, check for escalation, sleep until next threshold
- [ ] Support signals: `pause`, `resume`, `completeResponse`, `completeResolution`, `cancel`
- [ ] Support queries: `getState` (returns current status, remaining time, etc.)

#### FR-4: Business Hours Timer Calculation
- [ ] Create activity `calculateNextWakeTime(currentTime, targetTime, schedule, pauseMinutes)`
- [ ] Activity uses existing `businessHoursCalculator` logic
- [ ] Returns actual wall-clock time to sleep until, accounting for business hours
- [ ] Handles edge cases: start outside business hours, holidays, timezone changes

#### FR-5: Temporal Activities for SLA Operations
- [ ] `sendSlaNotification`: Sends threshold notification (reuses existing notification service)
- [ ] `checkAndEscalate`: Checks escalation thresholds and escalates if needed
- [ ] `updateSlaStatus`: Updates ticket SLA fields in database
- [ ] `recordSlaAuditLog`: Writes to sla_audit_log table

#### FR-6: pgboss Backend for CE
- [ ] Create `PgBossSlaBackend` implementing `ISlaBackend`
- [ ] `startSlaTracking`: No-op (deadlines already stored by slaService)
- [ ] `pauseSla`/`resumeSla`: Delegate to existing `slaPauseService`
- [ ] `completeSla`: Delegate to existing `slaService` methods
- [ ] Existing `sla-timer` job continues polling for threshold notifications

#### FR-7: Integration with Existing SLA Services
- [ ] Modify `slaService.startSlaForTicket()` to call backend's `startSlaTracking()`
- [ ] Modify `slaPauseService.pauseSla()`/`resumeSla()` to call backend methods
- [ ] Modify `slaService.recordFirstResponse()`/`recordResolution()` to signal backend

#### FR-8: Workflow Lifecycle Management
- [ ] Workflow ID format: `sla-ticket-{tenantId}-{ticketId}`
- [ ] On ticket deletion: cancel workflow if running
- [ ] On SLA policy change: cancel existing workflow and start new one
- [ ] Workflow gracefully handles duplicate starts (idempotent)

### Non-functional Requirements

#### NFR-1: Fallback Behavior
- [ ] EE with Temporal unavailable falls back to pgboss polling
- [ ] Log warning when fallback occurs
- [ ] Existing tickets continue with polling; new tickets also use polling until Temporal recovers

#### NFR-2: Workflow Durability
- [ ] Workflows survive Temporal worker restarts
- [ ] Workflow state reconstructed from Temporal history on replay

## Data / API / Integrations

### Database
No schema changes. Uses existing:
- `tickets` table: `sla_*` fields for tracking
- `sla_audit_log`: Audit trail
- `sla_policies`, `sla_policy_targets`: Policy configuration
- `business_hours_schedules`, `business_hours_entries`, `holidays`: Business hours

### Temporal Task Queue
- Queue name: `sla-workflows` (or reuse `alga-jobs` with workflow routing)
- Workflows: `SlaTicketWorkflow`
- Activities: `sla-activities` (notification, escalation, DB updates)

### Integration Points
- `@alga-psa/notifications`: For sending threshold notifications
- `@alga-psa/sla`: For business hours calculations
- `JobRunnerFactory`: For fallback to pgboss when Temporal unavailable

## Security / Permissions

No changes. Existing tenant isolation via `tenant` column and `runWithTenant()` context.

## Observability

- Temporal UI provides workflow visibility for debugging
- Existing logger calls in activities for audit trail
- Workflow queries allow real-time status inspection

## Rollout / Migration

### Phase 1: Backend Interface
1. Define `ISlaBackend` interface
2. Implement `PgBossSlaBackend` wrapping existing behavior
3. Wire up factory with CE-only support
4. Verify no behavioral changes

### Phase 2: Temporal Workflow Implementation
1. Create `SlaTicketWorkflow` and activities
2. Implement `TemporalSlaBackend`
3. Add EE branch to factory
4. Test in EE environment

### Phase 3: Integration
1. Integrate backend calls into existing SLA services
2. Handle pause/resume signals
3. Handle ticket resolution signals
4. Test full lifecycle

### Migration Strategy
- New tickets get workflows (EE) or polling (CE)
- Existing active tickets continue with polling (no migration needed)
- Workflows only started for tickets created after deployment

## Open Questions

1. **Q: Should we migrate existing active tickets to workflows?**
   A: No - too complex, let them naturally resolve via polling. Only new tickets get workflows.

2. **Q: How long should workflows remain after ticket resolution?**
   A: Workflow completes immediately on resolution. Temporal history retained per server config.

3. **Q: Should workflow query replace database reads for SLA status?**
   A: No - database remains source of truth. Workflow is for timer orchestration only.

## Acceptance Criteria (Definition of Done)

1. [ ] EE edition starts Temporal workflow for new tickets with SLA policies
2. [ ] Workflow wakes at correct business-hours-adjusted times for each threshold
3. [ ] Notifications sent at configured thresholds (50%, 75%, 90%, 100%)
4. [ ] Escalations triggered when thresholds crossed
5. [ ] Pause signal stops workflow timers; resume recalculates remaining time
6. [ ] Resolution signal completes workflow and records met/breached status
7. [ ] CE edition continues using pgboss polling with no changes
8. [ ] Fallback to pgboss works when Temporal unavailable in EE
9. [ ] Unit tests for backend interface and workflow logic
10. [ ] Integration test for full ticket SLA lifecycle in EE