Mere Medical

Mere Medical is a self‑hosted, privacy‑first Personal Health Record (PHR) designed to aggregate data from a wide spectrum of patient portals and electronic medical record (EMR) systems. From an engineering standpoint, the application exposes a RESTful API layer that ingests HL7/FHIR payloads and converts them into a unified internal schema. The front‑end, built with modern web technologies, consumes this API to render a timeline view and summary widgets that can be accessed offline thanks to Service Workers and IndexedDB caching.

Technical Stack & Architecture

• Backend: Node.js (TypeScript) powered by the NestJS framework, which provides a modular architecture and dependency injection out of the box. The service layer interacts with a PostgreSQL database via TypeORM, storing both raw FHIR bundles and denormalized aggregates for quick queries.
• Frontend: Angular 16, leveraging RxJS for reactive data flows. The UI is responsive and follows Material Design guidelines, with a mobile‑first approach that allows the same codebase to run in browsers and as a Progressive Web App (PWA).
• Containerization: A single Docker image (cfu288/mere-medical) contains the compiled front‑end and the Node.js API. Docker Compose is bundled in the repo for quick local spin‑ups, exposing only port 80 (or a configurable host port) and environment variables for OAuth credentials to various patient portals.
• Data Sync: The application implements the SMART on FHIR OAuth 2.0 flow for each supported provider (Epic, Cerner, OnPatient, Veradigm). A background worker, scheduled via BullMQ, polls provider APIs for new bundles and persists them.

Core Capabilities & Developer API

• Patient Portal Integration: Exposes a POST /sync endpoint that accepts OAuth tokens and triggers provider-specific adapters. Each adapter is a pluggable module, making it straightforward to add new portals by implementing the IProviderAdapter interface.
• FHIR Resource Normalization: Internally transforms incoming FHIR resources into a canonical model (Patient, Observation, MedicationStatement, etc.) and stores them in PostgreSQL. A GraphQL layer (Apollo Server) is available for advanced queries, allowing developers to fetch nested relationships without multiple round‑trips.
• Webhooks & Callbacks: The API supports registering webhook URLs (POST /webhook) that receive JSON payloads when new records are ingested, enabling downstream analytics or CI/CD pipelines to react in real time.
• Export & Import: Endpoints for exporting data as a FHIR bundle (GET /export) or importing an existing bundle (POST /import) facilitate interoperability with other PHR solutions.

Deployment & Infrastructure

• Self‑Hosting: The minimal requirements are a Docker runtime and a PostgreSQL instance. For production, the repo includes Helm charts for Kubernetes deployments (including optional Ingress and TLS termination).
• Scalability: Stateless API containers allow horizontal scaling behind a load balancer. The background worker can be replicated to process sync jobs in parallel, while the PostgreSQL database can be scaled using read replicas or managed services.
• Offline First: Service Workers cache static assets and API responses, enabling the web app to function without network connectivity. IndexedDB stores a local copy of the timeline data, which syncs once the connection is restored.

Integration & Extensibility

• Plugin System: Developers can extend Mere by creating new provider adapters or UI components. The plugin interface is documented in the docs/architecture.md file, detailing lifecycle hooks and dependency injection patterns.
• Custom Workflows: The application exposes a scripting endpoint (POST /workflow) that accepts JavaScript snippets to transform or annotate records before they are persisted, useful for research projects or custom analytics.
• Community & Documentation: The project maintains a comprehensive API reference, example curl scripts, and a Discord channel for real‑time support. The license is MIT, ensuring no vendor lock‑in.

Use Cases

1. Clinical Research – Researchers can host Mere on a secure server, ingest patient data from multiple hospitals, and run analytics without exposing PHI to third‑party SaaS platforms.
2. Enterprise IT – Hospitals can deploy Mere on-premises to provide patients with a single portal that aggregates data from disparate EMR systems, improving patient engagement.
3. Personal Health Management – Developers building mobile health apps can embed Mere’s API to offer patients a consolidated view of their medical history, while keeping data under the user’s control.

Advantages for Developers

• Open‑Source & Transparent – Full source code with a permissive license eliminates hidden costs and allows deep customization.
• Modular Architecture – Clear separation between adapters, API, and UI makes it easy to maintain or replace components.
• Performance – NestJS + TypeORM + PostgreSQL provide a proven, low‑latency stack for FHIR data; caching layers reduce API calls to external portals.
• Extensibility – The adapter and workflow hooks enable rapid integration of new providers or custom business logic without touching core code.
• Community Support – Active Discord channel and GitHub issue tracker ensure timely assistance for integration challenges.

Mere Medical offers developers a robust, self‑hosted foundation to build patient‑centric health applications while preserving data sovereignty and compliance with privacy regulations.