# jmandel/health-record-mcp architecture

> Architecture diagram of the GitHub repository jmandel/health-record-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jmandel/health-record-mcp
- Repository: https://github.com/jmandel/health-record-mcp

## Overview

──────────────────────────────
##### Project Type & Core Purpose

- This is a specialized backend server and toolkit that sits between Electronic Health Records (EHR) and external AI/LLM agents.
- It implements the SMART on FHIR client to fetch detailed patient data and then exposes that data via empowered MCP tools (grep_record, query_record, eval_record).
- It supports multiple modes: a standalone web client mode (using HTML/JS), a CLI/standard IO mode that builds a local SQLite database, and an SSE (Server-Sent Events) mode for persistent networked connections with OAuth 2.1.

──────────────────────────────
##### Out the Main Components

A. Client-Side Components
1. SMART on FHIR Web Client
- Represented by “opener.html” (and possibly other static files in the “static” directory, e.g. db-picker.html).
- Function: Initiate the SMART App Launch flow, authenticate with the EHR provider, and fetch a comprehensive set of FHIR resources.
2. External AI / LLM Interface (Consumer)
- Function: Sends queries/requests to the MCP endpoint (e.g., for performing a grep, SQL, or eval function).

B. Server-Side Components
1. MCP Server components (core engine)
- Two modes/capabilities:
a. Local MCP Server via Stdio/CLI (referencing “src/cli.ts”)
- Two-step: First, fetch data and create a local SQLite database; second, load the database and start the MCP server communicating via standard input/output.
b. Persistent MCP Server via SSE (referencing “src/sse.ts”)
- Provides a network endpoint using SSE, handles OAuth 2.1 endpoints (/authorize, /token, etc.), and has an experimental authentication flow.
- MCP Server component with sub-nodes or annotations explaining its dual mode of operation.
2. Authentication & OAuth Endpoints
- Dedicated endpoints for OAuth endpoints (illustrate: /authorize, /token, /register).
- These are part of the MCP SSE mode and are critical for secure client (and AI agent) approval.

C. Data Management Components
1. Database Storage (SQLite Database)
- Use a node for the local SQLite database that gets created when running the CLI with "--create-db" flag.
- That absolute paths are recommended for configuration (as observed in the README).
2. FHIR Data Extraction & Transformation
- This node interfaces between the fetched data and the MCP tools (grep_record, query_record, eval_record).

D. Configuration & Deployment
1. Configuration Files
- Role of various configuration files (e.g., “config.epicprod.json”, “sample-config.json”) which tailor the system’s behavior to different EHR providers (Epic, SMART sandbox, etc.).
2. Docker and CI/CD
- That the project includes a Dockerfile and GitHub workflows (”.github/workflows/build-and-package.yml”), indicating that containerization and automated builds/deployments are part of the overall ecosystem.

──────────────────────────────
##### Relationships and Data Flow

- “SMART on FHIR Web Client” → (data extraction using the SMART App Launch flow) → “FHIR Data Extraction & Transformation Module”

- “FHIR Data Extraction” → “MCP Server”
- That once extracted, data enters the MCP process and is either stored in an SQLite database (CLI mode) or retained in memory for SSE sessions.

- “MCP Server” ←→ “Authentication & OAuth Endpoints”

- “MCP Server” ↔ “External AI / LLM Interface”

- “MCP Server” → “SQLite Database” (when in CLI mode)

- Optionally, include CI/CD/Deployment pipelines (Docker / GitHub Actions) as peripheral nodes that trigger builds and packaging.

──────────────────────────────
##### Technology & Architectural Patterns

A. Architectural Patterns
- Separation of concerns: clearly differentiate between the UI (SMART client), business logic (MCP server, FHIR extraction), and persistence (SQLite database).
- Use of asynchronous communication (postMessage for the standing web client, and SSE for persistent server mode).

B. Technologies and Frameworks
- Use a note to mention that the project uses TypeScript (files in “src”, “clientTypes.ts”, etc.).
- Mention the use of Docker (via Dockerfile) and continuous integration (via GitHub workflows).
- The OAuth 2.1 implementation and the Server-Sent Events model is essential to the design.

