GroundWork: Offline-First Clinical AI Workflows for Community Health Workers

An interoperable orchestration layer for frontline healthcare — built for environments where existing infrastructure assumptions fail.

Executive Summary

GroundWork is a deployable healthcare workflow orchestration system designed from the ground up for Community Health Workers (CHWs) operating in low-resource, low-connectivity environments — the settings where the majority of the world's healthcare interactions actually occur.

GroundWork is an operational layer — a composable, standards-compliant, AI-powered infrastructure system that takes fragmented, multilingual, multimodal clinical inputs from frontline workers and converts them into structured, interoperable healthcare artifacts, then reliably dispatches those artifacts to backend systems even when connectivity is absent.

Target users: Community Health Workers, ASHA workers, frontline field staff, rural health practitioners, NGO health teams, and mobile clinic operators in low-to-middle income country (LMIC) environments.

Target environments: Settings with intermittent or absent internet connectivity, no access to structured EHR systems, multilingual patient populations, handwritten clinical documentation, and minimal desktop infrastructure.

GroundWork at a Glance

GroundWork is an offline-first healthcare workflow infrastructure system for Community Health Workers operating in low-resource environments.

Layer	Components
Inputs	Multilingual free text · Handwritten clinical documents · Multimodal clinical artifacts (RDT strips, device readings, wound images)
Intelligence	AI extraction · Patient history injection · Deterministic safety upgrades · Terminology normalization (LOINC / SNOMED / RxNorm)
Outputs	FHIR R4 artifacts · Interoperable clinical workflows · Queue-backed synchronization
Infrastructure	Offline-first architecture · 10+ MCP healthcare tools · A2A skills · Idempotent dispatch · Retry semantics · ~120 passing tests

End-to-end pipeline:

Clinical Input
    ↓
AI Interpretation
    ↓
Structured Workflow State
    ↓
FHIR Generation
    ↓
Reliable Dispatch

No paragraph-length explanation required. This is the system.

Demonstrated Validation

GroundWork has been validated end-to-end across all primary workflow paths:

~120 passing tests covering triage, OCR, FHIR generation, dispatch, and synchronization
End-to-end workflow execution across all four clinical workflow paths
FHIR bundle generation: 4 Observation, 3 MedicationRequest, 1 RiskAssessment resources produced
Multilingual handwritten OCR: Kannada prescription successfully processed through two-stage pipeline
Clinical image extraction: Pulse oximeter, thermometer, and glucometer readings extracted from photographs
Queue fallback validation: Offline persistence to SQLite confirmed under simulated connectivity failure
Idempotency testing: Duplicate dispatch correctly rejected; no duplicate resource creation
Synchronization verification: Retry worker confirmed draining queue on reconnection

Healthcare Problem Landscape

The Community Health Worker Reality

Community Health Workers are the primary healthcare interface for an estimated 1–2 billion people globally. In India alone, over 1 million ASHA workers conduct frontline health outreach in environments that bear no resemblance to the hospital settings that most healthcare technology is designed for.

Their operational reality includes:

Connectivity failures: Rural health visits frequently occur in areas with 2G signals, no signal, or intermittent mobile data. A workflow that requires a live API call to function is a workflow that fails during a patient encounter.
Handwritten prescriptions: Referral slips, prescription documents, and lab report forms are predominantly handwritten, in regional scripts, in abbreviated clinical shorthand that resists naive OCR extraction.
Multilingual patient communication: Clinical encounters in India span dozens of regional languages. A patient presenting with chest pain in Kannada, a prescription written in Hindi, and a referral slip in English are all part of the same clinical episode.
Fragmented healthcare systems: Patient history exists across disconnected primary health centers, district hospitals, private practitioners, and informal care points. There is no unified record. There is no queryable EHR.
Delayed synchronization: Data collected during a field visit may not be transmittable until a CHW returns to a connectivity zone hours or days later. Records must be generated, stored, and dispatched asynchronously.
Incomplete patient histories: Chronic condition context — TB status, COPD diagnoses, hypertension history — exists in fragmented paper records or not at all. Without history, triage decisions are made blind.

Why Traditional Systems Break Here

Traditional healthcare AI and workflow systems are implicitly designed for a specific operational context: a hospital or clinic with stable internet, an EHR system generating structured data, English or near-English clinical documentation, and trained administrative staff.

Remove any one of those assumptions — connectivity, structure, language, infrastructure — and most systems degrade or fail outright. In frontline CHW environments, all four assumptions fail simultaneously.

The interoperability gap compounds this: even when systems do collect data, outputs are frequently not standards-compliant FHIR resources. They are PDF reports, free-text notes, or proprietary JSON blobs that cannot be consumed by downstream clinical systems. Data collection without interoperability is not infrastructure — it is digital paper.

Why Generative AI Is Necessary

The Limits of Rule-Based Systems

