saqib mirandClaude Sonnet 5
72dddcdf74
Two-call reasoning design (structured-output diagnosis, then a separate knowledge-grounded reasoning/tool call), confidence-band policy as a DB- configurable gate applied by app code, a deterministic tool-policy gate that never reads AI free text, an app-owned runbook step index, and a fail-closed placeholder verification tool mirroring the existing malware-scanner precedent. Real Anthropic Claude integration per explicit product decision. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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/statusrequiresexpectedVersion(optimistic concurrency — a stale version is rejected with409, never silently overwritten) and only accepts transitions defined in the state machine (400 INVALID_TRANSITIONotherwise). - Messages:
POST/GET /tickets/:ticketId/messages(customer-scoped — internal note types are never returned) andGET /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-urlalways returns409): 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
minioservice indocker-compose.development.yml/docker-compose.test.ymland theAWS_S3_ENDPOINTvalue 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
KnowledgeEntryorRunbooknever overwrites it in place — it creates a new row (versionincremented,isCurrentVersion: true), and the prior version stays queryable (GET /admin/knowledge/:code/versions). RequiresexpectedVersion; a stale value is rejected with409, same concurrency pattern as ticket status updates. - Retrieval (
GET /knowledge/retrieve?productId=&feature=&category=) only ever returnspublished, currently-effective, current-version entries scoped to the given product —validatedentries are ranked ahead ofunvalidatedones. An unregisteredproductIdreturns an empty array, not an error. - Full semantic/embedding-based retrieval is intentionally not implemented here — see
specs/004-product-knowledge/spec.mdAssumptions.