# rvcarcueva2/open-health-stack architecture

> Architecture diagram of the GitHub repository rvcarcueva2/open-health-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rvcarcueva2/open-health-stack
- Repository: https://github.com/rvcarcueva2/open-health-stack

## Overview

Open Health Stack is a local-first patient registration and synchronization product. A user enters a patient record, which is converted to FHIR and saved on-device; an explicit Sync now action uploads pending records through the Spring API and OpenHIM to HAPI FHIR. The mobile app also lists and searches local patients and exposes upload status. The graph combines sampled mobile calls with README-documented backend and infrastructure flow; backend implementation details and several mobile modules were not sampled.

Main entry points: [`mobile/src/features/patients/PatientsScreen.tsx`](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/PatientsScreen.tsx) (Patient list), [`mobile/src/features/patients/hooks.ts`](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/hooks.ts) (Patient hooks), [`mobile/src/features/patients/local.ts`](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/local.ts) (Local patient data), [`mobile/app`](https://github.com/rvcarcueva2/open-health-stack/tree/main/mobile/app) (Expo routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_routes["Expo routes"]
  node_patient_screen["Patient list<br/>[PatientsScreen.tsx]"]
  node_patient_card["Patient card<br/>[PatientCard.tsx]"]
  node_patient_form["Patient form<br/>[AddPatientForm.tsx]"]
  node_form_components["Form controls"]
  node_sync_card["Sync status<br/>[SyncCard.tsx]"]
  node_patient_hooks["Patient hooks<br/>[hooks.ts]"]
  node_fhir_mapping["FHIR mapping<br/>[fhir.ts]"]
  node_formatting["Patient formatting<br/>[format.ts]"]
  node_local_data["Local patient data<br/>[local.ts]"]
  node_sqlite[("SQLite database<br/>[migrations.ts]")]
  node_sync_runner["Sync runner<br/>[syncPatients.ts]"]
  node_patient_api["Patient API calls<br/>[api.ts]"]
  node_http_client["HTTP client<br/>[client.ts]"]
  node_api_host["API host config<br/>[config.ts]"]
end

subgraph group_backend["Backend API"]
  node_controller["Patient controller"]
  node_fhir_config["FHIR client config<br/>[FhirConfig.java]"]
  node_patient_service["Patient service"]
end

subgraph group_interop["FHIR interoperability"]
  node_openhim{{"OpenHIM gateway"}}
  node_hapi["HAPI FHIR"]
  node_postgres[("PostgreSQL")]
end

node_user(("Mobile user"))

node_user -->|"uses"| node_routes
node_routes -->|"opens list"| node_patient_screen
node_routes -->|"opens form"| node_patient_form
node_patient_form -->|"renders"| node_form_components
node_patient_form -->|"creates through"| node_patient_hooks
node_patient_hooks -->|"saves locally"| node_local_data
node_local_data -->|"maps patient"| node_fhir_mapping
node_local_data -->|"reads and writes"| node_sqlite
node_patient_screen -->|"loads patients"| node_patient_hooks
node_patient_screen -->|"renders"| node_patient_card
node_patient_screen -->|"formats search"| node_fhir_mapping
node_patient_card -->|"formats display"| node_formatting
node_patient_screen -->|"shows status"| node_sync_card
node_sync_card -->|"starts sync"| node_patient_hooks
node_patient_hooks -->|"dispatches sync"| node_sync_runner
node_sync_runner -->|"gets pending rows"| node_local_data
node_sync_runner -->|"uploads resource"| node_patient_api
node_patient_api -->|"sends request"| node_http_client
node_http_client -->|"uses host"| node_api_host
node_http_client -->|"POST FHIR JSON"| node_controller
node_controller -->|"parses FHIR"| node_fhir_config
node_controller -->|"creates patient"| node_patient_service
node_patient_service -->|"sends FHIR request"| node_openhim
node_openhim -->|"forwards FHIR"| node_hapi
node_hapi -->|"persists resources"| node_postgres

click node_routes "https://github.com/rvcarcueva2/open-health-stack/tree/main/mobile/app"
click node_patient_screen "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/PatientsScreen.tsx"
click node_patient_card "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/PatientCard.tsx"
click node_patient_form "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/AddPatientForm.tsx"
click node_form_components "https://github.com/rvcarcueva2/open-health-stack/tree/main/mobile/src/components"
click node_sync_card "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/components/SyncCard.tsx"
click node_patient_hooks "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/hooks.ts"
click node_fhir_mapping "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/fhir.ts"
click node_formatting "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/format.ts"
click node_local_data "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/local.ts"
click node_sqlite "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/db/migrations.ts"
click node_sync_runner "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/sync/syncPatients.ts"
click node_patient_api "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/api.ts"
click node_http_client "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/api/client.ts"
click node_api_host "https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/config.ts"
click node_controller "https://github.com/rvcarcueva2/open-health-stack/blob/main/backend/src/main/java/com/example/openhealthstack/api/PatientController.java"
click node_fhir_config "https://github.com/rvcarcueva2/open-health-stack/blob/main/backend/src/main/java/com/example/openhealthstack/config/FhirConfig.java"
click node_patient_service "https://github.com/rvcarcueva2/open-health-stack/blob/main/backend/src/main/java/com/example/openhealthstack/fhir/PatientService.java"
click node_openhim "https://github.com/rvcarcueva2/open-health-stack/tree/main/infra/openhim"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_patient_screen,node_patient_card,node_patient_form,node_form_components,node_sync_card,node_patient_hooks,node_fhir_mapping,node_formatting,node_local_data,node_sqlite,node_sync_runner,node_patient_api,node_http_client,node_api_host,node_user toneBlue
class node_controller,node_fhir_config,node_patient_service toneAmber
class node_openhim,node_hapi,node_postgres toneMint
```

## Components

### Mobile app

- [Expo routes](https://github.com/rvcarcueva2/open-health-stack/tree/main/mobile/app): `mobile/app`
- [Patient list](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/PatientsScreen.tsx): `mobile/src/features/patients/PatientsScreen.tsx`
- [Patient card](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/PatientCard.tsx): `mobile/src/features/patients/PatientCard.tsx`
- [Patient form](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/AddPatientForm.tsx): `mobile/src/features/patients/AddPatientForm.tsx`
- [Form controls](https://github.com/rvcarcueva2/open-health-stack/tree/main/mobile/src/components): `mobile/src/components`
- [Sync status](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/components/SyncCard.tsx): `mobile/src/components/SyncCard.tsx`
- [Patient hooks](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/hooks.ts): `mobile/src/features/patients/hooks.ts`
- [FHIR mapping](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/fhir.ts): `mobile/src/features/patients/fhir.ts`
- [Patient formatting](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/format.ts): `mobile/src/features/patients/format.ts`
- [Local patient data](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/local.ts): `mobile/src/features/patients/local.ts`
- [SQLite database](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/db/migrations.ts): `mobile/src/db/migrations.ts`
- [Sync runner](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/sync/syncPatients.ts): `mobile/src/sync/syncPatients.ts`
- [Patient API calls](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/features/patients/api.ts): `mobile/src/features/patients/api.ts`
- [HTTP client](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/api/client.ts): `mobile/src/api/client.ts`
- [API host config](https://github.com/rvcarcueva2/open-health-stack/blob/main/mobile/src/config.ts): `mobile/src/config.ts`

### Backend API

- [Patient controller](https://github.com/rvcarcueva2/open-health-stack/blob/main/backend/src/main/java/com/example/openhealthstack/api/PatientController.java): `backend/src/main/java/com/example/openhealthstack/api/PatientController.java`
- [FHIR client config](https://github.com/rvcarcueva2/open-health-stack/blob/main/backend/src/main/java/com/example/openhealthstack/config/FhirConfig.java): `backend/src/main/java/com/example/openhealthstack/config/FhirConfig.java`
- [Patient service](https://github.com/rvcarcueva2/open-health-stack/blob/main/backend/src/main/java/com/example/openhealthstack/fhir/PatientService.java): `backend/src/main/java/com/example/openhealthstack/fhir/PatientService.java`

### FHIR interoperability

- [OpenHIM gateway](https://github.com/rvcarcueva2/open-health-stack/tree/main/infra/openhim): `infra/openhim`
- **HAPI FHIR**
- **PostgreSQL**

### Other components

- **Mobile user**

## Connections

- Mobile user → Expo routes: uses (evidence: `README.md`)
- Expo routes → Patient list: opens list (evidence: `mobile/app/(tabs)/index.tsx`)
- Expo routes → Patient form: opens form (evidence: `mobile/app/add-patient.tsx`)
- Patient form → Form controls: renders (evidence: `mobile/src/features/patients/AddPatientForm.tsx`)
- Patient form → Patient hooks: creates through (evidence: `mobile/src/features/patients/AddPatientForm.tsx`)
- Patient hooks → Local patient data: saves locally (evidence: `mobile/src/features/patients/hooks.ts`)
- Local patient data → FHIR mapping: maps patient (evidence: `mobile/src/features/patients/local.ts`)
- Local patient data → SQLite database: reads and writes (evidence: `README.md`)
- Patient list → Patient hooks: loads patients (evidence: `mobile/src/features/patients/PatientsScreen.tsx`)
- Patient list → Patient card: renders (evidence: `mobile/src/features/patients/PatientsScreen.tsx`)
- Patient list → FHIR mapping: formats search (evidence: `mobile/src/features/patients/PatientsScreen.tsx`)
- Patient card → Patient formatting: formats display (evidence: `mobile/src/features/patients/PatientCard.tsx`)
- Patient list → Sync status: shows status (evidence: `mobile/src/features/patients/PatientsScreen.tsx`)
- Sync status → Patient hooks: starts sync (evidence: `mobile/src/components/SyncCard.tsx`)
- Patient hooks → Sync runner: dispatches sync (evidence: `mobile/src/features/patients/hooks.ts`)
- Sync runner → Local patient data: gets pending rows (evidence: `mobile/src/sync/syncPatients.ts`)
- Sync runner → Patient API calls: uploads resource (evidence: `mobile/src/sync/syncPatients.ts`)
- Patient API calls → HTTP client: sends request (evidence: `mobile/src/features/patients/api.ts`)
- HTTP client → API host config: uses host (evidence: `mobile/src/api/client.ts`)
- HTTP client → Patient controller: POST FHIR JSON (evidence: `README.md`)
- Patient controller → FHIR client config: parses FHIR (evidence: `README.md`)
- Patient controller → Patient service: creates patient (evidence: `README.md`)
- Patient service → OpenHIM gateway: sends FHIR request (evidence: `README.md`)
- OpenHIM gateway → HAPI FHIR: forwards FHIR (evidence: `README.md`)
- HAPI FHIR → PostgreSQL: persists resources (evidence: `README.md`)
