# jmesplana/openmrs_ai_insights architecture

> Architecture diagram of the GitHub repository jmesplana/openmrs_ai_insights, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jmesplana/openmrs_ai_insights
- Repository: https://github.com/jmesplana/openmrs_ai_insights

## Overview

##### Project type and purpose
- This is a full-stack, single-page React application (built with Vite) that provides an AI-powered conversational interface for querying patient data from an OpenMRS server.  It includes both a frontend and a small backend (either an Express.js proxy server locally or serverless functions on Vercel) to handle CORS and streaming.

##### Main components
a. Frontend (Browser)
- Static host / CDN (Vercel or local dev server via Vite)
- React SPA – index.html + bundle served by Vite
- React components (Layout, Sidebar, Patient panels, AiChatPanel, SettingsModal)
- Context provider (OpenMRSContext) for auth & configuration
- Services module (aiService, openMrsService, mockData)
- React Query / Axios for data fetching
b. Backend Proxy
- Local Express proxy (server.cjs) for development on port 3001
- Vercel serverless functions (api/proxy.js, api/stream.js) for production
c. External systems
- OpenMRS REST API (patient data source)
- AI providers:
– OpenAI API (cloud)
– Ollama local LLM server
- (Mock data as a fallback)

##### Relationships and data flows
1. Browser loads React SPA via Vite server or CDN.
2. User authenticates / configures via SettingsModal → stored in React Context.
3. For patient data:
- Components call openMrsService → HTTP to `/api/proxy/*` → proxy forwards to OpenMRS REST API → returns JSON → React Query caches & feeds components.
- If mock mode enabled, openMrsService returns data from mockData.js directly, skipping proxy.
4. For AI queries:
- AiChatPanel calls aiService → HTTP to `/api/stream` (with patient data & prompt) → serverless/local proxy streams events → proxy calls selected AI provider (OpenAI or Ollama) → streams tokens back → aiService pipes tokens to UI.
5. All sensitive credentials and API keys remain on client or in proxy; none stored on external servers.

