X-Ray Integration — Overview

Status: unreleased, beta-gated. This walkthrough documents pull request "X-ray integration" (yasser/desktop-apis-reorganized, PR #370) against the Dentolize monorepo, together with its companion pull request in the separate xolize-core repository ("Feature/xray integration", PR #6) which ships the actual desktop application this feature depends on. Nothing here is live for ordinary customers yet — even once merged, the feature only activates for companies flagged isBeta (see Rollout, Feature Flag & Observability). Everything below was verified by reading the source in both repositories and exercising the feature in a sandbox environment, not by trusting the PR description.

What this PR adds

Today, a clinic's X-ray images arrive on a computer plugged into a sensor or scanner and someone has to save the file, find it on disk, and manually upload it into the patient's chart. This change closes that gap: a clinic pairs a Windows desktop application with Dentolize, and staff can request an X-ray capture directly from a patient's chart. The image is captured by a real TWAIN scanner driver, uploaded straight to storage, and dropped into the exact slot the staff member asked for — no manual file handling.

Three pieces make this possible, spanning two repositories:

1. Access Keys (/work/repo) — a way for a clinic to issue revocable, hashed API credentials (from Account → Security) that a desktop workstation uses to authenticate itself to Dentolize's servers, scoped to specific capabilities.
2. X-Ray Acquisition (/work/repo) — a request/response workflow with a formal state machine: a staff member picks a connected "room" from a patient's X-ray screen, sends a capture request, and watches its status update live until the image lands in the patient's chart.
3. The Dentolize Bridge desktop app (xolize-core, not in this repo) — a real Electron + native TWAIN application that clinics install on the workstation connected to their scanner. It holds the Access Key, receives capture requests over a GraphQL subscription, drives the actual scanner hardware, and uploads the result. See The Desktop App & Scanner Integration — this is a full, working application, not a stub or a future promise.

Who is involved

• Clinic staff (anyone whose permission group has ACQUIRE_PATIENTS_XRAYS) — requests captures from the patient chart and watches them complete.
• Clinic administrators (anyone with MANAGE_ACCESS_KEYS or the blanket DO_ALL permission) — create and revoke Access Keys under Account → Security, one per desktop workstation/scanner.
• Whoever sets up the workstation — installs the Dentolize Bridge desktop app, pastes in the Access Key, and picks a TWAIN scanner and a branch/room.

How the pieces fit together

Clinic staff (clinic-web)             Dentolize server                    Dentolize Bridge (desktop app)
        |                                    |                                      |
        |-- requestXrayAcquisition -------->|                                      |
        |    (GraphQL mutation)             |-- xrayAcquisitionRequested (WS) ---->|
        |                                    |<---- POST .../transitions ----------|  (ACCEPTED, IN_PROGRESS, PREVIEW,
        |<-- xrayAcquisitionStatusUpdated --|                                      |   CAPTURED, WAITING_UPLOAD, UPLOADING)
        |                                    |<---- POST .../upload-intents -------|  (reserves storage quota, gets a
        |                                    |----- presigned S3 POST form ------->|   presigned upload form)
        |                                    |     (desktop app uploads directly to S3, not through the API)
        |                                    |<---- POST .../complete -------------|  (server re-downloads & verifies
        |<-- xrayAcquisitionStatusUpdated --|                                      |   the object before trusting it)

The server tracks every step in an XrayAcquisitionRequest row (plus an append-only XrayAcquisitionLog audit trail and a separate XrayUploadIntent row per upload attempt), and a cron job force-fails any request that stalls past its per-state deadline so staff are never left staring at a spinner forever. The desktop app authenticates to all of this using a short-lived lease token obtained from an Access Key, not the Access Key itself — see Access Keys & Security Model for why that split exists.

What changed since the last draft of this documentation

This documentation was previously written before the companion desktop-app pull request's source was available for review, and described the desktop app as "external, not in this repository." That was wrong — full source for a real Electron + TWAIN application exists in xolize-core#6 and is covered in depth here. Separately, the server-side Access Key and authorization model was substantially rewritten between drafts (branch name: "desktop-apis-reorganized") — access keys are now HMAC-hashed at rest instead of stored in plaintext, every access-control gap previously flagged in this documentation has been fixed, and a new lease-token layer, storage-quota system, and server-side image verification pipeline were added. See Access Keys & Security Model and For Quality for the current, re-audited picture.

Where to go next

• Walkthrough — a screenshot-driven tour of creating an Access Key and requesting a capture, captured live from the sandbox.
• X-Ray Acquisition Workflow — the request lifecycle, idempotency, and upload verification in detail.
• Access Keys & Security Model — how credentials are issued, hashed, scoped, leased, and rate-limited.
• Real-Time Status, Presence & Timeouts — how the server knows a desktop app is online, and what happens when things stall.
• The Desktop App & Scanner Integration — the companion Electron/TWAIN application, its architecture, and its own recovery/reliability story.
• Rollout, Feature Flag & Observability — the beta feature flag, what's monitored, and what a go-live requires.
• For Quality — what to test, and the residual open questions found while re-auditing this PR.