support_backend/.specify/memory/constitution.md

<!--
Sync Impact Report
Version change: [TEMPLATE] → 1.0.0 (initial ratification)
Modified principles: n/a (first concrete version; template placeholders replaced)
Added sections:
  - Core Principles I–VIII (SaaS identity authority, configuration over hardcoding,
    layered architecture/module boundaries, AI-recommends/policy-decides, evidence-based
    verification, durable audit & history, concurrency-safe job handling, ticket/problem
    separation)
  - Technology & Platform Constraints
  - Testing, Observability & CI/CD Gates
  - Governance
Removed sections: none (placeholders only)
Deferred items:
  - TODO(RATIFICATION_DATE): original adoption date predates this codified constitution
    and was not recorded; using first-codification date as a placeholder until the team
    confirms the true ratification date.
Templates requiring follow-up: none checked yet — run speckit-specify/plan/tasks next
  and verify they don't reference stale template placeholder names.
-->

# SupportHub Constitution

## Core Principles

### I. SaaS Is the Sole Identity & Access Authority (NON-NEGOTIABLE)
SupportHub MUST NOT duplicate, shadow, or re-implement SaaS user identity, tenant identity,
product access, subscriptions, permissions, or authentication. It integrates with the owning
SaaS via secure APIs and per-product integration credentials, and stores only external
references (`externalUserId`, `externalTenantId`, `externalProductId`). SupportHub is the
sole authority only for its own domain: tickets, problems, support org structure, routing/
assignment, SLA, escalation, investigation/root cause/solution/verification/resolution,
knowledge, and support audit. Rationale: a second, drifting identity/RBAC system is worse
than no system — it creates authorization ambiguity. Exactly one source of truth per concern
keeps that ambiguity from existing.

### II. Configuration Over Hardcoding
Support hierarchy, SLA values, escalation paths, routing rules, and assignment strategy MUST
be admin-configurable data, never hardcoded in application code. Anything the business can
legitimately change without a deploy MUST be driven by configuration or persisted state, not
by editing source. Rationale: these policies change on business cadence, not engineering
cadence; hardcoding them forces a deploy for every policy tweak and makes non-engineers
dependent on engineering for routine changes.

### III. Layered Architecture With Enforced Module Boundaries
Every module follows Route → Schema validation → Controller → Service → (Engine/Rules if
required) → Repository → Prisma → PostgreSQL. Controllers MUST NOT touch Prisma or contain
business logic; routes MUST NOT contain business logic; the repository is the only layer
permitted to call Prisma. A module's internals are reachable only through its own public
`index.ts` — no deep cross-module imports, no circular module dependencies, no giant global
services. Rationale: this is what keeps a modular monolith splittable later without a rewrite,
and what makes module boundaries reviewable rather than aspirational.

### IV. AI Recommends, Deterministic Policy Decides
The AI Support Agent MUST NOT receive unrestricted backend access, MUST NOT invent
troubleshooting steps or product behavior beyond retrieved knowledge, and MUST NOT execute a
high-risk action without an explicit permission/policy check — regardless of the model's
reported confidence. Tool execution is scoped and enforced by deterministic policy code, never
left to model judgment alone. Rationale: the LLM proposes a diagnosis or action; policy code is
the actual authority. This is what makes running AI-first support against production systems
safe.

### V. Evidence-Based Verification
A problem MUST NOT be marked resolved on the customer's say-so alone wherever a system signal
is available to check the outcome. Recording a resolution requires verification evidence
attached to the ticket/problem, not just a customer confirmation click. Rationale: customer
"yes, it's fixed" clicks on problems that recur erode trust in both the AI and human resolution
paths; evidence is what separates a genuinely closed loop from a hopeful one.

### VI. Durable Audit & History
All important operations — assignment, escalation, SLA transitions, resolution, AI tool calls —
MUST be audit-logged. Full AI session history and full resolution history MUST be preserved,
never overwritten or summarized away. Every log line MUST carry a request ID/correlation ID so
a single ticket's full journey (AI session → tool calls → escalation → assignment → SLA events)
is traceable end to end. Rationale: admin trust, dispute resolution, and debugging all depend on
nothing about a ticket's journey being silently lost.

