WIP EUPL-1.2Healthcare Services

MedBook

Electronic clinical file - Self-hosted FHIR R4 + GDPR for EU clinics and primary care physicians

Status
WIP
License
EUPL-1.2
Category
Healthcare Services
Updated
GitHub source

Project status

Description

MedBook is a self-hosted electronic health record (EHR) for small and medium clinics, specialist practices and general practitioners in the EU who want to own their patient data without depending on cloud SaaS. The architecture is a four-layer Clean Architecture on Spring Boot 3.4 with a JPA-agnostic domain, a zoneless Angular 21 front end with standalone components and signals whose clinical routes render exclusively in the browser, and PostgreSQL 16 persistence with application-level AES-256-GCM encryption (Google Tink) on sensitive fields and a three-level audit trail. The data model is designed around FHIR R4 (Patient, Practitioner, Observation, Condition, MedicationStatement, AllergyIntolerance, Procedure, DiagnosticReport), mapping JPA entities to FHIR resources through the HAPI FHIR library for interoperability with national health systems. Security is first-class: Keycloak SSO with OIDC, role-based access control, a three-level access record — versioning, an HMAC chain with a daily seal, and the database audit log — because versioning tables alone are not immutable, configurable session timeout, and a NIST 800-63B compliant password policy. GDPR consent is handled through a dedicated schema, with granular consent per data category and traceable withdrawal. Consent does not govern care, which rests on Article 9(2)(h) GDPR: it governs the shared record and external sharing. Where a clinical record is subject to a retention obligation, the ordinary answer to an erasure request is a reasoned refusal under Article 17(3)(b) and (c), not anonymisation. The EUPL-1.2 licence aligns explicitly with the EU public sector standard. The project is designed for integration with the Italian national health record and in anticipation of the EHDS: no conformity is claimed before it has been verified. Deployment is through Docker Compose or a systemd unit, targeting a single practitioner or a cluster of 2 to 20 concurrent users. The philosophy is data sovereignty by design: the data lives on the customer's own server, with no external analytics, no telemetry and no CDN for the clinical bundles.

Key Features

  • Data model FHIR R4 native

    JPA entity mapped to FHIR Resource (Patient, Observation, Condition, MedicationStatement) via HAPI FHIR, export bundle in JSON/XML standard.

  • Three-level audit trail, not just versioning

    Every access is recorded (operator, time, action, reason). Envers provides versioning but is not immutable in itself: anyone with write permissions on the revision tables can alter them. The audit trail therefore has three levels, with an HMAC chain, a daily seal, and update and delete permissions revoked.

  • Keycloak SSO with fine-grained RBAC

    OIDC Integration, 4 predefined roles (Doctor/Nurse/Secretary/Admin), configurable permission matrix, role-based session timeout.

  • GDPR Consent Management

    Granular consent per data category with traceable withdrawal, kept distinct from the lawful basis for care, which is Article 9(2)(h) GDPR and not consent. Data export on request by the data subject.

  • Zoneless Angular 21 front end

    Standalone components, reactive signals, prerendering for public pages only. No clinical data is server-rendered: clinical routes render in the browser, verified at build time. Tokens never reach the browser (BFF pattern, HttpOnly session).

  • Application-level AES-256-GCM encryption

    Sensitive fields are encrypted in the application with AES-256-GCM (Google Tink), with associated data bound to the row and a per-organisation key hierarchy. Not pgcrypto: a key passed as a SQL argument ends up in query statistics and query logs. Search on the national identifier uses an HMAC blind index, exact equality only.

  • Automated encrypted backups

    Dump encrypted with GPG, configurable retention, Hetzner Storage Box option, guided restore testing in documentation.

  • Deploy a hardened systemd version

    Run with NoNewPrivileges, ProtectSystem=strict, PrivateTmp, no Docker needed, use alternative Docker Compose if preferred.

Tech stack

  • Spring Boot 3.4
  • Java 21
  • Angular 21
  • PostgreSQL 16
  • HAPI FHIR R4
  • Keycloak
  • Hibernate Envers
  • Google Tink
  • Docker Compose

Use cases

  • Basic medical clinic that wants to digitize patient files without relying on US-based SaaS.
  • Specialized clinic small (2-20 users) with need for FHIR R4 export to external labs and specialists
  • Dentist or physiotherapist clinic that manages patient records and treatment plans with strict GDPR constraints.
  • Researchers who need an open-source EHR for small local clinical studies

Road Map

  1. v0.1.0Scheduled

    Core EHR: Patient, Practitioner, and Audit Information

    • FHIR Patient and Practitioner Model mapped to JPA
    • CRUD endpoint with Keycloak SSO and RBAC base
    • Active Hibernate Envers audit trail on sensitive entities
    • Frontend Angular login and patient dashboard
  2. v0.5.0Scheduled

    Observation and Treatment Plan

    • FHIR Observation, Condition, and Medication Statement
    • Export FHIR bundle JSON/XML via endpoint /fhir/Patient/
    • Application-level AES-256-GCM encryption for history and allergies
    • GDPR Consent - Revoke - Export DSAR Data
  3. v1.0.0Scheduled

    FSE 2.0 IT Integration and Production Deployment

    • National FSE 2.0 Gateway Connector
    • Automated encrypted backups with test restores
    • Complete MkDocs documentation and VPS deployment guide
    • Security audit pre-release + penetration testing (post MVP delay)

Who is it for

  • For Developers - Senior
  • Decision Maker/Founder

Quick start

Start the project locally in just a few commands. 

# Quick start (work-in-progress: nessun codice applicativo ancora rilasciato)
# git clone https://github.com/fedcal/MedBook.git
# cd MedBook
# cp .env.example .env  # configura DB, Keycloak, gestore delle chiavi
# docker compose up -d  # postgres + keycloak + medbook-backend + medbook-frontend

Contribute to the project

MedBook is open source. Open an issue, propose a pull request or leave a star on GitHub: every contribution, no matter how small, is welcome.

  • ⭐ Leave a star if it's useful
  • 🐛 Report bugs or suggest features via issue
  • 🔧 Send a pull request with fixes or improvements
  • 📣 Share the project if you find it interesting
Star on GitHubOpen an issuePull request
← ⭐ View on GitHub