A rule-based system can map a structured input field to a severity tier. It cannot handle a Kannada symptom description that varies in phrasing depending on dialect, education level, and health literacy. It cannot extract medication names from handwritten abbreviations. It cannot interpret a malaria RDT strip image and produce a SNOMED-coded clinical finding.

The clinical inputs CHWs routinely work with are:

Multilingual free text: Symptom descriptions in regional languages, mixed scripts, non-standardized vocabulary
Handwritten prescriptions: Variable handwriting quality, regional language drug names, dose abbreviations, multi-drug regimens crammed into small referral slip fields
Multimodal clinical images: RDT strips in variable lighting, pulse oximeter displays photographed at angles, thermometer readings, glucose meter screens, wound presentations, edema photographs
Noisy health records: Incomplete, partially legible, structurally inconsistent patient history documents
Context-dependent severity: A fever of 38.5°C means one thing in an otherwise healthy 25-year-old; it means something different in a known TB patient with a recent respiratory event

Rule-based systems can handle clean structured inputs. They cannot handle the actual data that frontline healthcare generates.

AI as Workflow Substrate, Not Endpoint

The critical architectural distinction in GroundWork is that AI outputs are not the system's outputs. AI outputs are structured intermediate representations that become inputs to the workflow layer.

The pipeline is:

Raw clinical input (image / free text / document)
    ↓
AI extraction + multimodal interpretation
    ↓
Structured intermediate representation (severity score, coded findings, extracted medications)
    ↓
Deterministic enrichment (history injection, severity upgrades, escalation rules)
    ↓
FHIR resource generation (Observation, Condition, MedicationRequest, RiskAssessment)
    ↓
Validated bundle construction
    ↓
Dispatch + synchronization (live or deferred)

AI handles interpretation — converting unstructured, multilingual, multimodal inputs into typed clinical data. Deterministic logic applies safety-critical escalation rules (COPD + low SpO2 = mandatory escalation; TB history + fever = automatic severity upgrade). FHIR generation converts enriched data into interoperable artifacts. The dispatch layer ensures reliable delivery even under connectivity failure.

GroundWork does not expose AI outputs to clinicians as conclusions. It converts AI outputs into structured data that the workflow layer acts on deterministically.

System Philosophy

Core Principle: Operational Continuity Under Constraint

GroundWork is built around a single governing principle: healthcare infrastructure should remain operational under the conditions where it is most needed.

This requires architectural decisions that run counter to most healthcare software design:

Offline-first, not offline-capable: Offline-capable means the system degrades gracefully. Offline-first means the system is designed to operate primarily without connectivity, treating connectivity as an enhancement rather than a dependency.
Deployability over elegance: The system must be deployable without Docker orchestration, without cloud-native infrastructure teams, without managed Kubernetes clusters. Simplicity of deployment is a clinical safety requirement.
Low cognitive burden: A CHW conducting a field visit cannot context-switch into a complex multi-tab workflow. The interaction surface must be minimal. The intelligence must be in the backend.
Deterministic safety overlays: AI-generated severity scores are not sufficient for safety-critical clinical escalation. Deterministic rules based on known patient history must override probabilistic AI outputs when evidence warrants it.
Standards compliance as default: Every output must be a valid healthcare artifact — FHIR R4 resources, LOINC-mapped vitals, SNOMED-coded symptoms, RxNorm medication identifiers. Non-compliant outputs cannot integrate into downstream systems.

What GroundWork Is Not

Not a chatbot. GroundWork has no conversational interface. It executes structured clinical workflows.

Not an EHR. GroundWork does not store longitudinal patient records. It retrieves FHIR Condition resources from existing systems, uses them as workflow context, and dispatches new FHIR resources back.

Not a diagnostic system. GroundWork triages, escalates, extracts, normalizes, and dispatches. Clinical judgment remains with the CHW and the clinical hierarchy above them.

Not a dashboard. GroundWork executes workflows.

End-to-End Clinical Workflows

Workflow 1: Text Triage

CHW enters symptom description (any supported language)
    ↓
Frontend sends to GroundWork MCP server
    ↓
extract_triage called
    ↓
Llama 3.3 70B: multilingual extraction
    → severity score
    → referral flag
    → LOINC-mapped vitals
    → SNOMED-coded symptoms
    ↓
Structured triage output returned
    ↓
dispatch_fhir_bundle called
    → Observation resources generated
    → RiskAssessment generated
    ↓
If connectivity available: direct dispatch to FHIR server
If connectivity unavailable: SQLite queue persistence
    ↓
Background retry worker (30s interval)
    ↓
Idempotent dispatch on reconnection

Workflow 2: Prescription OCR

CHW photographs prescription / referral slip
    ↓
Image uploaded to frontend
    ↓
triage_document_image called
    ↓
Stage 1: Llama 4 Vision — pure OCR extraction
    → raw text from handwritten document
    → preserves original script and abbreviations
    ↓
Stage 2: Llama 3.3 70B — structured clinical interpretation
    → medication names → RxNorm normalization
    → dosage extraction
    → route and frequency
    → clinical condition inference
    ↓
