Concepts

Medblocks has a small number of moving parts. Once you understand them, the rest of the platform reads naturally.

The flow is: Connectors bring data in from external systems → an Agent writes Mappings from that data into the Tables and Columns you defined → you Export those Tables to your warehouse or downstream systems, with Provenance back to every source row.

Connectors

A Connector is a configured link to a single external system that holds patient data — an EHR, an HIE network, a payer, a wearable feed, a document store. Each Connector knows how to authenticate against that system, pull data on a schedule (or stream it), and land it in your warehouse in its native shape.

We ship Connectors for the standardised regulated APIs that matter most:

EHRs through FHIR (US Core, USCDI) and CCDA.
HIE networks like CommonWell, Carequality, and the emerging TEFCA / CMS-aligned networks.
Payers through CMS-9115 Patient Access and Provider Directory APIs.
Patient-mediated connections — a patient receives an SMS link, authorises access in about 5 minutes, and contributes their own records and wearables.
Documents and unstructured feeds — PDF exports, fax inboxes, scanned notes.

Connectors do not transform data. They land it as-is, with the original codes, identifiers, and structure preserved — into tables inside Medblocks, one row per FHIR resource, claim line, document, or observation, with the original payload kept intact alongside indexed columns for the fields you’ll query most. The data is append-only and timestamped, and you (and the Agent) can query it directly with SQL during exploration. Transformation happens later, in Mappings, where it can be reviewed and versioned.

If the same patient shows up across multiple Connectors (an EHR record, a payer claim, a wearable feed), they remain separate at the Connector level. Reconciliation happens at the Table level.

Tables

A Table is the answer to a question, expressed as a schema. You define what you want to know — Medblocks figures out how to compute it.

Examples of Tables a team might define:

Patient Roster — one row per patient, with name, DOB, current PCP, last visit, attribution status.
Diabetes Panel — one row per diabetic patient, with last HbA1c value, last reading date, medications, missed appointments in the last 90 days.
Care Gaps — one row per (patient, gap) pair, with the measure, the data points that triggered it, and when it was last evaluated.

Tables are materialised inside Medblocks alongside the raw Connector data, and update in real time as new data lands. You can query them directly inside Medblocks, or push them out to your own warehouse via Exports — which is what most teams do for analytics at scale.

Columns

A Column is a single field on a Table. Columns are where you express intent in plain English alongside the type.

A Column has:

A name — last_hba1c_value.
A type — numeric, date, text, boolean, code, etc.
A description — the prompt the Agent reads to decide what to compute. The more specific, the better the Mapping. “Most recent HbA1c lab result, in %, from any source. Prefer LOINC 4548-4 but accept local codes that mean the same thing. Ignore point-of-care fingerstick estimates.” is a good description; “HbA1c” is not.
Optional constraints — value ranges, allowed code systems, units.

You do not write SQL for a Column. The Agent does that, and you review the result.

Mappings

A Mapping is the deterministic SQL that takes data from one or more Connectors and produces one Column (or sometimes a whole Table). Mappings are the artefact the Agent produces and the artefact our team reviews.

Mappings are:

Deterministic — same input, same output. No LLM is in the query path at runtime.
Versioned — every change to a Mapping is a new version with a diff against the prior one.
Inspectable — you can read the SQL, run it yourself, and see exactly which input rows fed which Column values.
Cheap to run — it is just SQL.

This is the property that makes Medblocks scale to terabyte datasets where chat-over-data approaches collapse. Tokens are spent once, when the Mapping is being written or improved — not on every query.

The Agent

The Agent is the long-running coding agent that writes and improves Mappings. When you define a new Column, the Agent does not answer immediately. It runs inside a secure HIPAA-compliant environment for hours or days, exploring your actual data:

Profiles the relevant Connector data — which code systems are present, which fields are populated, which terminologies are in use.
Writes candidate SQL Mappings.
Tests them against your data, looking for null rates, distribution anomalies, and disagreement between Connectors.
Iterates until the Mapping is robust on your dataset, not a textbook one.
Submits the Mapping for review.

The Agent is also responsible for self-improvement. If the shape of incoming data changes — a new code system shows up, a Connector starts populating a previously empty field, a payer changes their schema — the Agent detects the drift and runs the same loop again.

Review

Three things in Medblocks are gated behind a human review step. Each one is a different kind of decision the Agent can get wrong, so each is reviewed differently.

Mapping reviews

