support_backend/docs/10-implementation-roadmap.md

# 10 — Implementation Roadmap

Implement incrementally. **Do not implement all business logic in one step.** Each phase below must be typed, tested, documented, integrated, observable, and production-safe before moving on — a feature isn't "done" until it clears all seven of those, not just "coded."

## Phased plan

| Phase | Focus | Primary deliverables |
|---|---|---|
| **1** | Engineering foundation | Repo scaffolding, Fastify modular-monolith skeleton, Next.js app skeleton, Prisma schema baseline, CI pipeline skeleton, env validation, health endpoints |
| **2** | SaaS integration | Product/ProductIntegration models, credential validation, service-to-service auth (signed tokens/OAuth2/mTLS), inbound request contract, rate limiting |
| **3** | Product knowledge | Knowledge/KnownIssue/ErrorCode/Runbook models, admin CRUD, versioning + publish state, retrieval (RAG) layer |
| **4** | AI support | AI session/diagnosis/interaction models, classification, RAG-backed reasoning, confidence thresholds (configurable), tool system with permission/risk gating, runbook engine, verification logic |
| **5** | Ticketing | Ticket + Problem models (kept separate), message types, attachment pipeline (object storage, scanning, expiring URLs), ticket lifecycle state machine |
| **6** | Support organization | Team/Agent/AgentSkill/AgentAvailability models, dynamic HierarchyNode configuration, admin hierarchy editor |
| **7** | Orchestration and assignment | Orchestration engine, capability matching, pluggable assignment strategies, concurrency-safe round robin, assignment history |
| **8** | SLA and escalation | SLA policy engine, business calendar/holiday support, durable pause/resume via BullMQ, rule-driven escalation engine, escalation event audit |
| **9** | Problem resolution | Investigation/RootCause/Solution/SolutionImplementation/SolutionVerification/Resolution models and workflows, customer confirmation + reopen flow |
| **10** | Agent/Admin UI | Agent workspace (continues from AI context), admin configuration surfaces for every configurable subsystem above |
| **11** | Analytics, hardening, security, production deployment | Reporting dashboards, full observability, security hardening pass, load/concurrency testing, production deployment pipeline |

> Note the dependency direction: Phase 4 (AI) and Phase 9 (resolution stages) both plug into Phase 5's ticket, so ticketing's core data model should be stable before AI or resolution logic is built against it — even though ticketing is listed after AI support here, expect to iterate the `Ticket`/`Problem` shape lightly across phases 4–9 rather than treating phase 5 as strictly sequential.

## Success criteria checklist

Use this as the actual go/no-go list, not phase names — a phase can be "complete" on paper while missing several of these.

- [ ] A SaaS product can securely integrate with SupportHub
- [ ] The SaaS user can enter support from within the product
- [ ] SupportHub receives trusted product/tenant/user context
- [ ] A problem creates a durable support case immediately
- [ ] AI understands the problem
- [ ] AI retrieves correct product knowledge
- [ ] AI can diagnose known issues
- [ ] AI can guide the customer through supported troubleshooting
- [ ] The system verifies successful resolution with evidence
- [ ] AI can resolve supported issues automatically
- [ ] Unresolved issues are escalated automatically
- [ ] AI context is preserved in the ticket for the human agent
- [ ] Orchestration chooses the correct support path
- [ ] Capability/skill matching works correctly
- [ ] Assignment respects availability/workload
- [ ] SLA is applied correctly (calendar-aware, durable)
- [ ] Escalation occurs according to configured policy
- [ ] Human agents receive full context, don't restart diagnosis
- [ ] Agents can investigate and resolve the problem
- [ ] Resolution is verified and recorded
- [ ] Customer sees the final result
- [ ] Complete audit history exists
- [ ] All critical operations are observable
- [ ] CI/CD can validate and deploy the system safely

## Open business decisions (do not invent final values)

Anything the business hasn't finalized yet must be explicitly marked in code, config schema, and documentation as one of:

```
CONFIGURABLE
OPEN BUSINESS DECISION
REQUIRES BUSINESS CONFIRMATION
```

Known candidates for this list at spec time:
- Actual SLA minute values per product/priority/category
- Actual escalation rule conditions and target nodes per product
- Whether/when premium support tiers override "support enabled by default"
- Confidence-threshold cut points for high/medium/low AI bands, per product
- Assignment strategy choice per hierarchy node
- Business calendar definitions (hours, holidays, timezones) per team

Never hardcode a placeholder value for any of the above and ship it as if it were final — mark it and surface it for confirmation instead.

## Cross-reference map

| If you're building... | Read |
|---|---|
| The overall model and boundaries | [01](./01-product-vision-and-principles.md), [02](./02-integration-and-security.md) |
| The AI agent | [03](./03-ai-support-architecture.md) |
| The ticket/problem data model | [04](./04-ticketing-and-problem-management.md), [06](./06-database-schema.md) |
| Orchestration/SLA/escalation | [05](./05-orchestration-sla-escalation.md) |
| Backend module layout | [07](./07-backend-architecture.md) |
| Any UI surface | [08](./08-frontend-architecture.md) |
| Tests, CI, dashboards | [09](./09-testing-observability-cicd.md) |