support_backend/docs/07-backend-architecture.md

# 07 — Backend Architecture

## 1. Technology stack

- Node.js + TypeScript
- Fastify
- PostgreSQL + Prisma
- Redis + BullMQ
- Pino (structured logging)
- OpenAPI
- Zod (validation)
- Vitest
- Docker

**Architecture style:** modular monolith. Do not start with microservices — the module boundaries below make a future split possible, but premature service decomposition adds operational cost this system doesn't need yet.

## 2. Top-level source layout

```
src/
├── config
├── bootstrap
├── plugins
├── common
├── infrastructure
├── modules
├── events
├── jobs
└── api
```

## 3. Domain module groups

```
modules/
├── identity
│   ├── auth
│   ├── customers
│   ├── agents
│   └── teams
│
├── catalog
│   ├── products
│   ├── categories
│   ├── problem-types
│   └── priorities
│
├── ticketing
│   ├── tickets
│   ├── messages
│   └── attachments
│
├── problem-management
│   ├── problems
│   ├── investigation
│   ├── root-causes
│   ├── solutions
│   ├── verification
│   └── resolutions
│
├── ai-support
│   ├── agents
│   ├── sessions
│   ├── diagnosis
│   ├── knowledge
│   ├── troubleshooting
│   ├── tools
│   ├── tool-execution
│   ├── verification
│   └── escalation
│
├── orchestration
│   ├── hierarchy
│   ├── routing
│   ├── orchestration
│   ├── assignments
│   ├── sla
│   └── escalation
│
└── platform
    ├── notifications
    ├── audit
    ├── business-calendars
    ├── integrations
    ├── reports
    └── admin
```

> Note: `identity` here means SupportHub's own agent/team/support-domain identity — **not** a re-implementation of SaaS user/tenant identity. See [01](./01-product-vision-and-principles.md#4-system-ownership-boundary) and [02](./02-integration-and-security.md#5-rbac-boundary).

## 4. Module internal structure

Standard module:

```
module/
├── controller/
├── routes/
├── schema/
├── repository/
├── service/
├── types/
├── mapper/
├── constants/
└── index.ts
```

Complex modules (real decision logic, not just CRUD) add:

```
├── engine/
├── rules/
├── strategies/
└── calculators/
```

Example — `orchestration`:

```
orchestration/
├── controller
├── routes
├── schema
├── repository
├── service
├── engine
├── rules
├── types
├── mapper
├── constants
└── index.ts
```

`ai-support` and `orchestration` are the two module groups most likely to need the extended structure across nearly all their submodules — see [03](./03-ai-support-architecture.md) and [05](./05-orchestration-sla-escalation.md).

## 5. Request flow

```
HTTP → Route → Schema validation → Controller → Service
     → Engine/Rules (if required) → Repository → Prisma → PostgreSQL
```

Rules:
- **Controller never touches Prisma directly.**
- **Repository** is the only layer that talks to Prisma.
- **Service** coordinates business workflows and calls repositories/engines.
- **Engine** implements complex decision logic (assignment strategy selection, SLA calculation, escalation rule evaluation, AI tool-execution policy).

## 6. Module boundaries

Modules must not reach into another module's internals. Only import through the target module's public `index.ts`.

```ts
// Allowed
import { TicketService } from "@/modules/ticketing/tickets";

// Not allowed — reaches past the module boundary
import { TicketRepository } from "@/modules/ticketing/tickets/repository/ticket.repository";
```

## 7. Redis / BullMQ usage

Redis is **not** a source of truth — it's for queues, caching, and coordination. Use BullMQ jobs for:

- SLA monitoring (warning, breach detection)
- Escalation triggering
- Notifications
- AI background work where appropriate (long-running tool calls, batch re-diagnosis)
- Analytics rollups
- Attachment processing (malware scan, thumbnailing)
- Cleanup jobs

**Jobs must be durable and idempotent.** Never use `setTimeout` or any in-memory timer for production SLA enforcement — a process restart must not lose or double-fire SLA state transitions.

## 8. Domain events

Emit and consume these as first-class domain events (not just side effects buried in service code), so audit, notifications, analytics, and SLA/escalation subsystems can all react independently:

```
TicketCreated, ProblemCreated, TicketClassified
AIAnalysisStarted, KnowledgeRetrieved, AIDiagnosisCompleted
AIActionRequested, AIActionCompleted, AITroubleshootingStarted
AIResolutionVerified, TicketEscalatedToHuman
TicketAssigned, TicketReassigned, PriorityChanged
SLANearingBreach, SLABreached
InvestigationStarted, RootCauseIdentified
SolutionProposed, SolutionImplemented, VerificationCompleted
TicketResolved, TicketClosed, TicketReopened
```

Events must be traceable (correlation ID) and auditable.

## 9. Notifications

Channels: in-app, email, push (where appropriate). Triggered asynchronously (via job queue, never inline in the request path) on: ticket created, AI solved, human escalation, assignment, agent reply, SLA warning, SLA breach, escalation, resolution, closure, reopen.

## 10. Audit

Audit every important action: ticket creation, AI escalation, assignment/reassignment, priority changes, hierarchy changes, SLA changes, escalation, investigation, root cause, solution, verification, resolution, closure.

Audit record shape:

```ts
interface AuditRecord {
  actor: string;
  actorType: "customer" | "agent" | "admin" | "system" | "ai";
  action: string;
  entity: string;
  entityId: string;
  oldValue?: unknown;
  newValue?: unknown;
  timestamp: Date;
  reason?: string;
  metadata?: Record<string, unknown>;
}
```

Security-relevant audit records should be **append-only** from the application's perspective — no service-layer update/delete path against `AuditLog`.

## 11. Observability endpoints

```
GET /health
GET /health/live
GET /health/ready
GET /metrics
```

Structured logging via Pino, with request ID and correlation ID on every log line; metrics and tracing wired through from day one, not bolted on later. Full metric list is in [09](./09-testing-observability-cicd.md#observability).