build_medication_bundle called
    → MedicationRequest resources
    → Condition resources
    → RiskAssessment
    ↓
dispatch_medication_bundle called
    → live dispatch or SQLite queue fallback

Workflow 3: Clinical Image Analysis

CHW photographs clinical device / finding
(malaria RDT / pulse oximeter / thermometer / glucometer / wound / edema)
    ↓
analyze_clinical_image called
    ↓
Llama 4 Vision: image-type detection + structured extraction
    → device type identified
    → reading extracted (SpO2 %, temperature °C, glucose mg/dL, RDT band pattern)
    → finding coded to SNOMED where applicable
    ↓
Structured schema output compatible with triage workflows
    ↓
Output injected into triage pipeline or dispatched directly as Observation
    ↓
FHIR Observation resource generated
    → LOINC code mapped to reading type
    → value + unit structured
    → clinical context preserved

Workflow 4: History-Aware Triage

CHW initiates triage with patient ID
    ↓
extract_triage_with_history called
    ↓
Step 1: get_patient_history
    → FHIR Condition resources retrieved from server (or local cache)
    → SHARP extensions applied for context propagation
    ↓
Step 2: History injected into triage context
    → Known conditions: COPD, TB, hypertension, diabetes
    → Recent events: respiratory episodes, medication changes
    ↓
Step 3: AI triage with enriched context
    → Severity score computed with history awareness
    ↓
Step 4: Deterministic severity upgrades applied
    → COPD + SpO2 < 92%: mandatory escalation regardless of AI score
    → TB history + fever: automatic severity upgrade
    → Hypertension + chest symptoms: referral flag forced
    ↓
Final severity output: hybrid AI + deterministic
    ↓
FHIR bundle generation + dispatch

Competitive Analysis

Dimension	Typical Health Chatbot	Hospital Dashboard / EHR	GroundWork
Connectivity assumption	Stable internet required	Stable internet required	Offline-first; designed for zero-connectivity operation
Input types	Structured text	EHR-structured data	Free text, handwritten documents, clinical images
Language support	English-primary	English-primary	Multilingual; regional language support
Output format	Free text / proprietary	Proprietary EHR format	FHIR R4, LOINC, SNOMED, RxNorm
Standards compliance	Absent	Varies; often proprietary	Full FHIR R4 with terminology normalization
Target environment	Hospital / clinic	Hospital / clinic	CHW field settings, rural clinics, mobile health
AI role	Conversational interface	Analytics / reporting	Workflow substrate; input understanding layer
Patient history	Not incorporated	EHR-resident	FHIR-retrieved; deterministically injected
Safety model	None	Clinical staff oversight	Deterministic severity upgrades over AI output
Dispatch reliability	N/A	Network-dependent	Idempotent, queued, retry-guaranteed
Deployability	SaaS dependency	Hospital IT infrastructure	Lightweight; SQLite; no cloud-native dependencies

The architectural differentiation is not incremental. GroundWork solves a structurally different problem from hospital-oriented healthcare AI — it optimizes for the environments where healthcare AI currently provides no value because existing systems cannot function there.

Feasibility

Privacy

GroundWork does not store patient data beyond the operational lifetime of the sync queue. Patient records are generated as FHIR bundles, dispatched to the FHIR server, and removed from the queue on successful dispatch. Compliance with applicable frameworks (DPDP Act 2023 in India, GDPR for European deployments) is achievable within this architecture.

Human Oversight

GroundWork is explicitly not a diagnostic system. Every severity output is a triage signal, not a clinical conclusion. The CHW remains the human decision-maker at the point of care. The deterministic severity upgrade rules are auditable, documented, and adjustable by clinical governance teams without model retraining.

Interoperability

FHIR R4 compliance means GroundWork outputs are consumable by any FHIR-capable system: district health information systems (DHIS2 with FHIR adapter), national health repositories, telemedicine platforms, and hospital EHRs. No proprietary integration layer is required.

Constrained Deployment

The AI stack (Groq API with Llama models) requires connectivity for inference. In fully offline scenarios, inference cannot occur — addressed in the roadmap via edge model deployment. The offline persistence layer ensures bundles generated before connectivity loss survive and dispatch on reconnection. Partial connectivity (periodic sync windows) is sufficient for operational continuity.

Standards and Safety

LOINC, SNOMED CT, and RxNorm are openly licensed for use in health applications. FHIR R4 is an HL7 standard with broad implementation support. The deterministic safety overlay is clinically reviewable code, not a black-box model.

Potential Impact

Workflow Continuity at Scale

The 1+ million ASHA workers in India collectively conduct hundreds of millions of patient encounters annually. Standardized, FHIR-compliant data from CHW encounters would enable disease surveillance, treatment pattern analysis, and resource allocation in ways that current fragmented, non-interoperable CHW data cannot support.

Reduced Manual Burden

