Development

docker compose --env-file .env.development -f docker-compose.development.yml up -d --build

Test

docker compose --env-file .env.test -f docker-compose.test.yml up --build

Production

docker compose --env-file .env.prod -f docker-compose.prod.yml up --build -d

Stop

docker compose -f docker-compose.prod.yml down

Local environment setup

.env.development, .env.test, and .env.prod are gitignored (they hold real credentials) — copy .env.example to the one you need and fill in real values before running any command above.

CI/CD

Every push/PR triggers the Jenkins pipeline defined in Jenkinsfile. Stage order: checkout → install → environment validation → typecheck → lint → format check → unit test → integration test → E2E test → build → Docker build → publish → deploy. Publish/deploy only run on branches with a configured deploy target (main → prod, develop/test → test); other branches validate and build only. Pipeline run status and per-stage logs are visible in the Jenkins UI for the relevant job — see specs/001-ci-pipeline/quickstart.md for how to validate the pipeline itself, and specs/001-ci-pipeline/contracts/pipeline-stage-contract.md for the guarantees each stage makes.

Required Jenkins credentials (see the header comment in Jenkinsfile for exact IDs): per target environment (test, prod) a Postgres password, Redis password, JWT secret, and AWS access key/secret, plus one shared Docker registry username/password. None of these are ever read from a file in this repository.

SaaS Integration

