Onboarding a department

Four-week phased onboarding plan for healthcare design partners. Adjust per scope (radiology-only pilot vs hospital-wide rollout) and per organisational complexity (single-CIO single-LCO authority vs multi-stakeholder governance).

Reading this against the shipped product. Every line below was graded against the code on main and the live pilot deployment on 2026-09-02; the grading is in pilot-blockers.md. Where a step depends on something that is not yet available, the step says so and names the blocker (B1, B2, …) from that register. Nothing in this plan describes a surface the product does not have.

Week 0 — Pre-deployment

Legal + compliance

BAA (Business Associate Agreement) execution. Tavrik signs as Business Associate; covered-entity counterparty signature required. BAA scope covers governance, audit, and EHR-adjacent audit-forwarding connectors. Template not yet available — the repo carries no BAA / DPA / design-partner agreement templates (B8).
Data Processing Agreement / GDPR Article 28 processor agreement for EU deployments. Tavrik acts as processor; customer is controller.
My Health Records Act 2012 (Cth) participating-organisation agreement for Australian My Health Record-system-connected customers. Tavrik’s role: audit-metadata processor.
Privacy Impact Assessment (PIA) completed by customer. Tavrik provides the technical documentation set in compliance/healthcare/.

Network + integration discovery

Network access plan: gateway → integration engine MLLPS listener, gateway → FHIR audit endpoint (if applicable). Firewall rules opened. Egress rules to LLM providers reviewed. Ports and the loopback-only binding of the services are in the on-prem VM runbook §1 and §6. Workstations must also reach the gateway’s /v1/extension/* routes for the browser extension; on the pilot shape that edge is not yet configured (B2).
Integration engine config exchange: customer provides the integration engine’s MLLPS listener hostname + port, server cert (or CA bundle for the server cert chain), and a sending-application/facility identifier to expect from Tavrik (default TAVRIK / TAVRIK_GW).
FHIR audit endpoint (optional): URL, auth kind (bearer or mTLS), CA bundle.
Operator-supplied CA bundles: customer provides PEM bundles for connector TLS validation. Stored envelope-encrypted per ADR-0035. The host must have GATEWAY_BYOK_DEFAULT_KEK_REF set before any connector config is saved (runbook §4).

Tenant scoping

Clinical-group inventory: which departments / applications get Tavrik-mediated AI access? Each maps to a Tavrik tenant (department / application; NOT individual patients per ADR-0043 Decision 5).
AI tool inventory: which clinician-facing AI tools route through Tavrik? Browser-extension targets (Claude, ChatGPT, Gemini) vs API integrations. There is no product surface yet that reports which AI tools staff are actually using (B4); this inventory is a customer-side exercise until then.
Operator-identity provisioning: hospital staff who manage Tavrik configurations get Tavrik operator accounts per ADR-0021/0022. Bootstrap operator created via ADR-0023 path (runbook §6.3); further operators via the admin API or SSO auto-provisioning (runbook §6.4).

Week 1 — Deploy

Day 1 — Gateway deployment

Deploy Tavrik on a single Linux VM as systemd units per ../operations/on-prem-vm-runbook.md. This is the pilot shape and the one that has been executed end to end. (A Kubernetes Helm chart exists under deploy/helm/tavrik and is install-smoked in CI, but it is not the pilot shape. There is no single-binary appliance build; ADR-0008 defers it.)
Configure database (PostgreSQL with RLS per ADR-0004; tenant-scoped predicates). Runbook §3 and §5.2.
Configure the KMS / KEK source per ADR-0035. Only AWS KMS is implemented (GATEWAY_KMS_BACKEND=aws); any other host runs the stub backend, which is not secure for production. A non-AWS backend is not yet available (#296, B11 — needs a ruling on the pilot shape).
Bootstrap the first (root) operator with GATEWAY_ADMIN_ALLOW_BOOTSTRAP (runbook §6.3), then create the first non-bootstrap operator per ADR-0022/0023 and set the flag to false.

Day 2 — Tenant + recognizer pack provisioning

Create initial tenant (one clinical group; radiology-AI is the typical lighthouse).
Enable the healthcare vertical pack for the tenant via the admin API (ADR-0042 + M5.A.1.B).
Verify recognizer pack registration with vertical_pack.recognizer_loaded audit event. The pack_version pin is not validated against the versions the binary ships (#300); pin the version the binary reports.

Day 3 — Connector configuration

Configure the hl7_mirth_mllps connector (HL7 v2.x ARV over MLLPS) OR the fhir_audit_https connector (FHIR R4 AuditEvent over HTTPS) OR both, per the customer’s existing audit infrastructure. These are the connector kinds the admin API and console accept (internal/admin/handlers/connectors.go).
Submit per-tenant config via the admin API (PUT /v1/tenants/{id}/connectors/{kind}) or the console /tenants/[id]/connectors page. The ConfigValidator structurally enforces TLS 1.3 minimum + (for HL7) no plaintext MLLP fallback. Then enable the policy (PUT …/connectors/{kind}/policy with {"mode":"enabled"}).
FHIR: verified live (256+ AuditEvents accepted by a catcher on 2026-09-02). MLLPS: the transport, validator and tavrik-validate-mllps CLI exist and are unit-tested against an in-process listener, but have not yet been exercised against a real integration engine (B12 — run the acceptance gate before relying on it).
Verify the connector via the admin API: GET /v1/tenants/{id}/connectors/{kind} returns the policy mode, has_credential and timestamps only. Confirm the first connector.event_forwarded event in the audit log (console /audit, filter by event type). Retry depth, DLQ depth and cursor lag are not yet exposed (B5); the runbook shows the SQL to read them meanwhile.
First enable floods history. Enabling a connector starts delivery from the beginning of the audit file, not the tail (#302, B10a). Enable on a fresh deployment, or expect the backlog.

Day 4 — Browser extension deployment

Deploy the Tavrik browser extension via enterprise MDM (Chrome Enterprise / Edge Enterprise / Firefox ESR) per compliance/extension-mdm-deployment.md. MDM policy provisions tenant identity per ADR-0040.
Verify the extension’s chrome.storage.managed read resolves to a non-empty tenant identifier on a managed test device.
Issue the per-user credential (shipped 2026-09-02, ADR-0040 amendment (a)): on the console at /tenants/{tenant_id}/extension (operator or root), “Issue MDM enrolment” mints the working JWT for the MDM ExtensionSettings jwt field (≤ 24 h, shown once); “Issue pairing code” mints a short-lived code (≤ 10 min; single-use: a second exchange of the same code is refused) the clinician pastes into the extension popup on a self-installed device. Same via the admin API: POST /v1/tenants/{tenant_id}/extensions/enrollments / …/extensions/pairing-codes with {"user_id": "<uuid>"}. Both gateway and gateway-admin must carry the same GATEWAY_EXTENSION_JWT_KEK_REF (docs/operations/on-prem-vm-runbook.md §4). Plan for the 24 h JWT lifetime: a workstation idle over a weekend needs a fresh enrolment.
Supported browsers for the pilot: Chromium-based — Google Chrome Enterprise and Microsoft Edge (force-install via ExtensionInstallForcelist, managed config via ExtensionSettings). Firefox ESR is not in the pilot offering: the Firefox build and manifest exist (ADR-0041 Decision 2) but its MDM path and service-worker parity have never been exercised on a managed fleet. It is scheduled as a post-pilot item with a lead time of one build cycle plus one managed-fleet test cycle (≈ 2 weeks from a named requirement); a partner that needs Firefox ESR in weeks 0–4 should say so in week 0. Safari is out of scope (ADR-0040).

Day 5 — Smoke test

Clinician on a test workstation visits ChatGPT / Claude / Gemini through the extension.
Paste a synthetic HL7 message or FHIR resource fragment (sample synthetic data only; never real PHI).
Verify: PHI categories detected; policy decision rendered; categorical audit event flowing to integration engine.
Status: exercised end to end on 2026-09-02 against the deployed instance (docs/healthcare/demo-script.md §10): enrolment via pairing code, pre-submit tokenisation of NAME / MRN / DOB in the browser, categorical-only evaluate call, audit events on the console. The browser-side recognizers now run the core set plus the healthcare pack (Medicare tokenised in the browser, #342), and the gateway answers CORS for extension origins itself (GATEWAY_EXTENSION_ALLOWED_ORIGINS, ADR-0040 amendment (c), #333/#337) — no edge rule needed.

Week 2 — Pilot

Operator activities

Discovery view (shipped 2026-09-02, B4): /tenants/{tenant_id}/extension → “AI tools in use” — observations by tool, users seen, top PHI categories, for the last 7 days (GET …/extensions/summary?window=7d, up to 90 d). This is the week-2 conversation artefact: which AI tools staff actually use through the extension and what they paste. The same page lists every enrolled extension with last activity and a Revoke action (see compliance/extension-mdm-deployment.md §Revoking a device).
Daily review of audit-event flow into the integration engine. Verify expected event volume; investigate any connector.event_failed events (console /audit, filter by event type) and any rows in the connector_retry / connector_dlq tables (runbook §“Integration engine outage”). Note that connector.event_dlq is declared in the event enum but is not emitted by the dispatcher; a DLQ transition appears only as a dispatch: event moved to DLQ line in the admin journal and a row in connector_dlq.
Review connector.client_cert_expiring early-warning emissions (none expected in week 2; the probe catches sub-14-day expiries from initial config). Emitted by both writers when an mTLS client cert is configured — the MLLPS writer on construction and on each write, the FHIR writer before each batch — rate-limited to one per 24 h per writer instance.
Review per-tenant detection-coverage signals. Per-request attributes exist on inspect.* events (pii.categories_detected); an aggregate per-tenant view is not yet available (B4).

Clinical activities

Pilot clinical group exercises target AI tools in normal workflow. NO production patient data — pilot uses synthetic / de-identified clinical cases.
Clinicians report friction points (over-aggressive PHI detection, missed-detection examples).
Tavrik team reviews via screen-share or operator-side audit-log review.

Compliance activities

Compliance team reviews audit-event flow in the customer’s integration engine alongside other clinical-system audit. Verify cardinality, dedupe behavior (UUIDv7 event_id as MSH-10 for SIEM dedupe; FHIR AuditEvent id). The MSH-10 claim is untested against a live engine (B12).
Verify HIPAA Security Rule §164.308(a)(1)(ii)(D) control evidence is satisfied via the audit-event stream.

Week 3 — Tune

Per-tenant recognizer-pack policy: per-category disable per ADR-0042 §6 (shipped 2026-09-02, B7). On the console /tenants/{tenant_id}/vertical-packs → Categories on the healthcare row: untick the categories a clinician reports as over-detected (e.g. healthcare/medicare_number_au); the recognizer stops running for that tenant within 60 s. Same via PUT …/vertical-pack-policies/healthcare with disabled_categories. Audited as vertical_pack.policy_updated with the old and new sets.
Per-tenant inspector policy (ADR-0037 Decision 6): shipped 2026-09-02 (B7) as the Inspectors section of /tenants/{tenant_id}/policy (GET/PUT/DELETE …/inspector-policies/{inspector}). Tuning inspectors (injection, jailbreak, leak scan, outbound redaction, Purview labels) are operator+ to disable or fail-open; validate / restore_tokens cannot be relaxed; pii_redact and opa_policy are root-only to disable or fail-open and the change is audited with guarantee_removed: true — agree the SIEM alert on that attribute in week 1.
Per-tenant routing policy (ADR-0038): tables are read by the router, but there is no admin surface (post-pilot). The pilot uses the global routes file plus the rego model allowlist.

Review false-positive rate (categorical detections that didn’t carry PHI in customer cases) via audit exports. Recognizer activation (server-only vs server+extension) is a pack-manifest property, not per tenant.
Review false-negative rate (PHI missed). Flag to Tavrik product team for next recognizer-pack iteration (additive to v0.7.0+).

Verify all in-scope audit-event types flow correctly. Domain-prefix subtype filtering working in the integration engine.
For FHIR R4: verify the Tavrik-issued CodeSystem URN is registered in the audit aggregator’s CodeSystem registry per compliance/healthcare/fhir-audit-codes.md.

Expansion

Add second tenant for adjacent clinical group (ED, ICU, oncology, etc.). Independent config; no cross-tenant data flow per ADR-0036 §5 RLS. Verified with two tenants on 2026-09-02.

Week 4+ — Steady state

Quarterly cert rotation: operator-driven; see ../runbooks/healthcare-connector-operations.md §“Client cert rotation”. The procedure exists; it has not yet been exercised through a live rotation cycle.
Annual CA bundle review: hospital integration engine’s CA chain rotates as part of normal IT operations.
Continuous audit-event monitoring: customer SIEM / audit aggregator should alert on:
- connector.event_failed rate, and growth of the connector_retry / connector_dlq tables (there is no connector.event_dlq emission and no DLQ-depth endpoint yet — B5)
- connector.mllps_handshake_failed / connector.fhir_endpoint_unreachable rate (transport health; one event per failed delivery attempt until B10b aggregates them)
- connector.client_cert_expiring (operator-runbook trigger; resolves with cert rotation)
- hash-chain verification failures: POST /v1/audit/verify returning verified: false (procedure in ../runbooks/audit-log-tamper-investigation.md). There is no scheduled seal and no audit.seal_verify_mismatch emission today; the daily Merkle seal scheduler (M3.7.B) has not shipped (post-pilot register).
Quarterly compliance evidence review: align with HIPAA Security Rule §164.308(a)(8) annual evaluation cadence.
Recognizer pack updates: Tavrik ships additive recognizer-pack minor versions (v0.7.0+). Customer reviews + accepts; rollout via per-tenant pack_version policy.

Stakeholder responsibilities

Stakeholder	Owns
Tavrik product team	Gateway version updates, recognizer-pack updates, connector framework evolution
Hospital biomed engineering	Gateway deployment + upgrades per the on-prem VM runbook (§8), host backups (§10), network access policy, integration engine config exchange
Hospital compliance / privacy	BAA execution, audit-event review cadence, PIA maintenance
Hospital IT / SecOps	Cert rotation, CA bundle maintenance, MDM policy for the browser extension
Hospital clinical group leads	AI tool selection per clinical group, clinician feedback collection
Hospital risk management	Incident-response runbook integration; correlate Tavrik audit events into existing IR workflow

Escalation paths

Tavrik product support: dedicated channel during design-partner phase; SLAs per the customer agreement.
Tavrik incident response: integration-engine outages affecting audit-event delivery → Tavrik investigates dispatcher / retry / DLQ state; customer investigates integration-engine state.
Mutual escalation: a hash-chain verification failure (POST /v1/audit/verify → verified: false) escalates both ways; investigation runs per ../runbooks/audit-log-tamper-investigation.md.

Sign-off

The design-partner onboarding is considered complete when:

✅ BAA + DPA / equivalent agreements executed
✅ Production deployment serving real clinical workflow for ≥30 days
✅ Audit events landing in customer integration engine with operator-confirmed cardinality
✅ Zero unresolved rows in connector_dlq (checked by SQL until B5 exposes DLQ depth)
✅ POST /v1/audit/verify over the pilot window returns verified: true (see the tamper runbook for how to select the window)
✅ Operator runbook validated through at least one cert rotation cycle
✅ Compliance team sign-off on the audit-event evidence stream

Beyond design-partner: move to standard customer agreement; quarterly business review cadence.

References

README.md — healthcare-vertical overview
architecture.md — deployment topologies
pilot-blockers.md — what is and is not shipped, graded line by line against this plan
../operations/on-prem-vm-runbook.md — the pilot deployment shape
../runbooks/healthcare-connector-operations.md — day-to-day runbook
../runbooks/audit-log-tamper-investigation.md — hash-chain verification and escalation
../../compliance/healthcare/ — compliance posture