# aphp/fhir-mapbuilder architecture

> Architecture diagram of the GitHub repository aphp/fhir-mapbuilder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aphp/fhir-mapbuilder
- Repository: https://github.com/aphp/fhir-mapbuilder

## Overview

##### Project type and purpose
- This is a two‑part developer tool:
– A Visual Studio Code extension (TypeScript) that provides language support (syntax highlighting, snippets, completions, on‑the‑fly validation) for a custom FHIR mapping language (FML).
– A Java Spring Boot application (fhir‑mapbuilder‑validation) that implements the core validation/compilation/translation engine as a REST API (or launched as a standalone JAR).
- Together they form a “full‑stack” IDE integration: the extension is the UI/client and the Spring Boot service is the backend validation engine.

##### File structure
Top‑level
- .github/workflows – CI/CD pipelines (build, test, release, publish)
- vscode‑extension/ – VS Code extension project
- fhir‑mapbuilder‑validation/ – Spring Boot validation engine
In vscode‑extension/
- src/extension.ts – entry point for the VS Code extension host
- FmlCompletionProvider.ts – supplies code completion items
- FmlValidation.ts – orchestrates validation requests
- MapBuilderJavaProcess.ts – spawns or manages the JAR process
- MapBuilderValidationApi.ts – issues HTTP requests to the local Spring Boot server
- MapBuilderWatcher.ts – watches FML files for changes
- constants/, Models.ts, utils.ts – shared types and constants
- syntaxes/, snippets/ – grammar & snippet definitions
In fhir‑mapbuilder‑validation/
- src/main/java/fr/aphp/mapbuilder/MatchBoxApplication.java – Spring Boot bootstrap
- config/MatchboxEngineConfig.java – DI and engine configuration
- controller/HealthController.java, MatchBoxController.java, ShutdownController.java – REST endpoints
- service/MatchBoxService.java – core validation business logic
- model/*.java – representation of errors (ParsingError, ValidationError, etc.)
- utils/FileUtils.java – file handling
- src/main/resources/application.yaml – server configuration

##### README for additional insights
- Confirms the two‑module structure
- Describes build flow:
– mvn package ⇒ produces fhir‑mapbuilder‑validation.jar
– Move the JAR into vscode‑extension/target
– npm install + vsce package ⇒ .vsix
- Runtime flow:
– Run Spring Boot: mvn spring‑boot:run
– Launch VS Code extension host (F5)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% VS Code Extension Side
    subgraph "VS Code Extension" 
        direction TB
        VSCodeHost["VS Code Extension Host"]:::extension
        EntryPoint["extension.ts"]:::extension
        Watcher["MapBuilderWatcher"]:::extension
        ValidationClient["FmlValidation"]:::extension
        JavaProcessMgr["MapBuilderJavaProcess"]:::extension
        HTTPClient["MapBuilderValidationApi"]:::extension
        CompletionProv["FmlCompletionProvider"]:::extension
        Models["Models.ts"]:::extension
        ApiConsts["ApiConstants.ts"]:::extension
        UiConsts["UiConstants.ts"]:::extension
        UtilsTS["utils.ts"]:::extension
        Grammar["fml.tmLanguage.json"]:::extension
        Snippets["fml-snippets.json"]:::extension
        Tests["extension.test.ts"]:::ci
    end

    %% Backend Side
    subgraph "Spring Boot Validation Engine"
        direction TB
        Bootstrap["MatchBoxApplication.java"]:::backend
        Config["MatchboxEngineConfig.java"]:::backend
        subgraph Controllers
            HealthCtrl["HealthController.java"]:::backend
            ValidateCtrl["MatchBoxController.java"]:::backend
            ShutdownCtrl["ShutdownController.java"]:::backend
        end
        Service["MatchBoxService.java"]:::backend
        subgraph "Domain Models"
            CompErr["CompilationError.java"]:::backend
            ParseErr["ParsingError.java"]:::backend
            ValErr["ValidationError.java"]:::backend
            TransErr["TransformationError.java"]:::backend
        end
        FileUtils["FileUtils.java"]:::backend
        YAML["application.yaml"]:::backend
    end

    %% Artifacts
    JAR["fhir-mapbuilder-validation.jar"]:::artifact
    VSIX[".vsix Package"]:::artifact

    %% CI/CD
    subgraph "CI/CD Pipelines"
        direction TB
        TestCI["test.yml"]:::ci
        ReleaseCI["release.yml"]:::ci
        PublishCI["publish.yml"]:::ci
    end

    %% Relationships
    VSCodeHost --> EntryPoint
    EntryPoint --> CompletionProv
    EntryPoint --> Grammar
    EntryPoint --> Snippets
    EntryPoint --> Watcher
    Watcher --> ValidationClient
    ValidationClient --> JavaProcessMgr
    ValidationClient --> HTTPClient
    JavaProcessMgr --> JAR
    HTTPClient --> HealthCtrl
    HTTPClient --> ValidateCtrl
    HTTPClient --> ShutdownCtrl
    HealthCtrl --> Service
    ValidateCtrl --> Service
    ShutdownCtrl --> Service
    Service --> CompErr
    Service --> ParseErr
    Service --> ValErr
    Service --> TransErr
    Service --> FileUtils
    Bootstrap --> Config
    Bootstrap --> Controllers
    Bootstrap --> Service
    Bootstrap --> YAML

    ValidationClient -->|returns errors| EntryPoint
    EntryPoint -->|show diagnostics| VSCodeHost

    %% Packaging flow
    JAR -->|placed into| EntryPoint
    VSIX -->|installed in| VSCodeHost

    %% CI/CD triggers build and packaging
    TestCI --> JAR
    ReleaseCI --> JAR
    PublishCI --> VSIX

    %% Click Events
    click EntryPoint "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/extension.ts"
    click Grammar "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/syntaxes/fml.tmLanguage.json"
    click Snippets "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/snippets/fml-snippets.json"
    click CompletionProv "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/FmlCompletionProvider.ts"
    click ValidationClient "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/FmlValidation.ts"
    click Watcher "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/MapBuilderWatcher.ts"
    click JavaProcessMgr "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/MapBuilderJavaProcess.ts"
    click HTTPClient "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/MapBuilderValidationApi.ts"
    click Models "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/Models.ts"
    click ApiConsts "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/constants/ApiConstants.ts"
    click UiConsts "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/constants/UiConstants.ts"
    click UtilsTS "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/utils.ts"
    click Tests "https://github.com/aphp/fhir-mapbuilder/blob/main/vscode-extension/src/test/extension.test.ts"
    click Bootstrap "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/MatchBoxApplication.java"
    click Config "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/config/MatchboxEngineConfig.java"
    click HealthCtrl "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/controller/HealthController.java"
    click ValidateCtrl "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/controller/MatchBoxController.java"
    click ShutdownCtrl "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/controller/ShutdownController.java"
    click Service "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/service/MatchBoxService.java"
    click CompErr "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/model/CompilationError.java"
    click ParseErr "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/model/ParsingError.java"
    click ValErr "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/model/ValidationError.java"
    click TransErr "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/model/TransformationError.java"
    click FileUtils "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/java/fr/aphp/mapbuilder/utils/FileUtils.java"
    click YAML "https://github.com/aphp/fhir-mapbuilder/blob/main/fhir-mapbuilder-validation/src/main/resources/application.yaml"
    click TestCI "https://github.com/aphp/fhir-mapbuilder/blob/main/.github/workflows/test.yml"
    click ReleaseCI "https://github.com/aphp/fhir-mapbuilder/blob/main/.github/workflows/release.yml"
    click PublishCI "https://github.com/aphp/fhir-mapbuilder/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef extension fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef backend fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px
    classDef artifact fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef ci fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px
```
