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
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
empiworkflow node in a workflow. - A message carries the status
ERRORwhen 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
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
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
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
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)
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)
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.
Related
Something unclear? Send documentation feedback by email.