Prescription transcription, triage form completion, referral document preparation, and patient record entry are significant sources of CHW time expenditure. GroundWork's OCR, triage extraction, and FHIR generation pipelines automate the most labor-intensive documentation steps.

LMIC Deployment Relevance

GroundWork's architecture is specifically suited to LMIC deployment: no dependency on stable infrastructure, multilingual from the ground up, offline-first by design, standards-compliant for integration with national health systems. This is not a system adapted for low-resource environments; it is a system designed for them.

NGO and Public Health Integration

GroundWork's FHIR output layer is directly compatible with the data exchange requirements of organizations like WHO, MSF, and national public health programs that increasingly mandate FHIR-based interoperability for program data. NGO field teams using GroundWork generate compliance-ready health data as a byproduct of their clinical workflows.

Telemedicine Enablement

The referral flag output from extract_triage_with_history is designed to feed telemedicine escalation pathways. A CHW in a zero-physician catchment area can generate a structured, FHIR-compliant referral package — vitals, symptoms, history, severity — and dispatch it to a telemedicine platform. The receiving physician has a structured clinical summary rather than a verbal handoff.

Technical Deep Dive

Deep System Architecture

Layer Overview

┌─────────────────────────────────────────────────────────┐
│                    FRONTEND LAYER                        │
│          React · Multilingual UI · Offline PWA           │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│                 WORKFLOW ORCHESTRATION LAYER              │
│              GroundWork MCP Server (FastMCP)              │
│         Tool routing · Context management · Auth          │
└──────┬───────────┬──────────┬──────────┬────────────────┘
       │           │          │          │
┌──────▼──┐  ┌─────▼───┐ ┌───▼────┐ ┌──▼──────────┐
│TRIAGE   │  │VISION   │ │OCR     │ │HISTORY      │
│ENGINE   │  │TRIAGE   │ │BRIDGE  │ │RETRIEVAL    │
│triage.py│  │vision_  │ │ocr_    │ │get_patient_ │
│         │  │triage.py│ │bridge  │ │history      │
└──────┬──┘  └─────┬───┘ └───┬────┘ └──┬──────────┘
       └───────────┴──────────┴─────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│              CLINICAL INTELLIGENCE LAYER                  │
│   inference_engine.py · terminology.py · normalize.py    │
│  LOINC mapping · SNOMED coding · RxNorm normalization    │
│       Deterministic severity upgrades · History inject   │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│              FHIR INTEROPERABILITY LAYER                  │
│                      fhir_ops.py                          │
│   Observation · Condition · MedicationRequest ·           │
│   RiskAssessment · Bundle construction · R4 validation   │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│                DISPATCH LAYER                             │
│                action_dispatcher.py                       │
│      Idempotency keys · Exponential backoff ·            │
│      Live dispatch attempt · Failure capture             │
└──────────────┬──────────────────────────────────────────┘
               │ (on failure)
┌──────────────▼──────────────────────────────────────────┐
│              OFFLINE PERSISTENCE LAYER                    │
│                      sync_queue.py                        │
│           SQLite · Queue write · Pending tracking        │
└──────────────┬──────────────────────────────────────────┘
               │
┌──────────────▼──────────────────────────────────────────┐
│            SYNCHRONIZATION LAYER                          │
│         Background retry worker (30s interval)           │
│     Idempotent re-dispatch · Success marking ·           │
│         Failed count tracking · Queue draining           │
└─────────────────────────────────────────────────────────┘

Frontend Layer

The React frontend is the CHW interaction surface — intentionally minimal: image upload, text entry, and workflow status display. Clinical intelligence is entirely backend-resident. The frontend operates as an offline progressive web app (PWA); UI state does not depend on connectivity. Uploads queue locally when connectivity is absent and the backend sync layer handles retransmission.

The UI supports multilingual input across all supported regional languages. No English-first assumptions are encoded into the interaction layer.

Workflow Orchestration Layer

FastMCP serves as the workflow orchestration backbone. The MCP server exposes the full tool surface and handles:

Tool invocation routing based on input type
Context propagation across multi-step workflows
Patient context threading between history retrieval and triage execution
Workflow state management across asynchronous pipeline steps

Clinical Intelligence Layer

inference_engine.py orchestrates AI model calls (Groq API, Llama 3.3 70B for text, Llama 4 Vision for multimodal) and applies deterministic post-processing. terminology.py and normalize.py convert AI-generated clinical terms into LOINC, SNOMED CT, and RxNorm coded outputs. This layer converts free-form AI outputs into typed, coded, standards-compliant clinical data structures.

Interoperability Layer

fhir_ops.py implements FHIR R4 resource construction from structured intermediate representations. Resources generated include Observation (vitals, device readings), Condition (symptom-derived diagnoses), MedicationRequest (prescription-extracted medications), and RiskAssessment (triage severity output). SHARP extensions are applied for cross-system context propagation. Bundle validation occurs at this layer prior to dispatch.

