# synthetichealth/synthea architecture

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

- Interactive diagram: https://gitdiagram.com/synthetichealth/synthea
- Repository: https://github.com/synthetichealth/synthea

## Overview

##### Main Components
- Modules & Rule System: The project uses “modules” stored in the resources directory (e.g., under src/main/resources/modules) to define simulation rules, disease progression, lifecycle events, and demographics. This forms the modular rule system that drives individual patient simulation.
- World and Agents: The org.mitre.synthea.world package contains the definitions for simulated entities (e.g., Patient, Clinician, Provider, Payer). This part of the system models interactions and behaviors in the “world” of the simulation.
- Exporters: Multiple exporters (e.g., FHIR export, CCDA, CSV, CPCDS) are defined under org.mitre.synthea.export and its sub-packages. They transform generated simulation data into various output formats for consumption.
- Configuration & Resources: Configuration files (found in config and in src/main/resources) supply key simulation parameters, cost files, simulation modules, demographic data, physiology XML configurations, templates (for CCDA), and lookup tables.
- GraphViz Integration: Components like Graphviz.java support rendering simulation rules and modules visually. This rendering tool integrates with the simulation engine to provide graphical representations.
- Build and CI/CD: Although not the focus of the runtime system, the Gradle build files, wrapper scripts, and GitHub workflows (inside .github) indicate the automated build, test, and deployment pipeline used in development.

##### Relationships and Interactions
- The Simulation Engine reads configuration, modules, and templates from the configuration and resource directories. It uses the Modular Rule System and Physiological Models (under “physiology”) to simulate the lifecycle of synthetic patients.
- The World/Agents modules are used to model individual entities (patients, payers, providers, etc.) and govern the interactions among them. The simulation engine drives state transitions in the life of each patient.
- Graphviz (and helper classes) interact with the engine to produce visualizations of modules, which in turn feed back into the developer workflow.

##### Architectural Patterns and Design Principles
- Modularity: The system is divided clearly into simulation logic, rule/configuration modules, patient "world" agents, and export functionality.
- Separation of Concerns: Simulation and export functionality are separated, so each aspect of patient simulation and data output is encapsulated.
- Extensibility: The module framework (with drop-in JSON modules and custom Java rule modules) shows clear intent for extensibility and customization.

##### Elements
- Optionally, include a feedback loop from the Graphviz rendering tool back to the simulation engine to underline the visualization capability.
- If desired, include a build/integration section (e.g., Gradle build & CI workflows) to complete the overall architecture picture even though it may be viewed as “infrastructure.”

## Diagram (Mermaid)

```mermaid
graph TD
    %% Configuration & Resources Subgraph
    subgraph "Configuration & Resources"
        CR1["Config Files"]:::config
        CR2["Resource Files"]:::config
    end

    %% Build & CI/CD Subgraph
    subgraph "Build & CI/CD"
        CI1["CI Workflows"]:::build
        CI2["Gradle Build"]:::build
    end

    %% Modules & Rule System
    MS["Modules & Rule System"]:::modules

    %% World & Agents Subgraph
    subgraph "World & Agents"
        WA1["World"]:::world
        WA2["Agents"]:::world
    end

    %% Core Simulation Engine
    SE["Simulation Engine"]:::engine

    %% GraphViz Integration
    GV["GraphViz Integration"]:::graphviz

    %% Exporters
    EX["Exporters"]:::exporters

    %% Data Flow Connections
    CR1 --> SE
    CR2 --> SE
    MS --> SE
    WA1 --> SE
    WA2 --> SE
    CI1 -->|"build_triggers"| SE
    CI2 -->|"build_triggers"| SE
    SE --> EX
    SE <--> GV

    %% Click Events
    click SE "https://github.com/synthetichealth/synthea/tree/master/src/main/java/org/mitre/synthea/engine"
    click MS "https://github.com/synthetichealth/synthea/tree/master/src/main/resources/modules"
    click WA1 "https://github.com/synthetichealth/synthea/tree/master/src/main/java/org/mitre/synthea/world"
    click WA2 "https://github.com/synthetichealth/synthea/tree/master/src/main/java/org/mitre/synthea/world/agents"
    click EX "https://github.com/synthetichealth/synthea/tree/master/src/main/java/org/mitre/synthea/export"
    click CR1 "https://github.com/synthetichealth/synthea/tree/master/config"
    click CR2 "https://github.com/synthetichealth/synthea/tree/master/src/main/resources"
    click GV "https://github.com/synthetichealth/synthea/blob/master/src/main/java/Graphviz.java"
    click CI1 "https://github.com/synthetichealth/synthea/blob/master/.github"
    click CI2 "https://github.com/synthetichealth/synthea/blob/master/build.gradle"

    %% Styles
    classDef config fill:#daf7a6,stroke:#333,stroke-width:2px;
    classDef modules fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef world fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef engine fill:#f4c2c2,stroke:#333,stroke-width:2px;
    classDef exporters fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef graphviz fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef build fill:#c8c8ff,stroke:#333,stroke-width:2px;
```
