support_backend/.specify/memory/constitution.md

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