System Architecture

JupyterHealth System Architecture¶

JupyterHealth is a modular ecosystem of interconnected components that enable patients to collect, control, and share their health data with researchers or clinicians. Users of JupyterHealth might include researchers or clinicians (or even patients) looking to combine patient-generated data with clinical data. This document explains the architecture of each component and how they work together to support patient-centered health data exchange.

System Overview¶

The JupyterHealth ecosystem enables patients to share health data from personal medical devices with research studies through consent-based access control.

High-Level Data Flow¶

Key Points:

• Device Manufacturers: Patients’ health devices sync data to manufacturer cloud APIs (glucose meters, CGMs, fitness trackers, smart rings)

• CommonHealth App: Retrieves data from manufacturers, transforms to IEEE 1752 standard, wraps in FHIR, uploads to JHE

• JupyterHealth Exchange: Manage organizations, practitioners, patients, studies, and consents

• Researchers: Query JHE FHIR API from Jupyter notebooks to analyze consented data

Component Architecture¶

1. CommonHealth Android App¶

Purpose: Patient-facing mobile application for collecting health data from personal medical devices and uploading to JupyterHealth Exchange

Role in System:

CommonHealth serves as a data collection and consent management client for patients:

1. Device Integration: Connects to personal health devices and manufacturer APIs (glucose meters, continuous glucose monitors, fitness trackers, smart rings) as well as FHIR based APIs for clinical and insurance data

2. Data Standardization: Normalizes device data to Open mHealth (IEEE 1752) format

3. FHIR Compatibility: Packages standardized data as FHIR Observations for upload to JHE

4. Consent Management: Patient interface for enrolling in studies and managing data sharing consent

5. Secure Communication: Encrypted uploads to JHE via REST API

Data Flow Example:

Device Data → OMH Format → FHIR Observation → JupyterHealth Exchange

Note: CommonHealth is developed by The Commons Project Foundation. For technical integration details, contact The Commons Project.

2. JupyterHealth Exchange (Backend API)¶

Technology: Django, Django REST Framework, PostgreSQL

Purpose: Central data exchange hub managing patient data, consent, and research access

Key Responsibilities:

• Patient and practitioner management and authentication (OAuth 2.0)

• Organization and study management

• Consent management (granular, per-study, per-data-type)

• FHIR API for data upload and retrieval

• Role-based access control (Viewer, Member, Manager)

• Authorization enforcement (consent checks)

Architecture Layers:

Core Models:

• JHEUser: Base user model (extends Django AbstractUser)

• Patient: Patient profile with FHIR Patient resource

• Practitioner: Researcher/clinician profile

• Organization: Research organizations with hierarchical structure

• Study: Clinical studies within organizations

• Observation: FHIR Observation resources (health data)

• StudyPatient: Many-to-many relationship (patients enrolled in studies)

• StudyPatientScopeConsent: Granular consent per patient, study, and data type

• PractitionerOrganization: Many-to-many with role (viewer/member/manager)

Key Features:

• FHIR compliance for Observation and Patient resources

• Multi-tenant organization structure

• Consent-as-authorization (no consent = no access)

• Study-level data scoping

• RESTful API with Django REST Framework

API Endpoints:

Admin API:

• users - Practitioner management

• organizations - Organization management

• patients - Patient management

• studies - Study management

• observations - Observation management

• data_sources - Data Source management

FHIR API:

• base - batch upload

• Observation - Observation search and create

• Patient - Patient search and create

3. Jupyter-SMART-on-FHIR Extension¶

Technology: Python, Jupyter, OAuth 2.0

Purpose: Enable researchers to authenticate with JHE from Jupyter notebooks

Key Responsibilities:

• OAuth 2.0 client configuration for SMART on FHIR

• Token acquisition and refresh

• Jupyter server integration

• Provide authenticated FHIR client for notebooks

Workflow:

Configuration:

• Set client ID and secret in jupyter_server_config.py

• Configure FHIR scopes (patient/.read, observation/.read)

• Set authorization and token endpoints

Use Cases:

• Data analysis on consented research data

• Machine learning model training

• Statistical analysis of study cohorts

Deployment Architecture¶

Local Development Deployment¶

For local development and testing, JupyterHealth Exchange can be run using Django’s built-in development server:

Setup Steps:

1. Set up Python environment (Python >= 3.10)

2. Install dependencies: pipenv sync (or pip install -r requirements.txt)

3. Create PostgreSQL database

4. Copy dot_env_example.txt to .env and update database credentials

5. Load environment: pipenv shell

6. Run migrations: python manage.py migrate

7. Seed database: python manage.py seed

8. Start server: python manage.py runserver

9. Access at http://localhost:8000 with credentials mary@example.com / Jhe1234!

Note: The Django development server should only be used for local development, not production deployments.

Production Deployment (Fly.io)¶

The current JupyterHealth Exchange production deployment runs on Fly.io:

Infrastructure Details:

Deployment Workflow:

1. Code pushed to GitHub main branch

2. GitHub Actions workflow triggered

3. .env file created from GitHub repository secrets

4. Docker image built with embedded .env file

5. Image deployed to Fly.io

6. Database migrations run automatically (python manage.py migrate)

7. New container started with zero downtime

Environment Configuration:

• All secrets stored in GitHub repository secrets (not Fly secrets)

• .env file generated at build time and included in Docker image

• Environment variables loaded via python-dotenv at runtime

• Includes: database credentials, OAuth keys, PKCE values, site configuration

Alternative Deployment Options:

For self-hosted or enterprise deployments, JHE can be deployed to:

• AWS/Azure/GCP: Using container services (ECS, AKS, Cloud Run)

• Kubernetes: Containerized deployment with Helm charts

• Traditional VPS: NGINX reverse proxy + gunicorn (see README)

• On-premises: Docker Compose for development/testing

The Dockerfile and gunicorn configuration support any container runtime or cloud platform.

Component Dependencies¶

Technology Stack Summary¶

External Dependencies¶

FHIR Libraries:

• Python: fhir.resources - FHIR R4/R5 models and validation

• Kotlin: HAPI FHIR - Java FHIR implementation for Android (supports DSTU2, R4, R5)

OAuth/Authentication:

• Django OAuth Toolkit (JHE server-side)

• AppAuth (Android OAuth 2.0/OIDC client)

Database:

• PostgreSQL 14+ (JHE)

• Room with SQLCipher encryption (CommonHealth Android app)

Standards Compliance:

• FHIR R4/R5 (HL7)

• SMART on FHIR

• SMART Health Cards

• SMART Health Links

• OAuth 2.0 / OpenID Connect

Interoperability Standards¶

FHIR (Fast Healthcare Interoperability Resources)¶

JupyterHealth uses FHIR as the primary data exchange format:

FHIR Version:

• FHIR: JupyterHealth Exchange uses FHIR exclusively

FHIR Resources Implemented in JHE:

• Patient: Patient demographics, identifiers, contact information

• Observation: Health measurements and device data (primary data resource)

JHE focuses specifically on device-generated observations rather than comprehensive EHR data.

Learn More¶

• Exchange Overview - JupyterHealth Exchange details

• FHIR Interoperability - FHIR implementation details

• Data Flow - Detailed data flow documentation

• Security Overview - Security architecture and compliance

• Role-Based Access and Governance - Access control details