Dispatch Layer

action_dispatcher.py implements the dispatch contract: attempt live dispatch, capture failures with idempotency keys, route failed dispatches to the persistence layer. Exponential backoff is applied to live retry attempts before queue fallback.

Persistence and Synchronization Layers

sync_queue.py implements the SQLite-backed offline queue. Every dispatch failure writes a queue record with: bundle payload, idempotency key, timestamp, retry count, and status. The background worker polls every 30 seconds, attempts dispatch for pending records, marks successful dispatches, and increments retry counters for failures. check_sync_queue exposes queue state (pending / synced / failed counts) to the orchestration layer and frontend.

Infrastructure Reliability and Validation

The Offline Dispatch Problem

In an offline-first system, the dispatch layer faces a fundamental challenge: the system must guarantee that every FHIR bundle generated during a connectivity-absent field visit is eventually dispatched to the backend FHIR server, exactly once, in the correct state, without duplication or loss.

This is a distributed systems problem — specifically, a variant of the guaranteed delivery problem under intermittent connectivity — applied to a healthcare context where data loss or duplication carries clinical consequences.

SQLite Queueing

sync_queue.py implements a SQLite-backed queue as the offline persistence substrate. SQLite is chosen deliberately: file-based, no server process required, operates on the same device as the application, ACID transactions on commodity hardware. Every dispatch failure writes a complete record to the queue:

queue_record:
  - bundle_payload (complete FHIR bundle JSON)
  - idempotency_key (SHA-256 of bundle content hash + patient ID + timestamp)
  - created_at
  - last_attempted_at
  - retry_count
  - status (pending / synced / failed)
  - error_log (last dispatch error)

Idempotency

Every bundle is assigned an idempotency key before dispatch. The backend FHIR server rejects duplicate submissions with the same idempotency key, preventing the common failure mode where reconnection triggers duplicate resource creation. Idempotency is enforced at both the client (key generation and tracking) and server (key validation on receipt) layers.

Retry Worker

The background retry worker runs on a 30-second polling interval. On each cycle:

Query SQLite queue for records with status pending and retry_count < max_retries
Attempt dispatch for each eligible record
On success: update status to synced, record timestamp
On failure: increment retry_count, update last_attempted_at, log error
Records exceeding max_retries are marked failed and flagged for manual review

Exponential Backoff

Live dispatch attempts apply exponential backoff before queue fallback: 1s → 2s → 4s → 8s → queue. This prevents thundering herd behavior when connectivity is intermittently available and multiple retry attempts occur simultaneously.

Production Implications

This reliability architecture means GroundWork provides dispatch guarantees — not best-effort delivery. A CHW conducting a 6-hour field visit in a zero-connectivity zone generates FHIR bundles throughout the visit. Every bundle is persisted locally. Upon return to connectivity, the retry worker drains the queue, dispatches all pending bundles idempotently, and the backend FHIR server receives a complete, ordered, deduplicated record of the day's encounters.

The clinical record is complete regardless of when connectivity was available.

Validation Results

Validation Target	Result
FHIR Observation resources generated	4
FHIR MedicationRequest resources generated	3
FHIR RiskAssessment resources generated	1
Kannada prescription OCR (two-stage)	✓
Pulse oximeter reading extraction	✓
Thermometer reading extraction	✓
Glucometer reading extraction	✓
Offline queue fallback activation	✓
SQLite persistence confirmed	✓
Retry worker validation	✓
Idempotency validation (duplicate rejection)	✓

For a hackathon healthcare project, generating FHIR resources from multilingual free text and handwritten Kannada prescriptions is non-trivial. It requires a functioning pipeline across: image → OCR → NLP interpretation → terminology normalization → FHIR resource construction → bundle validation → dispatch. Each stage can fail independently. The validation results confirm all stages executed successfully in sequence across multiple workflow paths.

The offline queue validation is particularly significant. Confirming that bundles survive connectivity failure, persist correctly to SQLite, and dispatch idempotently on reconnection validates the core architectural claim: operational continuity regardless of connectivity state.

Repository Architecture

Module Responsibilities

triage.py Core multilingual triage pipeline. Manages prompt construction for Llama 3.3 70B, output parsing, severity score normalization, and structured triage schema assembly. Entry point for extract_triage and extract_triage_with_history.

vision_triage.py Multimodal image analysis pipeline. Manages Llama 4 Vision API calls, image encoding, device-type detection logic, reading extraction, and output schema normalization. Entry point for analyze_clinical_image.

ocr_bridge.py Two-stage OCR pipeline coordinator. Stage 1: vision model invocation for raw text extraction. Stage 2: language model invocation for structured clinical interpretation. Manages handoff between stages and output schema alignment. Entry point for triage_document_image.

fhir_ops.py FHIR R4 resource construction and bundle assembly. Implements resource builders for Observation, Condition, MedicationRequest, RiskAssessment. Applies LOINC, SNOMED, RxNorm codes. Validates bundle structure before dispatch. Entry point for build_fhir_bundle and build_medication_bundle.