──────────────────────────────

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        A["SMART on FHIR Web Client (opener.html & static)"]:::client
        B["External AI/LLM Interface (AI Agent)"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        subgraph "MCP Server"
            C1["CLI Mode (src/cli.ts)"]:::server
            C2["SSE Mode (src/sse.ts)"]:::server
            D["OAuth & Authentication Endpoints (/authorize, /token, /register)"]:::auth
        end
        subgraph "FHIR Extraction Modules"
            E1["FHIR Search Queries (src/fhirSearchQueries.ts)"]:::extraction
            E2["FHIR To Plaintext (src/fhirToPlaintext.ts)"]:::extraction
            E3["Session Utils (src/sessionUtils.ts)"]:::extraction
        end
    end

    %% Data & Config Layer
    subgraph "Data & Config Layer"
        F["SQLite Database"]:::database
        G["Configuration Files (config.epicprod.json, config.epicsandbox.json, config.jmandel.json, config.smartsandbox.json, config.stdio.json, sample-config.json)"]:::config
        H["CI/CD & Deployment (Dockerfile, .github/workflows/build-and-package.yml)"]:::deploy
    end

    %% Connections - Data Flow
    A -->|"ClientFullEHR_JSON(FHIR+Attachments)"| E1
    A -->|"ClientFullEHR_JSON(FHIR+Attachments)"| E2
    A -->|"ClientFullEHR_JSON(FHIR+Attachments)"| E3

    E1 -->|"Processed_EHR_Data"| C1
    E2 -->|"Processed_EHR_Data"| C2
    E3 -->|"Processed_EHR_Data"| C1

    C1 -->|"PersistData(CLI_Mode)"| F

    %% Connections - Configuration Influence
    G -->|"Configures"| C1
    G -->|"Configures"| E1
    G -->|"Configures"| E2
    G -->|"Configures"| E3

    %% Connections - Authentication and AI Agent
    C1 <-->|"OAuthValidation"| D
    C2 <-->|"OAuthValidation"| D
    B <-->|"MCP_Operations(grep_record,query_record,eval_record)"| C1
    B <-->|"MCP_Operations(grep_record,query_record,eval_record)"| C2

    %% Connections - Deployment Influence
    H -->|"BuildDeploy"| C1
    H -->|"BuildDeploy"| C2
    H -->|"BuildDeploy"| E1

    %% Click Events
    click A "https://github.com/jmandel/health-record-mcp/blob/main/opener.html"
    click A "https://github.com/jmandel/health-record-mcp/tree/main/static/"
    click C1 "https://github.com/jmandel/health-record-mcp/blob/main/src/cli.ts"
    click C2 "https://github.com/jmandel/health-record-mcp/blob/main/src/sse.ts"
    click D "https://github.com/jmandel/health-record-mcp/blob/main/src/oauth.ts"
    click E1 "https://github.com/jmandel/health-record-mcp/blob/main/src/fhirSearchQueries.ts"
    click E2 "https://github.com/jmandel/health-record-mcp/blob/main/src/fhirToPlaintext.ts"
    click E3 "https://github.com/jmandel/health-record-mcp/blob/main/src/sessionUtils.ts"
    click F "https://github.com/jmandel/health-record-mcp/blob/main/src/cli.ts"
    click G "https://github.com/jmandel/health-record-mcp/blob/main/config.epicprod.json"
    click G "https://github.com/jmandel/health-record-mcp/blob/main/config.epicsandbox.json"
    click G "https://github.com/jmandel/health-record-mcp/blob/main/config.jmandel.json"
    click G "https://github.com/jmandel/health-record-mcp/blob/main/config.smartsandbox.json"
    click G "https://github.com/jmandel/health-record-mcp/blob/main/config.stdio.json"
    click G "https://github.com/jmandel/health-record-mcp/blob/main/sample-config.json"
    click H "https://github.com/jmandel/health-record-mcp/tree/main/Dockerfile"
    click H "https://github.com/jmandel/health-record-mcp/blob/main/.github/workflows/build-and-package.yml"

    %% Styles
    classDef client fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef server fill:#ffa500,stroke:#000,stroke-width:1px;
    classDef auth fill:#ff4500,stroke:#000,stroke-width:1px;
    classDef extraction fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef database fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef config fill:#c0c0c0,stroke:#000,stroke-width:1px;
    classDef deploy fill:#c0c0c0,stroke:#000,stroke-width:1px;
```
