How sharedhealth/hie-docker works
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).