# ihtsdo/health-data-analytics architecture

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

- Interactive diagram: https://gitdiagram.com/ihtsdo/health-data-analytics
- Repository: https://github.com/ihtsdo/health-data-analytics

## Overview

##### Project type and purpose
- This is a full-stack, modular healthcare analytics application (“Snolytical”) with:
- A built-in patient data generator (“generator” module)
- A simple domain model (“model” module)
- A Spring Boot REST API server with ingestion pipeline and Elasticsearch persistence (“server” module)
- A Vue.js web UI (“ui” module)
- Optional Synthea JSON modules for richer synthetic data (“synthea-modules”)

##### File structure
- Top-level Maven modules:
- generator/ — Java patient-population generator
- model/ — plain Java POJOs (Patient, ClinicalEvent, etc.)
- server/ — Spring Boot application: ingestion, services, REST controllers, Elasticsearch config, Debian packaging
- ui/ — Vue.js single-page application
- synthea-modules/ — sample Synthea JSON modules
- Key patterns:
- Layered architecture in server: config → ingestion → service → REST controllers → repository
- Plugin-style ingestion sources (FHIR, NDJSON local file, real-time) via HealthDataIngestionSource interface
- Data flow orchestrated by the server CLI arguments for import vs. run

##### README for additional insights
- Core use cases: load Bulk FHIR or native NDJSON patient data → analyze cohorts → run statistical tests → show results on web UI
- Dependencies: Java 17, Spring Boot, Elasticsearch 8.11.x, Vue.js, Maven

- Client Browser / Web UI (Vue.js SPA)
- API Server (Spring Boot)
- Ingestion Pipeline (plugin modules for FHIR, local-NDJSON, real-time JMS, etc.)
- Domain Model (Patient, ClinicalEvent classes from model/)
- Persistence / Search Engine (Elasticsearch cluster)
- Data Generators:
- Built-in generator CLI (generator/)
- Synthea bulk FHIR generator + Synthea modules (synthea-modules/)
- External Services:
- FHIR Terminology Server (Snowstorm) for SNOMED CT lookups
- Optional CPT code loader (files on disk)

1. Data Generation → produces NDJSON FHIR files
2. CLI import arguments (–import-population-fhir or –import-population) invoke ingestion pipeline
3. Ingestion modules fetch or read resources → map to internal ClinicalEvent/Patient model
4. Service layer aggregates, validates, and hands off to repository
5. Repository writes to Elasticsearch indexes (patient, subset, etc.)
6. When server is running, REST controllers expose endpoints consumed by UI
7. UI issues HTTP requests → Server controllers → Service layer → Elasticsearch → back to UI

c. Architectural patterns and design principles:
- Layered MVC-style architecture in server
- Dependency injection (Spring Boot) for config, ingestion sources, services
- Plugin pattern for ingestion sources
- Separation of concerns between data generation, API, and UI

d. Key technologies/frameworks:
- Java 17, Spring Boot, Maven
- Elasticsearch 8.11.x
- Vue.js, TypeScript
- FHIR (NDJSON), SNOMED CT terminology service

##### Elements
- Labels: name each module/component (e.g., “FHIR Ingestion Source”)
- Orange cloud for external FHIR/SNOMED service
- Purple parallelogram for UI

