# projecttacoma/fqm-execution architecture

> Architecture diagram of the GitHub repository projecttacoma/fqm-execution, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/projecttacoma/fqm-execution
- Repository: https://github.com/projecttacoma/fqm-execution

## Overview

fqm-execution is a library for evaluating FHIR eCQMs whose measure logic is supplied as ELM. Its main workflow accepts a Measure/Library bundle and patient Bundles, executes the CQL/ELM, and returns patient- and population-level results with detailed statements, clauses, and highlighted logic. Related APIs expose data requirements and query filters, gaps-in-care, and FHIR MeasureReports; ValueSet resolution and a CLI are also documented capabilities. The README and tree establish these capabilities, but sampled excerpts do not show the Calculator implementation’s internal call wiring, so those links are omitted.

Main entry points: [`src/calculation/Calculator.ts`](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/Calculator.ts) (Calculator API), [`src/helpers/elm/RetrievesHelper.ts`](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/RetrievesHelper.ts) (Retrieve discovery), [`src/helpers/elm/QueryFilterParser.ts`](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/QueryFilterParser.ts) (Query info), [`src/helpers/elm/ELMHelpers.ts`](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/ELMHelpers.ts) (ELM helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calculation["Measure calculation"]
  node_calculator["Calculator API<br/>[Calculator.ts]"]
  node_cqlengine["CQL execution engine"]
  node_execution["Execution support<br/>[Execution.ts]"]
  node_cli["Command-line interface<br/>[cli.ts]"]
end

subgraph group_analysis["Measure analysis"]
  node_datareq["Data requirements"]
  node_retrieve["Retrieve discovery<br/>[RetrievesHelper.ts]"]
  node_queryinfo["Query info"]
  node_elmhelpers["ELM helpers<br/>[ELMHelpers.ts]"]
  node_dependency["ELM dependencies"]
end

subgraph group_outputs["Results and reports"]
  node_calculatorresults["Detailed results"]
  node_clauseresults["Clause results"]
  node_gaps["Gaps in care"]
  node_measurereport["Measure reports"]
  node_composite["Composite reports"]
  node_html["Logic highlighting<br/>[HTMLBuilder.ts]"]
end

subgraph group_terminology["Terminology resolution"]
  node_valuesethelper["ValueSet preparation<br/>[ValueSetHelper.ts]"]
  node_resolver["ValueSet resolver"]
  node_vsac["VSAC service"]
end

node_caller(("Library caller"))

node_caller -->|"calls calculation"| node_calculator
node_calculator -->|"executes ELM"| node_cqlengine
node_calculator -->|"calculates requirements"| node_datareq
node_calculator -->|"calculates query info"| node_queryinfo
node_calculator -->|"calculates gaps"| node_gaps
node_calculator -->|"builds reports"| node_measurereport
node_retrieve -->|"finds clauses"| node_elmhelpers
node_retrieve -->|"resolves references"| node_dependency
node_queryinfo -->|"finds clauses"| node_elmhelpers
node_execution -->|"prepares ValueSets"| node_valuesethelper
node_resolver -.->|"resolves remotely"| node_vsac
node_cli -->|"invokes calculation"| node_calculator

click node_calculator "https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/Calculator.ts"
click node_execution "https://github.com/projecttacoma/fqm-execution/blob/master/src/execution/Execution.ts"
click node_datareq "https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/DataRequirementHelpers.ts"
click node_retrieve "https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/RetrievesHelper.ts"
click node_queryinfo "https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/QueryFilterParser.ts"
click node_elmhelpers "https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/ELMHelpers.ts"
click node_dependency "https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/ELMDependencyHelpers.ts"
click node_calculatorresults "https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/DetailedResultsBuilder.ts"
click node_clauseresults "https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/ClauseResultsBuilder.ts"
click node_gaps "https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/GapsReportBuilder.ts"
click node_measurereport "https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/MeasureReportBuilder.ts"
click node_composite "https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/CompositeReportBuilder.ts"
click node_html "https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/HTMLBuilder.ts"
click node_valuesethelper "https://github.com/projecttacoma/fqm-execution/blob/master/src/execution/ValueSetHelper.ts"
click node_resolver "https://github.com/projecttacoma/fqm-execution/blob/master/src/execution/ValueSetResolver.ts"
click node_cli "https://github.com/projecttacoma/fqm-execution/blob/master/src/cli.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_calculator,node_cqlengine,node_execution,node_cli toneBlue
class node_datareq,node_retrieve,node_queryinfo,node_elmhelpers,node_dependency toneAmber
class node_calculatorresults,node_clauseresults,node_gaps,node_measurereport,node_composite,node_html toneMint
class node_valuesethelper,node_resolver,node_vsac toneRose
class node_caller toneIndigo
```

## Components

### Measure calculation

- [Calculator API](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/Calculator.ts): `src/calculation/Calculator.ts`
- **CQL execution engine**
- [Execution support](https://github.com/projecttacoma/fqm-execution/blob/master/src/execution/Execution.ts): `src/execution/Execution.ts`
- [Command-line interface](https://github.com/projecttacoma/fqm-execution/blob/master/src/cli.ts): `src/cli.ts`

### Measure analysis

- [Data requirements](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/DataRequirementHelpers.ts): `src/helpers/DataRequirementHelpers.ts`
- [Retrieve discovery](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/RetrievesHelper.ts): `src/helpers/elm/RetrievesHelper.ts`
- [Query info](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/QueryFilterParser.ts): `src/helpers/elm/QueryFilterParser.ts`
- [ELM helpers](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/ELMHelpers.ts): `src/helpers/elm/ELMHelpers.ts`
- [ELM dependencies](https://github.com/projecttacoma/fqm-execution/blob/master/src/helpers/elm/ELMDependencyHelpers.ts): `src/helpers/elm/ELMDependencyHelpers.ts`

### Results and reports

- [Detailed results](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/DetailedResultsBuilder.ts): `src/calculation/DetailedResultsBuilder.ts`
- [Clause results](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/ClauseResultsBuilder.ts): `src/calculation/ClauseResultsBuilder.ts`
- [Gaps in care](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/GapsReportBuilder.ts): `src/calculation/GapsReportBuilder.ts`
- [Measure reports](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/MeasureReportBuilder.ts): `src/calculation/MeasureReportBuilder.ts`
- [Composite reports](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/CompositeReportBuilder.ts): `src/calculation/CompositeReportBuilder.ts`
- [Logic highlighting](https://github.com/projecttacoma/fqm-execution/blob/master/src/calculation/HTMLBuilder.ts): `src/calculation/HTMLBuilder.ts`

### Terminology resolution

- [ValueSet preparation](https://github.com/projecttacoma/fqm-execution/blob/master/src/execution/ValueSetHelper.ts): `src/execution/ValueSetHelper.ts`
- [ValueSet resolver](https://github.com/projecttacoma/fqm-execution/blob/master/src/execution/ValueSetResolver.ts): `src/execution/ValueSetResolver.ts`
- **VSAC service**

### Other components

- **Library caller**

## Connections

- Library caller → Calculator API: calls calculation
- Calculator API → CQL execution engine: executes ELM
- Calculator API → Data requirements: calculates requirements
- Calculator API → Query info: calculates query info
- Calculator API → Gaps in care: calculates gaps
- Calculator API → Measure reports: builds reports
- Retrieve discovery → ELM helpers: finds clauses
- Retrieve discovery → ELM dependencies: resolves references
- Query info → ELM helpers: finds clauses
- Execution support → ValueSet preparation: prepares ValueSets
- ValueSet resolver → VSAC service: resolves remotely
- Command-line interface → Calculator API: invokes calculation