##### Architectural patterns and design principles
- SPA on the client, clearly separated from backend proxy
- React Context for global state (OpenMRS credentials & settings)
- Service layer (aiService & openMrsService) isolates API logic
- Proxy as BFF (Backend-for-Frontend) to handle CORS, authentication, streaming
- Mock provider for fast development & testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser / React SPA"
        Entry["index.html"]:::resource
        Bootstrap["main.jsx"]:::resource
        App["App.jsx"]:::resource

        subgraph UI["UI Components"]
            Layout["Layout"]:::ui
            Sidebar["Sidebar"]:::ui
            MainContent["MainContent"]:::ui
            AiChatPanel["AiChatPanel"]:::ui
            SettingsModal["SettingsModal"]:::ui
            PatientHeader["PatientHeader"]:::ui
            PatientDemographics["PatientDemographics"]:::ui
            PatientConditions["PatientConditions"]:::ui
            PatientObservations["PatientObservations"]:::ui
            PatientEncounters["PatientEncounters"]:::ui
        end

        Context["OpenMRSContext"]:::context

        subgraph Services["Service Layer"]
            aiService["aiService"]:::service
            openMrsService["openMrsService"]:::service
            mockData["mockData"]:::mock
        end

        ViteConfig["vite.config.js"]:::resource
        Env[".env.example"]:::resource
        vercelConfig["vercel.json"]:::resource
    end

    subgraph "Proxy Server (Express / Serverless)"
        LocalProxy["server.cjs"]:::proxy
        ProxyEndpoint["api/proxy.js"]:::proxy
        StreamEndpoint["api/stream.js"]:::proxy
    end

    ExternalOpenMRS["OpenMRS REST API"]:::external
    ExternalOpenAI["OpenAI API"]:::external
    ExternalOllama["Ollama LLM"]:::external

    %% Flows within SPA
    Entry -->|"loads"| Bootstrap
    Bootstrap -->|"mounts"| App
    App -->|"renders"| Layout
    App -->|"renders"| Sidebar
    App -->|"renders"| MainContent
    App -->|"renders"| SettingsModal

    MainContent -->|"contains"| AiChatPanel
    MainContent -->|"contains"| PatientHeader
    PatientHeader --> PatientDemographics
    PatientHeader --> PatientConditions
    PatientHeader --> PatientObservations
    PatientHeader --> PatientEncounters

    %% Context usage
    SettingsModal -->|"stores config"| Context

    %% Service calls
    AiChatPanel -->|"calls"| aiService
    PatientDemographics -->|"calls"| openMrsService
    PatientConditions -->|"calls"| openMrsService
    PatientObservations -->|"calls"| openMrsService
    PatientEncounters -->|"calls"| openMrsService

    openMrsService -->|"if mock mode"| mockData
    openMrsService -->|"HTTP GET /api/proxy/*"| LocalProxy
    openMrsService -->|"HTTP GET /api/proxy/*"| ProxyEndpoint

    aiService -->|"HTTP POST /api/stream"| LocalProxy
    aiService -->|"HTTP POST /api/stream"| StreamEndpoint

    %% Proxy to externals
    LocalProxy -->|"forwards patient requests"| ExternalOpenMRS
    ProxyEndpoint -->|"forwards patient requests"| ExternalOpenMRS
    LocalProxy -->|"streams to AI provider"| ExternalOpenAI
    LocalProxy -->|"streams to AI provider"| ExternalOllama
    StreamEndpoint -->|"streams to AI provider"| ExternalOpenAI
    StreamEndpoint -->|"streams to AI provider"| ExternalOllama

    %% Return flows
    ExternalOpenMRS -->|"JSON response"| openMrsService
    ExternalOpenAI -->|"stream tokens"| aiService
    ExternalOllama -->|"stream tokens"| aiService

    %% Click events
    click Entry "https://github.com/jmesplana/openmrs_ai_insights/blob/master/index.html"
    click Bootstrap "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/main.jsx"
    click App "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/App.jsx"
    click Layout "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/Layout.jsx"
    click Sidebar "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/Sidebar.jsx"
    click MainContent "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/MainContent.jsx"
    click AiChatPanel "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/AiChatPanel.jsx"
    click SettingsModal "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/SettingsModal.jsx"
    click PatientHeader "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/PatientHeader.jsx"
    click PatientDemographics "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/PatientDemographics.jsx"
    click PatientConditions "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/PatientConditions.jsx"
    click PatientObservations "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/PatientObservations.jsx"
    click PatientEncounters "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/components/PatientEncounters.jsx"
    click Context "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/contexts/OpenMRSContext.jsx"
    click aiService "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/services/aiService.js"
    click openMrsService "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/services/openMrsService.js"
    click mockData "https://github.com/jmesplana/openmrs_ai_insights/blob/master/src/services/mockData.js"
    click LocalProxy "https://github.com/jmesplana/openmrs_ai_insights/blob/master/server.cjs"
    click ProxyEndpoint "https://github.com/jmesplana/openmrs_ai_insights/blob/master/api/proxy.js"
    click StreamEndpoint "https://github.com/jmesplana/openmrs_ai_insights/blob/master/api/stream.js"
    click ViteConfig "https://github.com/jmesplana/openmrs_ai_insights/blob/master/vite.config.js"
    click vercelConfig "https://github.com/jmesplana/openmrs_ai_insights/blob/master/vercel.json"
    click Env "https://github.com/jmesplana/openmrs_ai_insights/blob/master/.env.example"

    %% Styles
    classDef ui fill:#d0e6ff,stroke:#0366d6,color:#0366d6
    classDef context fill:#e6ffe6,stroke:#2e8b57,color:#2e8b57
    classDef service fill:#e6ffe6,stroke:#2e8b57,color:#2e8b57
    classDef mock fill:#f0f0f0,stroke:#888888,color:#555555
    classDef proxy fill:#ffe6cc,stroke:#d2691e,color:#d2691e
    classDef external fill:#f5e6ff,stroke:#800080,color:#800080
    classDef resource fill:#e6f7ff,stroke:#1e90ff,color:#1e90ff
```