##### Detail recommendations
- Domain model package as an internal sub-block of the server
- Optionally, show sequence:
1. Generate synthetic data
2. Import into API
3. Run analytics via REST
4. In UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Generation Layer
    subgraph "Data Generation" 
        direction TB
        GEN["Generator CLI"]:::jvm
        SYNTHEA["Synthea Modules (JSON)"]:::jvm
    end

    %% Server Layer
    subgraph "API Server (Spring Boot)" 
        direction TB
        subgraph "Configuration" 
            direction TB
            ES_CFG["ElasticsearchConfig"]:::jvm
            ES_PROP["ElasticsearchProperties"]:::jvm
            SWAGGER["SwaggerConfig"]:::jvm
        end
        subgraph "Ingestion Pipeline" 
            direction TB
            HDIS["HealthDataIngestionSource"]:::jvm
            FHIR_SRC["FHIR Ingestion Source"]:::jvm
            NDJSON_SRC["Local NDJSON Source"]:::jvm
            ELASTIC_OUT["ElasticOutputStream"]:::jvm
        end
        subgraph "Domain Model" 
            direction TB
            MODEL["Patient & ClinicalEvent POJOs"]:::jvm
        end
        subgraph "Service Layer" 
            direction TB
            REP_SVC["ReportService"]:::jvm
            PAT_QRY["PatientQueryService"]:::jvm
            CPT_SVC["CPTService"]:::jvm
        end
        subgraph "Repository Layer" 
            direction TB
            PAT_REPO["PatientRepository"]:::jvm
            SUB_REPO["SubsetRepository"]:::jvm
        end
        subgraph "REST Controllers" 
            direction TB
            REST["REST API Endpoints"]:::jvm
        end
    end

    %% UI Layer
    UI["Web UI (Vue.js SPA)"]:::ui

    %% Data Store
    ES["Elasticsearch Cluster"]:::db

    %% External Services
    SNOMED["SNOMED CT Terminology Service (FHIR)"]:::external
    CPT_FILES["CPT Code Files (Disk)"]:::external

    %% Data Flows
    GEN -->|"NDJSON FHIR"| NDJSON_SRC
    SYNTHEA -->|"FHIR JSON"| FHIR_SRC
    NDJSON_SRC -->|":map to Model"| MODEL
    FHIR_SRC -->|":map to Model"| MODEL
    MODEL -->|":validate & aggregate"| REP_SVC
    ES_CFG --> HDIS
    HDIS --> ELASTIC_OUT
    REP_SVC --> PAT_REPO
    REP_SVC --> SUB_REPO
    CPT_FILES --> CPT_SVC
    ELASTIC_OUT --> ES
    PAT_REPO --> ES
    SUB_REPO --> ES
    REST --> REP_SVC
    REST --> PAT_QRY
    PAT_QRY --> ES
    UI -->|HTTP/JSON REST| REST
    SNOMED --> FHIR_SRC

    %% Click Events
    click GEN "https://github.com/ihtsdo/health-data-analytics/tree/ui-prototyping/generator/"
    click SYNTHEA "https://github.com/ihtsdo/health-data-analytics/tree/ui-prototyping/synthea-modules/"
    click MODEL "https://github.com/ihtsdo/health-data-analytics/tree/ui-prototyping/model/src/main/java/org/snomed/heathanalytics/model/"
    click ES_CFG "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/config/ElasticsearchConfig.java"
    click ES_PROP "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/config/ElasticsearchProperties.java"
    click SWAGGER "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/config/SwaggerConfig.java"
    click HDIS "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/ingestion/HealthDataIngestionSource.java"
    click FHIR_SRC "https://github.com/ihtsdo/health-data-analytics/tree/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/ingestion/fhir/"
    click NDJSON_SRC "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/ingestion/localdisk/LocalFileNDJsonIngestionSource.java"
    click ELASTIC_OUT "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/ingestion/elasticsearch/ElasticOutputStream.java"
    click PAT_REPO "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/store/PatientRepository.java"
    click SUB_REPO "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/store/SubsetRepository.java"
    click REP_SVC "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/service/ReportService.java"
    click PAT_QRY "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/service/PatientQueryService.java"
    click CPT_SVC "https://github.com/ihtsdo/health-data-analytics/blob/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/service/CPTService.java"
    click UI "https://github.com/ihtsdo/health-data-analytics/tree/ui-prototyping/ui/"
    click REST "https://github.com/ihtsdo/health-data-analytics/tree/ui-prototyping/server/src/main/java/org/snomed/heathanalytics/server/rest/"
    
    %% Styles
    classDef jvm fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef ui fill:#E8D0FF,stroke:#333,stroke-width:1px
    classDef db fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
```
