For Stakeholders

Status: pre-release, beta-gated. This feature is not deployed to customers and, even once merged, only activates for companies explicitly flagged as beta tenants. This page summarizes impact, risk, and dependencies for planning purposes.

Why it matters

Manual X-ray upload is a recurring friction point in dental practice workflows — someone has to physically move a file from an imaging PC into the patient record. This change is a complete, working, two-repository integration that removes that step entirely for clinics with a compatible desktop application: the clinic-facing half in this repository, and a real Electron + native TWAIN desktop application in a companion repository (xolize-core#6). It also lays a general-purpose foundation (Access Keys, scoped API access, lease-based device authorization) that future desktop/hardware integrations can reuse — this isn't X-ray-specific plumbing, it's a first instance of a pattern.

Scope of this change

• New database tables (AccessKey, XrayAcquisitionRequest, XrayAcquisitionLog, XrayUploadIntent) and two new permissions (ACQUIRE_PATIENTS_XRAYS, MANAGE_ACCESS_KEYS).
• New GraphQL queries/mutations/subscriptions for the capture lifecycle and for managing Access Keys, plus eight REST endpoints for the desktop app to call, all behind rate limiting.
• A new UI surface in Account → Security (Access Keys, admin-gated) and additions to the patient X-ray screen, plus a new Logs page.
• A background cron job that force-times-out stalled requests, expires abandoned uploads, refunds storage quota, and cleans up orphaned S3 objects.
• A full companion desktop application (10-language UI, auto-update, native scanner driver integration, its own end-to-end test suite that runs live against the shared sandbox).
• A Prometheus alert set and dashboard integration purpose-built for this feature's rollout, plus go-live runbook updates.
• The feature is gated by FEATURE_XRAY_ACQUISITION, targeting only isBeta companies, with an independent kill switch.

What changed since the last version of this documentation

An earlier draft, written before the companion desktop-app pull request's source was available for review, incorrectly described the desktop application as "external, not in this repository" and flagged five specific, verified access-control gaps as release blockers (plaintext key storage with no hashing, a cross-tenant key-deletion bug, unauthenticated key enumeration, cross-tenant read access to acquisition records containing patient PHI, and an ungated Access Keys UI). All five have since been fixed as part of a security-focused rewrite on this same branch (evidenced by the branch name, "desktop-apis-reorganized"): keys are now HMAC-hashed at rest, deletion is company-scoped and is actually a reversible revoke, listing requires authentication and a dedicated MANAGE_ACCESS_KEYS permission, the two previously-open record queries are now company- and branch-scoped, and the UI is gated behind the same permission as the backend. A fresh, independent re-audit of the current code (documented in detail in Access Keys & Security Model and For Quality) did not surface a comparable severity of issue.

Current risk summary

1. No physical-hardware validation yet. The desktop repo's own acceptance documentation states the real-scanner validation matrix is entirely un-run as of this PR — validated so far only against TWAIN's reference sample source and simulated E2E captures. This is the most material open item before a real clinic pilot: it's a hardware-integration risk, not a security or data risk.
2. Unsigned installer. The desktop app currently ships unsigned, explicitly framed by its own team as a temporary pilot-only state — expect Windows SmartScreen friction during any pilot rollout until code signing is added.
3. Coarse-grained scopes. All three Access Key scopes are meaningful and enforced, but there's no way today to issue a narrower key than "full desktop capability" — a minor design limitation, not a vulnerability, since the UI only ever offers the all-or-nothing "Desktop App" grant in practice.
4. A cosmetic translation bug persists (an untranslated i18n key visible as a column header in the Logs page) — cosmetic only, flagged for a quick fix, not a blocker.

None of the items above require anything exotic to evaluate — they follow directly from reading the current permission configuration, resolver code, and the desktop repo's own acceptance documentation. Full detail is in Access Keys & Security Model, The Desktop App & Scanner Integration, and For Quality.

Dependencies / go-to-market implications

This is now a genuinely two-sided, both-halves-exist capability — unlike the earlier draft's understanding, launch communication does not need to hedge on "a separate, unbuilt desktop app." It does still need to account for: the beta feature-flag gate (this isn't turning on for the general customer base at merge time), the pending real-hardware validation work, and the unsigned-installer pilot framing. See Rollout, Feature Flag & Observability for the operational go-live checklist.