# sharedhealth/hie-docker architecture

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

- Interactive diagram: https://gitdiagram.com/sharedhealth/hie-docker
- Repository: https://github.com/sharedhealth/hie-docker

## Overview

##### Project Type and Purpose
- This is a Docker‐based orchestration repository (“HIE-Docker”) whose sole purpose is to stand up a cluster of Health Information Exchange (HIE) microservices (Cassandra cluster, MySQL, Identity Server, Terminology Server, Health-ID Server, MCI Server).
- It is not application code but a DevOps/infrastructure project, using shell scripts and Docker Compose to build and run containers for each service.

##### File Structure
- Top‐level files:
- .gitignore, README.md – documentation
- build-all-services.sh, create-shr-cluster.sh – orchestration scripts
- docker-compose.yml – defines multi‐container services and networks
- cassandra/ – Dockerfile + entrypoint script + CQL loader (mci_locations.cql)
- mysql/ – folder with SQL dumps to initialize the Terminology Server’s MySQL
- Architectural choice: microservices deployed in containers, networked via Docker Compose. Cassandra is run as a 2-node cluster. MySQL holds the TR (terminology) data. Other containers are stateless API services.

##### README for Insights
- Services instantiated:
1. Cassandra (seed + node)
2. MySQL (with optional TR dump)
3. Identity Server (auth/token issuance)
4. Terminology Server (OpenMRS REST API on MySQL)
5. Health-ID Server (generates HIDs)
6. MCI Server (patient registry, stores data in Cassandra)
- Example workflows: authenticating to Identity Server → generating Health-IDs → loading MCI locations → creating patients in MCI.

##### Main Components & Interactions
a. Components:
- Clients (e.g. shr-system-admin, facility-admin)
- API Services:
- Identity Server
- Terminology Server
- Health-ID Server
- MCI Server
- Datastores:
- Cassandra cluster (2 nodes)
- MySQL container
- Orchestration: Docker Compose network, build scripts
b. Relationships:
- Clients → Identity Server (REST signin) → tokens
- Clients + tokens → Health-ID Server (generate HIDs)
- Clients + tokens → MCI Server (create patients)
- MCI Server ↔ Cassandra cluster (persist patient & location data)
- Terminology Server ↔ MySQL (terminology data)
- Scripts invoke Docker Compose to wire all networks and volumes
c. Patterns & Principles:
- Microservices: each service in its own container
- Infrastructure as Code: Docker Compose, Dockerfiles, shell scripts
- Stateful services isolated (Cassandra, MySQL) vs stateless API services
d. Key Technologies: Docker, Docker Compose, Cassandra, MySQL, OpenMRS REST API, shell scripting

##### Final Checklist for the Principal Software Engineer
- Break the system into: Clients, API Services, Datastores, Orchestration Layer.
- Inter‐service communications and data flows.
- Build/run scripts that initialize or bootstrap data (TR dump, CQL loader).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        ScriptBuild["build-all-services.sh"]:::script
        ScriptCreate["create-shr-cluster.sh"]:::script
        Compose["docker-compose.yml"]:::script
    end

    %% Docker Compose Network
    subgraph "Docker Compose Network"
        subgraph Datastores
            CassSeed[(Cassandra Seed Node)]:::db
            CassNode[(Cassandra Node)]:::db
            MySQL[(MySQL)]:::db
            NoteCassandra["Note: entrypoint-wrap.sh loads mci_locations.cql"]:::note
            NoteMySQL["Note: init.sql & tr-dump.sql preload Terminology data"]:::note
        end
        subgraph "API Services"
            Identity["Identity Server\n(HTTP 8085)"]:::service
            Terminology["Terminology Server\n(HTTP 8082)"]:::service
            HealthID["Health-ID Server\n(HTTP 8083)"]:::service
            MCI["MCI Server\n(HTTP 8084)"]:::service
        end
    end

    %% External Clients and Docs
    Clients((Clients)):::external
    Readme["README.md"]:::docs
    Gitignore[".gitignore"]:::docs

    %% Connections
    ScriptBuild --> Compose
    ScriptCreate --> Compose
    Compose -->|wires containers| CassSeed
    Compose --> CassNode
    Compose --> MySQL
    Compose --> Identity
    Compose --> Terminology
    Compose --> HealthID
    Compose --> MCI

    Clients -->|"HTTP /auth\n8085"| Identity
    Identity -->|"Token Response"| Clients
    Clients -->|"HTTP /hid\n8083"| HealthID
    Clients -->|"HTTP /mci\n8084"| MCI

    MCI -->|"CQL 9042"| CassSeed
    MCI -->|"CQL 9042"| CassNode
    Terminology -->|"MySQL 3306"| MySQL

    CassSeed --> NoteCassandra
    MySQL --> NoteMySQL

    Readme --> ScriptBuild
    Readme --> Compose
    Gitignore --> Compose

    %% Click Events
    click ScriptBuild "https://github.com/sharedhealth/hie-docker/blob/master/build-all-services.sh"
    click ScriptCreate "https://github.com/sharedhealth/hie-docker/blob/master/create-shr-cluster.sh"
    click Compose "https://github.com/sharedhealth/hie-docker/blob/master/docker-compose.yml"
    click CassSeed "https://github.com/sharedhealth/hie-docker/tree/master/cassandra/Dockerfile"
    click NoteCassandra "https://github.com/sharedhealth/hie-docker/blob/master/cassandra/entrypoint-wrap.sh"
    click NoteCassandra "https://github.com/sharedhealth/hie-docker/blob/master/cassandra/mci_locations.cql"
    click MySQL "https://github.com/sharedhealth/hie-docker/blob/master/mysql/dumps/init.sql"
    click NoteMySQL "https://github.com/sharedhealth/hie-docker/blob/master/mysql/dumps/tr-dump.sql"
    click Readme "https://github.com/sharedhealth/hie-docker/blob/master/README.md"
    click Gitignore "https://github.com/sharedhealth/hie-docker/blob/master/.gitignore"

    %% Styles
    classDef script fill:#f9f,stroke:#333,stroke-width:1px
    classDef db fill:#ccf,stroke:#333,stroke-width:1px
    classDef service fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#ffc,stroke:#333,stroke-width:1px
    classDef docs fill:#eee,stroke:#333,stroke-width:1px
    classDef note fill:#fff,stroke-dasharray: 3 3,stroke:#999,stroke-width:1px
```
