OPSQAIOQOPSQAI
All documentation

Book 6

Engineering Handbook

Internal playbook for the OPSQAI engineering team. Public copy so integrators and auditors know how the sausage is made.

1. Conventions

  • TypeScript strict everywhere. No any, no @ts-ignore without a linked issue.
  • Server logic in createServerFn; public HTTP under src/routes/api/public/.
  • Design tokens only — no hard-coded colours in components.
  • Every new public table ships with GRANTs, ENABLE RLS, and policies in the same migration.

2. Release process

  1. Merge to main → CI builds and signs opsqai-web, opsqai-worker, postgres-pgvector images with cosign.
  2. Tagging vX.Y.Z promotes the images and publishes opsqai-stack.tgz to dl.opsqai.de/selfhost/X.Y.Z/.
  3. Release notes generated from Conventional Commits; CVEs linked explicitly.
  4. Managed Cloud rolls forward within 24h; self-host customers pull on their own schedule.

3. Adding a module

  1. Add a feature flag key to src/lib/license/features.ts.
  2. Create routes under src/routes/_authenticated/app.<module>.*.tsx.
  3. Register the module in the Portal sidebar behind hasFeature('module').
  4. Ship migrations with GRANT + RLS.
  5. Update the Product and Technical books.

4. Issuing a license

# In the Management Center
mc license issue \
  --customer "Acme GmbH" \
  --modules chat,knowledge,tickets \
  --seats 25 \
  --expires 2027-01-01 \
  --out acme.opsqai.license

The MC signs the JSON payload with the release Ed25519 key and stores the issuance in the audit trail.

5. Adding an AI adapter

  1. Implement AiAdapter under src/lib/ai/<name>.ts.
  2. Register in src/lib/ai/registry.ts.
  3. Add a wizard step field set + Doctor probe.
  4. Document env vars in the Administrator Guide.

6. Publishing container images

Images are pushed to ghcr.io/opsqai/*, signed with cosign keyless via OIDC in CI. SBOMs (CycloneDX) are attached to every image and mirrored to dl.opsqai.de/sbom/.

7. Migrations

SQL migrations live under supabase/migrations/. Rules: one logical change per migration, always backwards-compatible for one minor version, never destructive without a two-step deprecation window. Every new public table needs GRANT + RLS in the same file.

8. Pre-release checklist

  • Migrations reviewed for RLS + GRANT coverage.
  • Doctor probes green on a fresh install and on the upgrade path.
  • Backup + restore rehearsed against the release image.
  • SBOM published; cosign signatures verified.
  • Release notes + upgrade notes drafted.