POST /v1/support/requests is the trust boundary a registered SaaS product calls through — every request must carry a Authorization: Bearer <signed-token> header (HMAC-SHA256, signed with the integration's own secret) and a body matching the inbound contract. See specs/002-saas-integration/contracts/inbound-request-contract.md for the full validation order and error codes, and specs/002-saas-integration/quickstart.md for runnable scenarios.

Admins manage integrations under /admin/products/:externalProductId/integration (register) and /admin/integrations/:integrationId/{rotate,revoke,status,audit-trail}. These admin routes are not yet actually access-controlled — fastify.authenticate is a stub pending the identity/auth module; don't expose them outside a trusted network until that's implemented.

Rate limits (rateLimitPerMinute, rateLimitPerUserPerMinute) are set per integration at registration time and enforced via a Redis-backed fixed-window counter, independent of the global @fastify/rate-limit floor already applied to every route.

Ticketing

A validated inbound request (see "SaaS Integration" above) creates a Ticket and Problem immediately — before any diagnosis. See specs/003-ticketing/contracts/ticket-lifecycle-contract.md for the full lifecycle state machine, message-visibility rules, and attachment pipeline, and specs/003-ticketing/quickstart.md for runnable scenarios.

• Status transitions: PATCH /tickets/:ticketId/status requires expectedVersion (optimistic concurrency — a stale version is rejected with 409, never silently overwritten) and only accepts transitions defined in the state machine (400 INVALID_TRANSITION otherwise).
• Messages: POST/GET /tickets/:ticketId/messages (customer-scoped — internal note types are never returned) and GET /agent/tickets/:ticketId/messages (agent-scoped — everything). A message's customer-visibility is always derived from its type, never caller-supplied.
• Attachments: presigned-PUT upload (POST .../attachments/upload-url → POST .../attachments/confirm) against MinIO/S3 — file bytes never transit this API. Nothing is downloadable yet (GET .../attachments/:attachmentId/download-url always returns 409): the malware scanner is a placeholder that fails closed until a real one (src/modules/ticketing/attachments/mapper/malware-scanner.ts) replaces it.
• Local/test object storage is MinIO — see the minio service in docker-compose.development.yml / docker-compose.test.yml and the AWS_S3_ENDPOINT value in the corresponding .env.* file.

Product Knowledge

Admin CRUD for KnowledgeEntry/ErrorCode/KnownIssue/Runbook, plus GET /knowledge/retrieve — a filtered (not semantic/vector) query the future AI-support feature will call. See specs/004-product-knowledge/contracts/knowledge-contract.md for the full route list and specs/004-product-knowledge/quickstart.md for runnable scenarios.

• Versioning: editing a published KnowledgeEntry or Runbook never overwrites it in place — it creates a new row (version incremented, isCurrentVersion: true), and the prior version stays queryable (GET /admin/knowledge/:code/versions). Requires expectedVersion; a stale value is rejected with 409, same concurrency pattern as ticket status updates.
• Retrieval (GET /knowledge/retrieve?productId=&feature=&category=) only ever returns published, currently-effective, current-version entries scoped to the given product — validated entries are ranked ahead of unvalidated ones. An unregistered productId returns an empty array, not an error.
• Full semantic/embedding-based retrieval is intentionally not implemented here — see specs/004-product-knowledge/spec.md Assumptions.

AI Support

A ticket's AI session diagnoses the problem via a real Anthropic Claude call, applies a configurable confidence-band policy, and — on "proceed" — reasons and acts through a small, permission/risk-gated tool system, optionally walking a matching runbook step by step. See specs/005-ai-support/contracts/ai-support-contract.md for the full route list and specs/005-ai-support/quickstart.md for runnable scenarios.

• Requires a real ANTHROPIC_API_KEY (per explicit product decision — not a mock or pluggable-interface phase). The app boots and every non-AI test still passes without one; an AI session simply fails closed (escalates) if a reasoning call is attempted with none configured. AI_SUPPORT_MODEL/AI_SUPPORT_EFFORT and the system-wide confidence-threshold/question-budget defaults are all environment-configurable, never hardcoded (doc 11 §B2).
• Session lifecycle: a session starts automatically (queued, off the hot path of POST /v1/support/requests) when a ticket is created, and its status mirrors onto Ticket.status through 003-ticketing's existing state machine (AI_ANALYZING → AI_TROUBLESHOOTING → AI_VERIFYING → AI_RESOLVED, or HUMAN_ESCALATION from any point) — see specs/005-ai-support/research.md "AISupportSession.status drives Ticket.status". A customer reply is POST /tickets/:ticketId/ai-session/messages; the current session (with its diagnosis and conversation) is GET /tickets/:ticketId/ai-session.
• Confidence policy: PUT/GET /admin/products/:externalProductId/ai-policy sets per-product (optionally per-category) highThreshold/lowThreshold/maxClarifyingQuestions, falling back to env-configured system defaults when nothing is configured — applies to the very next diagnosis, no deploy required.
• Tool system: every tool call the AI proposes is evaluated by a deterministic policy gate (src/modules/ai-support/tools/service/policy-gate.ts) before anything executes — the gate never reads the AI's own proposal/justification text, only the tool's declared risk level and product scope. Low-risk tools (getTicketSnapshot, searchProductKnowledge, verifyProductResolution, escalateToHuman) auto-execute; overrideTicketPriority is high-risk and always stays pending_approval — there's no human-approval UI yet (Phase 10), so it never actually runs, by design, not by oversight. Every proposal, decision, and result is recorded and auditable via GET /tickets/:ticketId/ai-session/actions.
• verifyProductResolution is a documented, fail-closed placeholder (same pattern as ticketing/attachments's malware scanner) — it always returns confirmed: false, since there's no real per-product operational signal to check yet (doc 11 §A2). A ticket is only ever marked AI_RESOLVED on a passing result from this tool, never from what the customer says alone — so in practice, genuinely automatic AI resolution won't happen until a real verification signal replaces this placeholder.
• Runbook engine: when a diagnosis's problemType matches a runbook's key for the product (004-product-knowledge), the application — never the model — tracks which step is current (currentStepIndex) and advances it by exactly one at a time; exhausting every step without resolving escalates with the full attempted sequence attached.
• Semantic/vector retrieval, product-signal webhook verification, model routing/fallback, cost dashboards, and localization are intentionally out of scope here — see specs/005-ai-support/spec.md Assumptions.

Support Organization

Admin CRUD for Team/Agent/AgentSkill/AgentAvailability, plus a fully dynamic HierarchyNode tree — this system's explicit routing differentiator (doc 01: "changing one must never require a code change"). See specs/006-support-organization/contracts/support-org-contract.md for the full route list and specs/006-support-organization/quickstart.md for runnable scenarios.

• Teams and agents: POST/PATCH/GET /admin/teams, POST/PATCH/GET /admin/agents — active/inactive only, never hard deletion. Deactivating a team never cascades into deactivating its agents.
• Skills and availability: PUT /admin/agents/:agentId/skills/:skillTag upserts a proficiency level (never duplicates the same tag). PUT /admin/agents/:agentId/availability upserts the agent's single current record — status/working hours/current load — using last-write-wins, not this system's usual expectedVersion optimistic-concurrency pattern: availability is frequently-changing operational telemetry, not a durable business record (see specs/006-support-organization/research.md).
• The dynamic hierarchy: POST/PUT /admin/hierarchy-nodes build an arbitrary, nestable tree scoped to product/category/priority, each node carrying an assignmentStrategy and slaPolicyId/escalationPolicyId reference (no such policy tables exist yet — Phase 7/8) and opaque entryConditions/exitConditions. A reparenting edit that would make a node its own ancestor is rejected with 400 CYCLE_DETECTED; every create/edit/activate/deactivate writes an AuditLog row.
• Capability-eligibility lookup (GET /support-org/capability-eligibility?skills=&productId=& categoryId=&priorityId=) is a read-only contract for the future orchestration/assignment phase (Phase 7) to call — it answers "who is capability-eligible" (active agent, active team, holds every required skill, composed with any matching hierarchy node's own skills), and deliberately never filters by availability, working hours, or current load (doc 05 §3: "capability is evaluated before availability"). It does not make an assignment decision.
• This feature supersedes the pre-existing identity/agents scaffold stub, which queried a generic User/UserRole model unrelated to this system's real architecture (nothing else uses it — CustomerReference, built in 002, is the real customer-identity mechanism). identity/customers and identity/auth are untouched — out of scope here.

Orchestration and Assignment

When a ticket reaches HUMAN_ESCALATION, this system automatically resolves 006's hierarchy/ capability-eligibility lookup for it and assigns exactly one eligible agent through a pluggable strategy — no caller has to trigger this. See specs/007-orchestration-assignment/contracts/orchestration-contract.md for the full route list and specs/007-orchestration-assignment/quickstart.md for runnable scenarios.

• Trigger: entirely event-driven — ticketsService.updateStatus (003) publishes a domain event on every status change, and this feature's subscriber (registered alongside 005's own AI-session-ending one) reacts when newStatus === 'HUMAN_ESCALATION'. Neither ticketing nor ai-support has any import of orchestration — the event bus is what keeps that direction one-way. The event bus itself was fixed while building this feature: EventBus.publish now actually awaits its subscribers (it previously fired them via EventEmitter.emit, which never waits for an async listener) — without that fix, a status-update HTTP call could return before orchestration (or 005's own hook) had actually finished. registerDomainEventHandlers() is called from buildApp() itself now (idempotently — see its own code comment), not only from server.ts's production startup path, so this is true in tests too, not just production.
• Strategies: ROUND_ROBIN (concurrency-safe via an atomic Redis INCR, verified under real concurrent load in tests/concurrency/round-robin.test.ts), LEAST_LOADED, SKILL_BASED are auto-selected from the matched hierarchy node's own assignmentStrategy (or a configurable system default, ORCHESTRATION_DEFAULT_STRATEGY, when no node matched). MANUAL/DIRECT are never auto-selected — they only ever come from POST /admin/tickets/:ticketId/assignment's explicit agentId. LEAST_LOADED/SKILL_BASED ties fall through to the same concurrency-safe cursor ROUND_ROBIN uses, never an arbitrary/unstable ordering.
• A ticket's "required skill" comes from its most recent AI diagnosis's problemType (005), when one exists, unioned with any matching hierarchy node's own skills (006) — when neither exists, there's no skill constraint at all (every active agent is eligible), never zero eligible agents; see specs/007-orchestration-assignment/research.md.
• History: Assignment is a version-row-per-period model (reassigning supersedes the current row, never overwrites it); AssignmentHistory is a separate, purely-additive event log — GET /tickets/:ticketId/assignment (current) and GET /tickets/:ticketId/assignment-history (everything, including "no eligible agent" outcomes with agentId: null).
• currentLoad (006) is read by LEAST_LOADED, never written by this feature — no increment-on-assign/decrement-on-resolve lifecycle exists yet (that's a later phase's job once ticket resolution itself is built).
• SLA policy execution and rule-driven escalation are intentionally out of scope here — doc 05 documents them alongside orchestration, but the roadmap places them in Phase 8. See specs/007-orchestration-assignment/spec.md Assumptions.