# 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