terminology.py Clinical terminology mapping. Maintains LOINC code mappings for vitals, SNOMED code mappings for common symptom presentations, and RxNorm lookup logic for medication normalization. Called by fhir_ops.py and normalize.py.

normalize.py Input normalization layer. Converts AI-generated free-form clinical terms into typed, coded representations prior to FHIR construction. Handles regional medication name normalization, symptom vocabulary standardization, and unit conversion.

inference_engine.py AI orchestration and deterministic post-processing. Manages Groq API calls, response parsing, and deterministic severity upgrade rule application. The hybrid reasoning layer — AI outputs enter here, enriched + upgraded outputs exit.

action_dispatcher.py Dispatch coordination. Manages live dispatch attempts, idempotency key generation, exponential backoff, and failure routing to the sync queue. The boundary between the interoperability layer and the persistence layer.

sync_queue.py SQLite queue implementation. Manages queue writes, retry worker execution, status tracking, and check_sync_queue surface. The offline persistence and synchronization substrate.

MCP Ecosystem Design

GroundWork implements healthcare workflow capabilities as composable MCP tools — a design decision with significant architectural implications. MCP tools are independently callable, chainable, and discoverable by any MCP-compatible agent or orchestration system. GroundWork's clinical capabilities are not locked to a single frontend or workflow path; they are reusable healthcare infrastructure primitives.

Tool Documentation

`extract_triage`

Purpose: Extract structured clinical triage data from free-text multilingual symptom descriptions.

Inputs: Patient symptom description (any supported language), optional vitals (temperature, SpO2, heart rate)

Outputs:

Severity score (1–5 scale)
Referral flag (boolean)
LOINC-mapped vitals array
SNOMED-coded symptom array

Workflow position: Primary triage entry point for text-based encounters

Downstream dependencies: Feeds build_fhir_bundle, dispatch_fhir_bundle

Safety assumptions: AI output is treated as a draft severity; downstream deterministic layer may upgrade. AI output is never final for escalation decisions.

`extract_triage_with_history`

Purpose: Full history-aware triage pipeline. Retrieves patient FHIR history, injects it into triage context, applies deterministic severity upgrades.

Inputs: Patient ID, symptom description, optional vitals

Outputs: Same schema as extract_triage plus history_context block documenting which historical conditions influenced severity

Workflow position: Preferred triage entrypoint when patient ID is available

Downstream dependencies: Calls get_patient_history internally; feeds dispatch_fhir_bundle

Safety assumptions: Deterministic escalation rules override AI-generated severity for known high-risk condition combinations (COPD + hypoxia, TB + fever, hypertension + chest symptoms).

`get_patient_history`

Purpose: Retrieve FHIR Condition resources for a patient from the connected FHIR server.

Inputs: Patient ID

Outputs: FHIR Condition resource array with SHARP extension context fields

Workflow position: Context retrieval step; called by extract_triage_with_history and available independently for history review workflows

Downstream dependencies: Output injected into triage context; may also feed referral document generation

Safety assumptions: History retrieval failure (connectivity loss) degrades gracefully — triage proceeds without history context rather than blocking. Failure is logged and surfaced.

`analyze_clinical_image`

Purpose: Vision triage pipeline for multimodal clinical device images and physical examination findings.

Inputs: Image (base64 or URL), optional device type hint

Outputs: Structured schema containing:

Device/finding type
Extracted reading + unit
SNOMED code (where applicable)
Confidence flag
Compatible with triage pipeline input schema

Supported input types: Malaria RDT strips, pulse oximeters, thermometers, glucometers, wound photographs, edema presentations

Workflow position: Pre-triage input enrichment; output injected into extract_triage or dispatched directly as Observation

Downstream dependencies: Feeds build_fhir_bundle via Observation construction

Safety assumptions: Vision model outputs are treated as preliminary readings. Dose-critical readings (e.g., very low SpO2) trigger mandatory CHW confirmation prompt before escalation.

`triage_document_image`

Purpose: Two-stage OCR + interpretation pipeline for handwritten clinical documents.

Inputs: Document image (prescription, referral slip, lab report)

Outputs:

Stage 1 output: Raw extracted text (preserving original script)
Stage 2 output: Structured clinical interpretation with coded medications, conditions, dosages

Workflow position: Prescription and referral document processing entry point

Downstream dependencies: Stage 2 output feeds build_medication_bundle

Safety assumptions: Stage 1 (OCR) and Stage 2 (interpretation) are explicitly separated. The system does not conflate extraction with inference. Stage 2 output is clearly labeled as AI-interpreted and not raw OCR.

`build_fhir_bundle`

Purpose: Construct a validated FHIR R4 bundle from structured triage or image analysis outputs.

Inputs: Structured triage output or image analysis output

Outputs: FHIR R4 Bundle containing Observation, Condition, RiskAssessment resources