Every Mapping is reviewed by the Medblocks team before it goes live on your data. We read the SQL, check the test results the Agent produced, and look for the failure modes a coding agent is most likely to miss — silent code-system mismatches, unit confusion, timezone drift, cohort definitions that look right but exclude an edge case.

You can also review Mappings yourself. The SQL is yours; nothing is hidden behind a vendor black box.

Unstructured data reviews

When the Agent extracts a structured value from a PDF, scanned note, or free-text field — say, pulling an HbA1c result out of a discharge summary — every extraction comes with a confidence score. If the score is below a configurable threshold, the extraction goes into a review queue instead of straight into the Table.

A reviewer (yours or ours, depending on your plan) sees the original document with the relevant span highlighted, the proposed structured value, and accepts, edits, or rejects it. The decision is logged as part of the cell’s provenance, so you can always tell which values came from a high-confidence automated extraction vs. a human-confirmed one.

Record matching reviews

When the same patient, encounter, or observation arrives from multiple Connectors, Medblocks tries to recognise it as the same thing and combine the records — that’s how a single last_hba1c cell can be backed by both an EHR result and a payer claim. Each candidate match comes with a confidence score based on identifier overlap, demographic agreement, and value alignment.

High-confidence matches are combined automatically. Below a configurable threshold, the match is held for human review: the reviewer sees both records side by side, with the agreeing and conflicting fields called out, and decides whether they’re the same, different, or need to be split further. Like extraction reviews, the decision is recorded in provenance, and the same pair won’t be re-asked unless the underlying data changes.

Provenance

Every cell in every Table carries provenance: which input rows produced this value, through which Mapping version, at what time. Click into a cell and you see the chain back to the original FHIR Observation, claim line, or PDF page.

When the same data point arrives from multiple Connectors — an HbA1c value reported by both the EHR and the payer — the Table merges them into a single cell if they agree, and surfaces the conflict if they don’t. Either way, every contributing Connector is visible.

This is what makes the answers usable for clinical and financial decisions. “The number is 7.2” is not enough; “the number is 7.2, from the lab result on 2026-03-14, from the Epic Connector, mapped through Mapping v4” is.

Exports

An Export is how data leaves Medblocks. Most teams have a data warehouse, a FHIR server, or a downstream system that’s already wired into their BI tools, models, and clinical workflows. Exports push data into those systems on a schedule.

You can export either:

Tables — the curated, mapped output you defined. This is what most analytics workloads use.
Raw Connector data — the untransformed tables a Connector lands. Useful when a downstream team wants to do their own modelling, or when another system (a FHIR server, a research data lake) needs the original payloads with no Medblocks-specific shape applied.

Both can be exported side by side from the same workspace.

Supported destinations:

Object storage — S3, GCS, Azure Blob. Write Tables out as Parquet, CSV, or NDJSON, partitioned the way your warehouse expects. From there, Snowflake, BigQuery, Databricks, Redshift, or any warehouse with a copy-from-object-storage path can ingest them.
FHIR servers — push Tables back out as FHIR resources (or the underlying Connector data, unchanged) to any FHIR R4 server. Useful when the consumer is another clinical system rather than an analyst.
Direct database writes — Postgres, MySQL, SQL Server, and the warehouses above, when you’d rather Medblocks INSERT or MERGE than have you ingest a file.
Webhooks and event streams — for row-level deltas, fire a webhook or push to Kafka/Kinesis/PubSub when a Table cell changes.

Exports run on the same real-time cadence as the Tables they read from. If a new lab result lands and changes the last_hba1c cell, the next Export tick reflects it. You configure the cadence per Export — sub-minute for streaming destinations, hourly or daily for batch warehouse loads.

Provenance travels with Exports. Every exported row carries the same Mapping version and source-row references it had inside Medblocks, so you can trace a number in your BI dashboard back to the original FHIR Observation without leaving the warehouse.

Putting it together

A typical project looks like this:

Set up Connectors for the systems you care about. Data starts landing into tables inside Medblocks.
Define Tables and Columns for the questions you need answered. Write good Column descriptions.
The Agent builds Mappings. Our team reviews them. You review them too if you want.
Tables go live and update in real time as new data lands.
Configure Exports to push Tables and/or raw Connector data to your warehouse, FHIR server, or downstream systems.
Data drifts; the Agent self-improves; reviews repeat.

If you are ready to try it, the Quickstart walks through this end to end in about ten minutes.