# jprbom/-health-dashboard-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/jprbom/-health-dashboard-mcp
- Repository: https://github.com/jprbom/-health-dashboard-mcp

## Overview

##### Project type and purpose
- This is a Node.js “MCP server” (“Model Context Protocol”) that sits behind an AI assistant (e.g. Claude) to manage personal health and biometric data.
- Its purpose is to accept natural-language commands from the AI assistant, execute various “tools” (recording metrics, trend analysis, goal-setting, etc.), and return structured results.
- It also optionally integrates with external wearable APIs (Fitbit, Apple Watch, Garmin).

##### File structure
- Top-level:
- src/
- health_data/ (git-ignored local data store)
- .env (holds wearable API keys)
- package.json, .gitignore, README.md, LICENSE
- src/ contains:
- index.js – entrypoint that registers the MCP server
- tools/ – implementations of each “tool” (record_biometrics, get_health_summary, etc.)
- integrations/ – external API clients for Fitbit, Apple Watch, Garmin
- utils/ – shared helper functions (e.g., date parsing, file I/O)
- No frontend folder: the “client” is the AI assistant, communicating via an MCP wire protocol.

##### README for additional insights
- Lists available tools and their responsibilities.
- Specifies that all health data is stored locally under health_data/.
- Explains configuration for Claude Desktop to launch this server.

a. Main components
1. AI Assistant Client (Claude Desktop or other)
2. MCP Server (Node.js process)
- index.js (MCP server bootstrap)
- tools/ modules
- integrations/ modules
- utils/ modules
3. Local Data Store (health_data directory, file-based or lightweight DB)
4. External Wearable Services (Fitbit API, Apple Health, Garmin API)

b. Relationships and interactions
- AI Assistant → MCP Server: sends commands (JSON-RPC or similar)
- MCP Server → tools/: dispatches incoming commands to the correct tool
- tools/ → Local Data Store: read/write biometric data
- tools/ → integrations/: when syncing with wearable services, authenticate via .env keys and call external REST APIs
- MCP Server → AI Assistant: returns structured responses or insights

c. Key architectural patterns
- Modular “tool” pattern: each user-facing capability is encapsulated as its own module
- Adapter pattern for integrations: isolating wearable API clients behind a uniform interface
- Local persistence: simple file-based or embedded DB to keep data on the user’s machine
- Protocol adapter: the MCP server acts as a protocol translator between the AI assistant and the internal modules

d. Relevant technologies
- Node.js with npm modules
- JSON, REST for external service calls
- .env for configuration (dotenv)
- File I/O or lightweight DB (e.g., lowdb or similar) for health_data

##### Detailed breakdown
- A → B1 (MCP commands)
- B1 → B2 (dispatch to tools)
- B2 → C (read/write)
- B2 → B3 → D# (external sync)
- B2 → B1 → A (responses, insights)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    AI["AI Assistant Client"]:::client

    %% Server
    subgraph "MCP Server (Node.js)"
        IE["index.js\n(Protocol Adapter)"]:::server
        TM["tools/\nModule"]:::module
        IM["integrations/\nModule"]:::module
        UM["utils/\nModule"]:::module
    end

    %% Data Store
    DS["Local Health Data Store\n(health_data/)"]:::db

    %% External Services
    subgraph "External Wearable Services"
        FIT["Fitbit API"]:::external
        APP["Apple Watch API"]:::external
        GAR["Garmin API"]:::external
    end

    %% Configuration & Docs
    ENV["Configuration\n(.env)"]:::config
    PM["package.json"]:::config
    RD["README.md"]:::doc
    GI[".gitignore"]:::doc
    LI["LICENSE"]:::doc

    %% Relationships
    AI -->|"MCP JSON-RPC"| IE
    IE -->|"dispatch command"| TM
    TM -->|"read/write"| DS
    TM -->|"use integration"| IM
    IM -->|"REST API calls"| FIT
    IM -->|"REST API calls"| APP
    IM -->|"REST API calls"| GAR
    TM -->|"helper utils"| UM
    IE -->|"response"| AI
    ENV -.-> IM

    %% Click Events
    click IE "https://github.com/jprbom/-health-dashboard-mcp/blob/main/src/index.js"
    click TM "https://github.com/jprbom/-health-dashboard-mcp/tree/main/src/tools/"
    click IM "https://github.com/jprbom/-health-dashboard-mcp/tree/main/src/integrations/"
    click UM "https://github.com/jprbom/-health-dashboard-mcp/tree/main/src/utils/"
    click DS "https://github.com/jprbom/-health-dashboard-mcp/tree/main/health_data/"
    click ENV "https://github.com/jprbom/-health-dashboard-mcp/blob/main/.env.example"
    click PM "https://github.com/jprbom/-health-dashboard-mcp/blob/main/package.json"
    click RD "https://github.com/jprbom/-health-dashboard-mcp/blob/main/README.md"
    click GI "https://github.com/jprbom/-health-dashboard-mcp/blob/main/.gitignore"
    click LI "https://github.com/jprbom/-health-dashboard-mcp/tree/main/LICENSE"

    %% Styles
    classDef client fill:#f2f2f2,stroke:#333,stroke-width:2px;
    classDef server fill:#e6f7ff,stroke:#333,stroke-width:2px;
    classDef module fill:#e8f5e9,stroke:#333,stroke-width:1px;
    classDef db fill:#fff3e0,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#ffebee,stroke:#e53935,stroke-width:2px,stroke-dasharray: 5 5;
    classDef config fill:#fffde7,stroke:#333,stroke-width:1px;
    classDef doc fill:#f3e5f5,stroke:#333,stroke-width:1px;
```
