# gematik/openhealth-requirements architecture

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

- Interactive diagram: https://gitdiagram.com/gematik/openhealth-requirements
- Repository: https://github.com/gematik/openhealth-requirements

## Overview

##### Project type and purpose
- This is a modular Kotlin/Gradle project providing a **requirement‑extraction engine** (core), exposed both as a **standalone CLI tool** and as a **Gradle plugin**.
- Purpose: scan source files for structured “REQ‑BEGIN/REQ‑END” annotations and produce a CSV of requirement IDs, specs, descriptions, file paths, and line ranges.

##### File structure
- Top‑level Gradle multi‑module build (`settings.gradle.kts`, `build.gradle.kts`, `gradle.properties`).
- `core` module: houses the extraction logic (RequirementExtractor, RequirementMapper) and its tests.
- `cli` module: implements a Main.kt that invokes the core extractor via command‑line options.
- `gradle-plugin` module: registers a Gradle plugin (`RequirementExtractorPlugin`) that delegates to core when the `extractRequirements` task runs.
- Common config files: GitHub Actions workflow, Gradle wrapper, versions TOML.

##### README for additional insights
- Confirms dual‑mode availability (CLI vs plugin).
- Describes input parameters (`--base-path`, `--comment-prefix`, etc.) and output CSV format.

a. Main components
- **User Interfaces**
- CLI Executable (cli.jar with Main.kt)
- Gradle Plugin (`de.gematik.openhealth.requirements` task)
- **Core Extraction Engine** (`RequirementExtractor`, `RequirementMapper` in core module)
- **File System** (source code files scanned, output CSV)
- **Build System** (Gradle, plugin registry, plugin classpath)
b. Relationships & interactions
- User → CLI/Gradle Plugin (invocation)
- CLI/Plugin → Core Engine (API call)
- Core Engine → File System (reads source files, writes CSV)
- Gradle Plugin → Gradle API (task registration & execution)
c. Architectural patterns & design principles
- **Modular layering**:
- Presentation layer: CLI and Plugin modules
- Business logic layer: Core module
- **Plugin architecture**: Gradle plugin uses Gradle’s plugin API to hook into the build lifecycle.
- **Separation of concerns**: extraction logic is independent of how it’s invoked.
d. Key technologies & libraries
- Kotlin/JVM
- Gradle Kotlin DSL for build scripts
- Gradle Plugin API
- Standard file I/O and CSV generation
- JUnit/Kotlin test framework for core tests

## Diagram (Mermaid)

```mermaid
graph TD
    %% User
    User["User"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Executable\n(Main.kt)"]:::cli
        Plugin["Gradle Plugin\n(RequirementExtractorPlugin)"]:::plugin
    end

    %% Business Logic Layer
    subgraph "Core Module"
        direction TB
        RExt["RequirementExtractor"]:::core
        RMap["RequirementMapper"]:::core
        Test["RequirementExtractorTest"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        FS["File System\n(Read source files\nWrite CSV)"]:::external
        GradleAPI["Gradle API"]:::external
    end

    %% Configuration Files
    subgraph "Configuration Files"
        direction TB
        RootBuild["build.gradle.kts\nsettings.gradle.kts"]:::config
        PluginSettings["gradle-plugin/settings.gradle.kts"]:::config
        Versions["gradle/libs.versions.toml"]:::config
        CI[".github/workflows/pull_request.yml"]:::config
    end

    %% Interactions
    User -->|runs CLI| CLI
    User -->|invokes plugin task| Plugin

    CLI -->|"invoke extractor(basePath,commentPrefix)"| RExt
    Plugin -->|"invoke extractor(basePath,commentPrefix)"| RExt

    Plugin -->|registers task| GradleAPI

    RExt -->|maps annotations| RMap
    RExt -->|reads source files| FS
    RMap -->|writes CSV output| FS

    %% Click Events
    click RExt "https://github.com/gematik/openhealth-requirements/blob/main/core/src/main/kotlin/de/gematik/openhealth/requirements/RequirementExtractor.kt"
    click RMap "https://github.com/gematik/openhealth-requirements/blob/main/core/src/main/kotlin/de/gematik/openhealth/requirements/RequirementMapper.kt"
    click CLI "https://github.com/gematik/openhealth-requirements/blob/main/cli/src/main/kotlin/de/gematik/openhealth/requirements/Main.kt"
    click Plugin "https://github.com/gematik/openhealth-requirements/blob/main/gradle-plugin/src/main/kotlin/de/gematik/openhealth/requirements/plugin/RequirementExtractorPlugin.kt"
    click Test "https://github.com/gematik/openhealth-requirements/blob/main/core/src/test/kotlin/de/gematik/openhealth/requirements/RequirementExtractorTest.kt"
    click RootBuild "https://github.com/gematik/openhealth-requirements/blob/main/build.gradle.kts"
    click PluginSettings "https://github.com/gematik/openhealth-requirements/blob/main/gradle-plugin/settings.gradle.kts"
    click Versions "https://github.com/gematik/openhealth-requirements/blob/main/gradle/libs.versions.toml"
    click CI "https://github.com/gematik/openhealth-requirements/blob/main/.github/workflows/pull_request.yml"

    %% Styles
    classDef core fill:#ffe699,stroke:#cc9900,stroke-width:1px
    classDef cli fill:#c2dfff,stroke:#6699cc,stroke-width:1px
    classDef plugin fill:#d5ffd5,stroke:#66cc66,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#e6e6ff,stroke:#6666cc,stroke-width:1px,stroke-dasharray: 2 2
    class User,FS,GradleAPI external
    class RootBuild,PluginSettings,Versions,CI config
```