### VII. Concurrency-Safe, Durable Job Handling
SLA enforcement MUST NOT rely on in-memory timers (e.g. `setTimeout`) — enforcement state MUST
survive a process restart. Assignment and escalation logic MUST be tested under concurrency
(e.g. two tickets assigned simultaneously must never double-assign or corrupt round-robin
state), and job handlers MUST be idempotent (a rule firing twice must not create duplicate
events). Large files (attachments) MUST NOT be stored in PostgreSQL — use object storage.
Rationale: assignment and SLA are correctness-critical under real concurrent load; treating them
as single-threaded conveniences is how double-assignment and missed SLA breaches happen in
production.

### VIII. Problem and Ticket Are Separate, Related Entities
"Ticket" (the durable, customer-facing record created immediately when a problem is reported)
and "Problem" (the thing being diagnosed and investigated) MUST remain distinct, related
entities — never collapsed into one model. Rationale: a ticket exists before diagnosis begins
and can outlive multiple problem/investigation cycles; merging the two loses that lifecycle
distinction and makes the AI-first flow (ticket created at `NEW`, before AI even starts) harder
to represent correctly.

## Technology & Platform Constraints

- Stack: Node.js + TypeScript, Fastify, PostgreSQL + Prisma, Redis + BullMQ, Pino (structured
  logging), OpenAPI, Zod (validation), Vitest, Docker.
- Architecture style: modular monolith. Do not decompose into microservices prematurely —
  the module boundaries required by Principle III exist to make a future split *possible*,
  not to justify doing one now.
- Standard module shape: `controller/ routes/ schema/ repository/ service/ types/ mapper/
  constants/ index.ts`. Modules with real decision logic (not just CRUD) additionally use
  `engine/ rules/ strategies/ calculators/`.

## Testing, Observability & CI/CD Gates

- Required backend test categories: unit, integration, E2E, concurrency (assignment races),
  SLA (pause/resume correctness, business-calendar math, durability across a simulated process
  restart), escalation idempotency, orchestration (capability matching, hierarchy traversal,
  strategy selection), and AI tool-permission tests (the AI must never invoke a tool it isn't
  scoped for; high-risk tools require policy/approval regardless of AI confidence).
- Two critical end-to-end scenarios MUST exist as automated tests at all times: (A) AI resolves
  directly — problem → knowledge → guided troubleshooting → verification → AI-resolved; (B) AI
  escalates to human — problem → failed AI troubleshooting → escalation → orchestration →
  assignment → SLA → investigation → solution → verification → resolution → closure.
- Observability is wired in from the start, not retrofitted: Pino structured logs with a
  request ID and correlation ID on every line; `GET /health`, `GET /health/live`,
  `GET /health/ready`, `GET /metrics` exposed from day one.
- CI (Jenkins) MUST run, in order: checkout → install → environment validation → typecheck →
  lint → format check → unit test → integration test → E2E test → build → Docker build →
  publish → deploy. Production deployments use protected Jenkins-managed credentials; real
  secrets are never committed to the repository.

## Governance

This constitution supersedes ad hoc conventions and undocumented team habits. All PRs and code
reviews MUST verify compliance with the principles above before merge.

Amendments require: a documented rationale for the change, a version bump under the semantic
versioning rule below, and an updated Sync Impact Report prepended to this file. MAJOR = a
backward-incompatible principle removal or redefinition. MINOR = a new principle added, or
existing guidance materially expanded. PATCH = clarification, wording, or typo fixes with no
semantic change. Any exception to a MUST/MUST NOT rule requires explicit written justification
in the relevant PR description and is expected to be rare, not routine.

Detailed product and system design lives in `docs/00-INDEX.md` through
`docs/10-implementation-roadmap.md` — this constitution states the non-negotiable engineering
rules; the docs explain the full system those rules protect.

**Version**: 1.0.0 | **Ratified**: TODO(RATIFICATION_DATE): confirm original adoption date | **Last Amended**: 2026-08-21