How hl7/fhir-ig-publisher works
Project Type and Purpose
• This is a Java-based tool that takes a set of inputs (implementation guide artifacts) and produces a standard FHIR Implementation Guide. It is not an authoring environment per se but rather a publishing engine that transforms and validates inputs.
• The project is built with Apache Maven and supports both local execution and Docker-based execution.
• CI/CD integrations (using Azure, GitHub workflows, and various pipeline YAMLs) are also a critical component of the overall architecture.
File Structure for Architectural Clues
• “org.hl7.fhir.publisher.cli” – This Maven module produces the executable command-line interface (CLI) jar. It is the entry point for users invoking the publisher.
• “org.hl7.fhir.publisher.core” – The largest module housing the core logic. It encapsulates packages for:
– IG tool functionalities (e.g., input fetching, validation, configuration, dependency analysis).
– A “publisher” subpackage that likely orchestrates the publishing workflow.
– “modules”, “renderers”, “templates”, “web”, “ui” – These indicate a layered architecture responsible for processing inputs, generating outputs (like HTML, PDF, or XML), and possibly managing a graphical or web-based UI.
• CI/CD and deployment files (Dockerfile, various .yml pipeline scripts) – They mark integration points for automated building, testing, and releases.
Main Components
a. User/Client Layer
– Command-line invocations (CLI) and Docker container runs.
– External inputs: IG directories, configuration files, and parameters (e.g., “-ig”, “-tx”).
b. Publisher CLI Module
– Represents the entry point (from “org.hl7.fhir.publisher.cli”).
– Responsible for parsing command-line arguments and initializing the processing flow.
c. Core Processing Module (Publisher Core)
– Contains business logic encapsulated in various packages:
• Input Handling & Fetching (e.g., file loaders, Git utilities, network interactions)
• Validation & Dependency Analysis (e.g., CodeSystemValidator, DependencyAnalyser)
• Transformation & Conversion (e.g., TemplateManager, IGPack2NpmConvertor)
• Rendering Output (various renderers in “org.hl7.fhir.publisher.core/src/main/java/org/hl7/fhir/igtools/renderers”)
• Modules for cross-version compatibility, comparators for IG versions, and extensions.
d. External Services & Infrastructure
– CI/CD systems: Azure Pipelines (master, release, pull request & nightly builds).
– Artifact repositories: GitHub Releases, Sonatype OSSRH.
– Docker containerization (Dockerfile and Docker run instructions).
– External FHIR services (e.g., the tx.fhir.org endpoint mentioned in the VS-Code configuration).
Relationships and Data Flow
– From the CLI, the input is passed to the Publisher Core.
• Within the Core, break down the flow into:
1. Input Loader/Validator subcomponent: fetches files, validates configurations.
2. Core Publishing Engine: applies business logic, dependency checking, and module orchestration.
3. Rendering Engine: converts and generates outputs (HTML, XML, PDFs, etc.) using multiple renderer modules.
– External dependencies (e.g., FHIR terminology service) interact with the Core components during processing.
– CI/CD pipelines (illustrate as a separate infrastructure component) trigger builds, testing, and packaging. Their output (artifact jars, Docker images) then becomes available for deployment or release.
Architectural Patterns and Design Principles
– Modularity: The clear separation into CLI and Core modules, with the Core further decomposed by functionality (loading, processing, rendering).
– Layered architecture: Input Processing, Business Logic, and Output Generation layers.
– Extensibility: The use of subpackages such as “modules”, “renderers”, and “ui” indicates support for adding or customizing parts without affecting the entire system.
– CI/CD Integration: Automated builds and tests guarantee reliability and facilitate rapid release cycles.