How openlmis/openlmis-ref-distro works
<explanation>
1. Project Type and Purpose
- This is a full‑stack, containerized reference distribution for OpenLMIS v3+.
- It uses Docker Compose to assemble a suite of microservices (the core OpenLMIS Services), a UI layer (reference UI modules), infrastructure pieces (configuration container, syslog container, database), and an optional reporting pipeline (Debezium, NiFi, Superset, cron jobs).
- It also includes extensions/integrations (DHIS2, stock‑management validators, one‑network extensions).
2. File‑Structure Analysis
- Top‑level:
• .env, docker-compose.yml, start/stop scripts → orchestrator of the entire stack
• config/ → configuration container definition (Dockerfile + mounted volumes)
• dhis2/ → optional DHIS2 integration stack (with its own docker‑compose)
• reporting/ → reporting subsystem (Debezium Connect, NiFi, Superset, reporting DB, cron jobs + Compose files)
• docs/ → Sphinx‑based architecture and component documentation
• utils/ → assorted helper containerized tools (awscli, browsermob‑proxy, bzt‑yarn, etc.)
- Notice multiple Compose override files for different extensions and data‑load modes.
3. README Insights
- Describes how the Docker Compose files are the “authoritative” assembly of services.
- Explains the configuration container pattern via a named volume (service‑config).
- Describes the logging container (log) capturing syslog from services.
- Outlines how to load demo data, performance data, and refresh profiles.
- Details optional components: DHIS2, extensions, reporting pipeline.
4. Main Components for the Diagram
a. Core Services Cluster
- Box: “OpenLMIS Core Microservices” (each as a sub‑box or swimlane):
• ReferenceData, StockManagement, Requisition, Fulfillment, Notification, Report, Auth, CCE, etc.
- These expose REST APIs.
b. API Gateway / Reverse Proxy
- Nginx + consul‑template container → routes HTTP traffic from browser to UI modules and services.
c. UI Modules
- Reference UI front‑end modules (served via Nginx, static assets).
d. Configuration Container
- config image providing /config volume to all services.
e. Database Layer
- Postgres container for core services
- Separate Postgres (or other) for reporting, initialized by SQL scripts.
f. Logging
- Syslog container collecting logs from services via Docker logging or rsyslog.
g. Reporting Pipeline
- Debezium Connect (captures CDC from core DB)
- Apache NiFi (ingests, transforms, loads into reporting DB)
- Reporting DB container
- Superset container (visualization/dashboard)
- Cron job container (periodic queries or MV refreshes)
h. Integrations / Extensions
- DHIS2 stack (own DB, config, Compose file)
- One‑network, OpenLMIS extensions (separate Compose overlays)
i. Utility Containers (optional)
- AWS CLI, Browsermob Proxy, bzt-yarn, snapshot tools, ERD generator, etc.
5. Relationships & Data Flows
- Browser → Nginx → UI Modules → Core Microservices (HTTP REST)
- Core Microservices ↔ Core DB (JDBC over private Docker network)
- All services mount service‑config volume from Config container at /config
- All services send logs → Syslog container (rsyslog over network)
- Debezium Connect → reads from Core DB → publishes change events to Kafka topic
- NiFi → subscribes to Kafka → processes data → writes to Reporting DB
- Superset → reads from Reporting DB → serves dashboards to browser
- Cron jobs → run periodic SQL or REST calls → update materialized views or reports
6. Architectural Patterns & Principles
- Microservices communicating over REST
- Externalized configuration via a dedicated config container + volume
- Centralized logging with a syslog container
- Change‑Data‑Capture for reporting (Debezium + NiFi)
- Docker Compose as the deployment descriptor (infrastructure as code)
- Overlay Compose files for feature toggles (demo data, performance data, extensions)
7. Diagram Tailoring Guidelines
- Use separate swimlanes or clusters for:
• Core Application
• Persistence (Databases)
• Configuration & Logging
• Reporting Pipeline
• Integrations/Extensions
• Utilities (optional)
- Highlight service‑to‑service calls and DB connections with directional arrows.
- Group related containers in colored boxes:
• Blue for Core Services
• Green for Infrastructure (Config / Logging)
• Orange for Reporting
• Purple for Extensions
- Show Docker networks (e.g., “default”, “reporting_net”, “dhis2_net”) if relevant.
8. Diagram Elements to Include
- Boxes with clear labels for each container or logical component.
- Arrows indicating HTTP, JDBC, syslog, CDC/Kafka, NiFi flows.
- Legend or color‑coding to distinguish:
• Compute containers (services)
• Data stores (Postgres)
• Configuration & Logging
• Data‑flow connectors (Debezium, NiFi, Cron)
- Optional: annotate volumes (e.g., service‑config, syslog) and environment files (.env, settings.env).
By following this breakdown, you will produce a detailed container‑level architecture diagram that accurately captures the OpenLMIS Reference Distribution’s essential components, their relationships, and the Docker‑based deployment conventions this project embodies.
</explanation>