Skip to main content

Data Flow Diagrams

Visual references for the main ways data moves through Tietai. Use them to explain the platform to colleagues or to decide where a problem sits. Each diagram shows what the code does today, including the steps that are not connected.

1. Hospital message to FHIR​

Hospital HL7 message to FHIR through a Connect channel

A Connect channel receives HL7 v2 over MLLP. Before delivery it can run a preprocessing script, an optional workflow processor, the HL7 to FHIR transform and a postprocessing script. The FHIR transform runs only when the channel's transform_to_fhir property is true. With the default HL7_TO_FHIR transform, a failure does not raise an error: the engine passes the original HL7 content on to the destinations unchanged, so check what the destination received. The order-aware ORU^R01 transformer (channel property transformer_type = HL7_ORU_TO_FHIR) fails closed instead: the message gets status ERROR and raw HL7 is never forwarded as if converted. With FHIR batching on, a message shows QUEUED until the FHIR server answers, then SENT or ERROR. Destinations include an HTTP endpoint, Kafka and Parquet files.

  • ADT A01/A03/A08 and ORU R01 are generally available inputs. ORM, SIU, VXU, BAR and pharmacy messages have builders and are generally available too (tietai-connect/docs/CAPABILITY_MATRIX.md).
  • The channel does no patient matching. If you need matching, add the empi workflow node in a workflow.
  • A message carries the status ERROR when every destination failed. If at least one destination accepted it, the message keeps its delivered status and the failures are noted in its message text. Find them under Tiet · Connect → Network → Messages & DLQ. Replay and discard are available only when Connect runs in hub mode; in standalone mode the drawer is read-only.

2. Hub and spoke routing​

Hub mode: hub router, NATS backbone, spoke, dead-letter queue and replay

In hub mode the hub picks a spoke with one of seven strategies: round_robin, least_loaded, affinity, broadcast, capability, direct and random. Messages travel over NATS on tietai.<channel>.hub-to-spoke, and spokes answer on tietai.<channel>.spoke-to-hub. A message that exhausts its delivery attempts is stored in the Postgres dead-letter queue.

Find it under Tiet · Connect → Network → Mesh, Pipes and Messages & DLQ. Spoke authentication uses a service token. Mutual TLS between Connect hub and spoke is roadmap. The workflow engine's own mesh (see Run on Mesh) is a different mechanism that uses Connect as its transport.

3. Wearable data​

Wearables: provider OAuth or Apple Health import, wearables service, MQTT, Connect, FHIR and HL7 outputs

The wearables service pulls data from the provider's cloud API after the patient authorizes access through an invitation link, normalizes it, stores it in the vital_readings table and publishes it over MQTT when a broker is configured. The Vitals API and the device-data-source workflow node read vital_readings. Only Fitbit and WHOOP are collected by the running service (WHOOP also by signed webhook). Garmin, Oura, Polar, Suunto, Samsung Health and Apple Health have code in the repository that is not wired into the server. MQTT messages carry clinical_grade: false and source_type: consumer_wearable.

The hop from the wearables MQTT topics to Connect, and from there to FHIR Observations and HL7 v2.6 device messages, is not verified: Connect's FHIR and HL7 device mapping listens to its own tietai/v1/<org>/devices/... topics, and no subscriber for the wearables/... topics was found. Do not assume wearable readings reach the FHIR store. See Wearables & IoT Devices.

Manage devices under Tiet · Connect → Device Fleet.

4. Medical imaging​

Imaging sequence: Records Viewer, imaging service, PACS and vision model

Images flow PACS to the imaging service to the viewer. The imaging service is a DICOMweb proxy (QIDO-RS and WADO-RS), stores clinician annotations and KO, PR and SEG objects as imaging state, and starts AI analysis. POST .../ai/analyze returns 202 with a job id and findings stream over server-sent events. A store request (STOW-RS, POST /studies) writes to the upstream PACS. The service also has routes to index RT objects, export an SR object to FHIR (.../sr/{sop}/to-fhir), run AI automatically on a study (.../ai/auto-run) and build volume jobs.

Open Tiet · Govern → Records Viewer for DICOM studies.

5. EHDS dataset publication and access​

EHDS publication in the service provider, and contract negotiation and transfer in the dataspace connector

Publication needs an approved revision with a successful official HealthDCAT-AP Release 6 validation, and the person who publishes cannot be the person who approved. See EHDS Studio for the roles and the exact errors. Access to the data is a separate path: the dataspace connector negotiates a contract (OFFERED, AGREED, FINALIZED) and starts a transfer, and the consumer pulls through a Connect or the workflow engine data plane with a transfer token. Work in Tiet · Govern → EHDS Studio; the public catalogue needs no login.

6. Claims (US payers)​

Claims: X12 service generates and records claims; the step to the payer is not connected

The X12 service parses, validates, generates and converts X12 transactions (837P, 837I, 835, 270, 271, 276, 277, 278, 834, 820) and converts to and from FHIR R4. POST /api/v1/claims/submit records the claim and an outbound transaction with status created. It does not transmit anything: the code marks submission to the clearinghouse, resubmission and the 276 and 270 requests as not yet implemented. Clearinghouse connectors for SFTP, AS2 and REST exist as a library. Treat this flow as claim preparation and record keeping, not as payer connectivity.

7. FHIR to research (OMOP)​

FHIR to OMOP: load, run, publish, metadata and test

tietai-fhir2omop is a command-line workflow run per project, for example ./scripts/tietai-omop-code.sh --project example-img --command "/run all". It reads FHIR NDJSON from the project's input folder and loads it into DuckDB. Pipeline stages then refine the tables in numbered steps. /publish writes the final OMOP tables and the flattened source tables as CSV or Parquet under output/<format>/final and output/<format>/plain-input. /metadata writes record_traceability.csv, the source-to-OMOP trace. Publishing writes files; it does not deliver to a researcher portal.

Something unclear? Send documentation feedback by email.