Google Summer of Code 2025 – FHIR Project Final Report

Final-report.md

Google Summer of Code 2025 – Gen3 FHIR Server

Contributor Information

• Name: Andriana Sielli
• Organization: Center for Translational Data Science, University of Chicago
• Mentors: Alex Vantol, Kyle Burton
• GSoC Year: 2025
• Project Name: Gen3 FHIR Server
• Project Repository: https://github.com/Nana3792/gsoc-2025-fhir

1. Project Overview

This project addresses a critical challenge in biomedical data management: enabling secure, standards-based access to FHIR resources within the Gen3 ecosystem. It integrates a HAPI FHIR server with Gen3’s authorization system (Arborist) through a FastAPI-based proxy service, providing a modular, asynchronous, and secure layer for handling FHIR API requests.

Key highlights:

• Secure Access Control: Enforces Gen3-style access policies at the resource level using bearer token validation and security tags.
• Asynchronous API Handling: Uses FastAPI and HTTPX to support scalable, non-blocking requests for high-throughput FHIR data ingestion and retrieval.
• Standards-Based Storage: Uses a HAPI FHIR JPA server backed by PostgreSQL for reliable, standards-compliant FHIR data storage.
• Reproducible Deployment: Containerized with Docker and orchestrated via Docker Compose, enabling local and cloud-native deployments.
• FAIR-Aligned: Ensures Findable, Accessible, Interoperable, and Reusable management of biomedical data in compliance with NCPI guidelines.

This architecture demonstrates a practical path for integrating clinical data systems with federated data governance while maintaining interoperability and security.

2. Project Goals

The goal of this project was to develop a FHIR-compatible data service within the Gen3 ecosystem, enabling secure, authorized, and asynchronous access to FHIR resources.

Key Objectives

• Set up a local HAPI FHIR JPA server backed by PostgreSQL.
• Implement a FastAPI-based proxy enforcing authentication and access control.
• Integrate Arborist (Gen3 authorization service) for fine-grained policy enforcement.
• Ensure asynchronous ingestion of FHIR resources via FastAPI and HTTPX.
• Provide end-to-end tests using pytest and pytest-httpx.
• Containerize all components via Docker and Docker Compose for reproducibility.

3. System Architecture

The system integrates three core components:

1. HAPI FHIR Server — A JPA-backed FHIR server storing healthcare resources (Patient, Observation, etc.).
2. FHIR Proxy (FastAPI Service) — Acts as an intermediary between clients and the FHIR server. It:
   • Validates JWT tokens using Arborist.
   • Filters accessible resources based on user permissions.
   • Adds security tags to outgoing FHIR requests.
   • Routes API traffic asynchronously for scalability.
3. Arborist — The Gen3 authorization service managing resource access policies and permissions.

All services are containerized and orchestrated via Docker Compose.

4. Implementation Details

FastAPI Proxy

The proxy service handles all API traffic between the client and the HAPI FHIR server.
It uses asynchronous HTTP requests (httpx.AsyncClient) to improve performance and scalability.

Core Functions

• verify_token(token) – Validates bearer tokens.
• get_accessible_resources(token) – Calls Arborist’s /auth/resources endpoint to determine which FHIR resources a user can access.
• Forwards authorized API calls to the configured HAPI_FHIR_URL.
• Adds Gen3 security tags to enforce data governance.

---

Environment Configuration

Key parameters are defined in .env and config.py:

Variable	Description
ARBORIST_URL	URL for the Arborist authorization API
HAPI_FHIR_URL	Base URL for the HAPI FHIR server
SECURITY_TAG_PREFIX	Prefix for Gen3-style security labels
PROXY_TIMEOUT	Request timeout in seconds
GEN_USER_URL	Gen3 user endpoint

---

Asynchronous Ingestion

FastAPI endpoints support async ingestion and forwarding of FHIR data.
Using HTTPX ensures non-blocking calls to the HAPI server, improving throughput for multiple concurrent requests and enabling efficient handling of large-scale data ingestion workflows.

5. Testing

The testing suite ensures correct API behavior and integration with mocked external services.

Frameworks Used

• pytest and pytest-asyncio for asynchronous test execution
• pytest-httpx for mocking Arborist and HAPI server responses
• Environment isolation via .env.test for clean, reproducible runs

---

Test Coverage Includes

• Token verification and authorization checks
• Proxy routing and resource forwarding
• Mocked HAPI and Arborist endpoints for isolated integration testing

6. Dockerization

The FHIR Proxy is fully containerized to simplify local deployment and integration testing.

Overview

The system runs as a Docker Compose stack consisting of three main services:

• fhir-proxy – FastAPI-based proxy that enforces Gen3-style authorization and forwards FHIR requests.
• hapi-fhir – HAPI FHIR JPA server (Java-based) providing the core FHIR storage and retrieval.
• arborist – Gen3 authorization service for role- and resource-based access control.

Dockerfile

• Uses Amazon Linux 2023 as a base image.
• Installs Python 3.9, Poetry, and all dependencies defined in pyproject.toml.
• Runs the proxy via Gunicorn with Uvicorn workers for efficient asynchronous performance.
• Exposes port 8888.

Docker Compose

• Orchestrates the proxy, HAPI FHIR, and Arborist containers.
• Defines environment variables in .env (e.g., ARBORIST_URL, HAPI_FHIR_URL).
• Links services through a shared network for internal API communication.
• Exposes ports:
  • 8888 → FHIR Proxy
  • 8080 → HAPI FHIR Server
  • 8081 → Arborist

7. Outcome

This implementation demonstrates how to:

• Integrate FHIR-based clinical data systems with Gen3’s access control model.
• Build a FastAPI proxy that asynchronously manages secure data requests.
• Deploy the full stack in a reproducible containerized environment.

It provides a foundation for secure, standards-based, and FAIR-aligned biomedical data management.

8. Documentation

Community Feature Document

A detailed description of the proxy features and design decisions, created for community and organizational purposes.

HAPI FHIR JPA Server Summary

A concise summary of HAPI FHIR JPA server setup, configuration, and usage, combining key points from official HAPI documentation.

Repository README

Instructions for setting up the FHIR Proxy, ingestion scripts, environment variables, and running tests locally.

9. Future Work

• Extend proxy functionality to cover all NCPI FHIR resource profiles.
• Add logging, monitoring, and OpenAPI documentation.
• Connect to a persistent PostgreSQL database for HAPI FHIR.
• Configure and deploy an Elasticsearch backend to enable HAPI FHIR’s built-in full-text search capabilities (e.g., queries such as “Find all studies mentioning heart disease in their description”).
• Optimize unit testing to achieve near-complete (≈100%) code coverage and handle all potential failure scenarios.
• Implement Kubernetes deployment, including a Helm chart to simplify cloud-native installation and scaling.
• Expand and enhance project documentation, providing more comprehensive configuration guides, deployment instructions, and illustrative examples to support reproducibility, maintainability, and onboarding of new users.

→ When the above steps are completed, the implementation will be ready to undergo the formal Gen3 review process (integration, performance, and compliance testing), and the Community Feature Document can be finalized to reflect the completed and validated system design.

10. Project Metadata

• Author: Sielli Andriana
• Email: sielliandriana@gmail.com
• License: MIT
• Python: 3.9+
• Keywords: FHIR, Gen3, FastAPI, Arborist, NCPI, Docker, Cloud-native