Workflow position: Interoperability construction step; follows triage/image analysis, precedes dispatch

Downstream dependencies: Feeds dispatch_fhir_bundle

Safety assumptions: Bundle validation occurs before dispatch. Invalid bundles are rejected at this layer, not silently dispatched.

`build_medication_bundle`

Purpose: Construct a validated FHIR R4 bundle from prescription OCR outputs.

Inputs: Stage 2 OCR interpretation output

Outputs: FHIR R4 Bundle containing MedicationRequest, Condition, RiskAssessment resources

Workflow position: Medication workflow interoperability step

Downstream dependencies: Feeds dispatch_medication_bundle

Safety assumptions: RxNorm normalization is applied before bundle construction. Unrecognized medication names are flagged, not silently dropped.

`dispatch_fhir_bundle`

Purpose: One-step build + validate + dispatch pipeline for clinical triage bundles.

Inputs: Structured triage output (bundle construction handled internally)

Outputs: Dispatch status (success / queued / failed), idempotency key

Features:

Idempotency key generation (prevents duplicate dispatch on retry)
Exponential backoff on live dispatch failure
SQLite queue fallback on connectivity failure
Queue persistence with retry tracking

Workflow position: Terminal dispatch step for triage workflows

`dispatch_medication_bundle`

Purpose: Equivalent dispatch pipeline for medication bundles. Identical reliability guarantees.

Inputs: Stage 2 OCR output

Outputs: Dispatch status, idempotency key

`check_sync_queue`

Purpose: Returns current offline queue state.

Outputs:

pending_count: Records awaiting dispatch
synced_count: Successfully dispatched records
failed_count: Records that have exhausted retry attempts

Workflow position: Monitoring / status surface; callable by frontend and orchestration agents

A2A Skills

GroundWork exposes its clinical capabilities as Agent-to-Agent (A2A) skills, enabling GroundWork to function as a healthcare capability provider within multi-agent orchestration ecosystems.

CLINICAL IMAGE ANALYSIS

Accepts CHW-uploaded clinical images and returns structured findings compatible with downstream triage and FHIR generation workflows. Any orchestration agent can invoke this skill to obtain typed, coded clinical readings from raw device or examination photographs.

Agent ecosystem implication: A general-purpose orchestration agent with no healthcare-specific knowledge can delegate image interpretation to GroundWork and receive a structured, actionable output. Healthcare intelligence is encapsulated in the skill, not the orchestrating agent.

CLINICAL TRIAGE

Extracts multilingual triage information and returns coded healthcare outputs (LOINC vitals, SNOMED symptoms, severity scores, referral flags). Supports history-aware variants.

Agent ecosystem implication: Enables triage capability composition in multi-step agent workflows. An agent conducting a field visit workflow can invoke CLINICAL TRIAGE as a step and receive outputs that feed referral generation, alert dispatching, or record creation downstream.

FHIR BUNDLE DISPATCH

Creates and dispatches FHIR bundles with full reliability guarantees (idempotency, retry, queue fallback). Accepts structured clinical data, handles all interoperability and persistence concerns internally.

Agent ecosystem implication: Downstream agents do not need FHIR knowledge. They pass structured clinical data to this skill and receive dispatch confirmation. Interoperability complexity is encapsulated.

PRESCRIPTION OCR

Two-stage handwritten document processing pipeline. Returns structured medication and clinical data from raw prescription images.

Agent ecosystem implication: Any agent in a healthcare workflow that encounters a handwritten document can delegate extraction to this skill and receive structured, normalized output without implementing OCR or clinical interpretation logic.

Clinical Intelligence and Context Layer

History Retrieval and Injection

get_patient_history retrieves FHIR Condition resources from the connected server and structures them using SHARP extensions for cross-system context propagation. The retrieved history is injected into the triage prompt context before AI model invocation — the model receives both the current clinical presentation and the patient's documented condition history as a unified input.

This is not RAG in the conventional sense. It is deterministic context injection: a structured list of coded FHIR Conditions is appended to the triage prompt as a typed input block. The model does not retrieve this information; it receives it as structured context.

Deterministic Severity Upgrades

Following AI-generated triage output, inference_engine.py applies a deterministic severity upgrade pass operating on the combination of AI output + injected history:

COPD + SpO2 < 92%: Severity forced to maximum; referral flag forced true; escalation note appended
TB history + temperature > 38.0°C: Severity upgraded by one tier minimum; TB-specific referral pathway flagged
Hypertension + chest pain or shortness of breath: Referral flag forced; cardiovascular escalation note appended
Diabetes + altered consciousness symptoms: Severity upgraded; glucometer reading requested if not present

These rules are auditable, versioned, and documented. They are not learned behaviors. They are explicit clinical escalation policies implemented as deterministic code.

Hybrid Reasoning Architecture

The combination of AI interpretation + deterministic escalation produces a hybrid reasoning architecture with distinct safety properties:

AI handles the interpretation problem: extracting severity signals from noisy, multilingual, multimodal inputs that rule-based systems cannot parse
Deterministic logic handles the safety problem: ensuring that known high-risk combinations are never under-escalated regardless of AI output confidence

An AI model that outputs a moderate severity score for a COPD patient with SpO2 of 89% may have insufficient context. The deterministic layer catches this. Safety-critical escalation is not delegated to probabilistic inference.

Standards Architecture

FHIR R4

GroundWork generates FHIR R4 resources as its primary interoperability output. Every structured clinical finding — vital sign readings, symptom codes, medication prescriptions, severity assessments — is expressed as a valid FHIR resource with appropriate resource type, coded values, and structural conformance.

FHIR R4 resources are the interoperability currency of modern healthcare systems. A system that generates proprietary JSON cannot integrate with district health information systems, telemedicine platforms, or national health data repositories. GroundWork's outputs are consumable by any FHIR R4-capable system without transformation.

LOINC

Vitals extracted by GroundWork (temperature, SpO2, heart rate, blood glucose) are mapped to LOINC codes. An Observation resource generated in a rural Maharashtra field visit carries the same semantic meaning as one generated in a Mumbai tertiary hospital — both are LOINC 8310-5 for body temperature, LOINC 59408-5 for SpO2.

SNOMED CT

Symptom presentations extracted from free-text and image analysis are mapped to SNOMED CT codes where applicable. This converts informal clinical language ("patient has difficulty breathing") into structured, queryable clinical concepts (SNOMED 230145002 — difficulty breathing) that downstream clinical systems can act on.

RxNorm

Medications extracted from prescription OCR are normalized to RxNorm identifiers. Regional drug names, abbreviations, and brand names are mapped to their RxNorm equivalents, enabling MedicationRequest resources to be unambiguously interpreted by pharmacy systems, EHR medication reconciliation modules, and public health surveillance systems.

SHARP Extensions

SHARP extensions are applied to FHIR resources to support context propagation across systems — enabling patient history retrieved from one system to carry sufficient context for interpretation by another system in the workflow chain.

A Valid Healthcare Artifact Is More Than JSON

A system that generates {"symptom": "fever", "severity": "high"} has collected data. A system that generates a FHIR Observation resource with LOINC 8310-5, a UCUM-coded temperature value, a SNOMED severity code, a patient reference, an encounter reference, and a SHARP-extended provenance record has generated a healthcare artifact that any standards-compliant system can consume, validate, store, and act on.

GroundWork's outputs are designed to be the latter.

Future Roadmap

WhatsApp Integration

Patient history in LMIC environments often exists in messaging systems — prescription photographs shared with family members, symptom descriptions sent to informal networks. WhatsApp integration would enable GroundWork to receive clinical inputs through the channel CHWs and patients already use, routing them through the same extraction, normalization, and dispatch pipeline.

Edge Model Deployment

Current inference requires Groq API connectivity. Deploying quantized versions of Llama models (via llama.cpp or similar) to edge devices would enable fully offline AI inference — removing the final connectivity dependency from core workflows. This is technically achievable with current 7B-parameter quantized models on mid-range Android hardware.

Longitudinal Patient History

Expanding get_patient_history to maintain a local FHIR Condition store synchronized across visits would enable longitudinal tracking even when the backend FHIR server is intermittently accessible. Conflict resolution between local and server records is the primary engineering challenge.

Public Health Pilots

Partnering with state health departments or NGO field programs to deploy GroundWork in controlled pilot settings would generate real-world validation data on CHW workflow integration, data quality improvement, and system reliability under field conditions.

Expanded FHIR Integration

Deeper integration with FHIR Immunization, AllergyIntolerance, Procedure, and CarePlan resource types would expand the clinical surface area covered by GroundWork's interoperability layer.

EHR Workflow Embedding

Integration with district hospital EHR systems as a FHIR-native data receiver would close the referral loop: CHW generates referral package → dispatched to district hospital EHR → physician receives structured pre-admission record → patient arrives with clinical context already documented.

Closing Vision

Most healthcare technology investment flows toward environments that already have functioning infrastructure. GroundWork is built for the environments that don't.

The CHW conducting a tuberculosis follow-up in a zero-connectivity village, working from a handwritten patient list, photographing a prescription written in a regional script, making a triage decision on a patient with a complex comorbidity history — this is the operational context that GroundWork is designed for.

Not as a research prototype. As deployable infrastructure.

The engineering decisions throughout GroundWork — offline-first dispatch, deterministic safety overlays, standards-native output, multilingual extraction, idempotent synchronization — are not features. They are the minimum requirements for a system that claims to support clinical work in constrained environments.

Healthcare infrastructure that works only when conditions are favorable is not infrastructure. It is a fair-weather tool.

GroundWork is built for the weather that most health systems cannot handle.

Built With

fastapi
fastmcp
mcp
promptopinion
python
sqlite