# gematik/spec-vsdm2 architecture

> Architecture diagram of the GitHub repository gematik/spec-vsdm2, 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/spec-vsdm2
- Repository: https://github.com/gematik/spec-vsdm2

## Overview

##### Project type and purpose
- This repository is not an application you run but a specification‑and‑artifact project for the “Versichertenstammdatenmanagement (VSDM) 2.0” FHIR profiles and its RESTful API.

##### File structure
- Top‑level:
- docs/ – markdown specs for use‑cases, data models, error codes, context
- src/fhir/… – FSH input definitions and generated FHIR JSON resources
- src/openapi/ – the OpenAPI/YAML definition of the VSDM 2.0 API
- src/examples – small Java example client snippet
- No frontend/backend code: this is purely a spec/project artifacts repository

##### Key components
a. Primary System (Client)
- The “Primärsystem” (e.g. practice management software) that:
- Requests VSD data over FHIR‑REST
- Supplies a PoPP token (Proof‑of‑Patient‑Presence)
b. Fachdienst VSDM 2.0 (FHIR Server)
- Exposes secured FHIR endpoints as defined in vsdm2.yaml
- Hosts the VSDM‑specific FHIR profiles and ValueSets
c. PoPP Token Service
- Issues/validates PoPP tokens, decoupled from VSDM API
d. Telematik Infrastructure (TI 2.0)
- Network/security layer (ZeroTrust principles)
e. Supporting Artifacts
- Profiles & Logical Model (FSH source → generated JSON)
- OpenAPI spec (API contract)

##### Relationships and interactions
- The Primary System performs an HTTPS call to the Fachdienst VSDM 2.0 FHIR API, attaching a PoPP token in the Authorization or custom header.
- The Fachdienst validates the token with the PoPP Service over a secure ZeroTrust channel.
- On success, Fachdienst returns FHIR Bundle/Resources conforming to the VSDM profiles.
- The Primary System ingests and may store the returned data plus the Prüfziffer.

##### Architectural patterns and technologies
- RESTful micro‑API pattern (FHIR over HTTPS)
- Security: OAuth2 / token‑based authorization (PoPP), ZeroTrust network principles
- Specification‑driven design:
- FSH (FHIR Shorthand) → FHIR StructureDefinitions, ValueSets
- OpenAPI for endpoint documentation
- Artefact generation CI: sushi, plantuml/drawio exporters

- Primary System (Client App)
- PoPP Token Service
- VSDM 2.0 FHIR Server (Fachdienst)
- Telematik/ZeroTrust Layer
- Artifact Generators (SUSHI, PlantUML/DrawIO CI)
- Primary → Fachdienst: “FHIR GET /Patient, /Coverage, /Bundle + PoPP token”
- Fachdienst → PoPP Service: “Validate PoPP token”
- Blue for external actors (Primary System, PoPP Service)
- Green for core API component (Fachdienst VSDM)
- Orange for infrastructure/security (Telematik)
- Gray for docs/artifact pipelines
- Notes/annotations:
- File‑paths: src/openapi/vsdm2.yaml, src/fhir/input, src/fhir/fsh-generated, src/drawio, src/plantuml
- “example client” (src/examples/eGKRead.java) calling the API

##### Final advice
- Be exhaustive: capture every logical piece (security, API, profiles, artifact generation).
1) System Context (actors + Fachdienst + TI)
- Keep it high‑level but ensure each repository folder is represented as part of the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    subgraph "External Actors"
        Primary["Primary System (Client App)"]:::external
        PoPP["PoPP Token Service"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        TI["Telematik Infrastructure (ZeroTrust)"]:::infra
    end

    %% Core API Component
    subgraph "Core API"
        FHIRServer["Fachdienst VSDM 2.0 FHIR Server"]:::core
    end

    %% System Context Connections
    Primary -->|"FHIR GET /Patient, /Coverage, /Bundle + PoPP token"| FHIRServer
    FHIRServer -->|"Validate PoPP token"| PoPP
    Primary --- TI
    FHIRServer --- TI

    %% Artifact Pipeline
    subgraph "Artifact & CI Pipeline"
        FSHIn["FSH Source Definitions (src/fhir/input/fsh)"]:::artifact
        SUSHI["SUSHI Config"]:::artifact
        Generated["Generated FHIR JSON Resources"]:::artifact
        OpenAPI["OpenAPI Spec (vsdm2.yaml)"]:::artifact
        subgraph "Diagram Sources"
            Draw1["DrawIO: System Context"]:::artifact
            Draw2["DrawIO: System Overview"]:::artifact
            Plant1["PlantUML: Class Diagram"]:::artifact
            Plant2["PlantUML: Sequence Diagram"]:::artifact
        end
        CI["CI Pipelines"]:::artifact
        Docs["Normative Documentation"]:::docs
        XSD["XML Schema for VSDM"]:::artifact
    end

    %% Artifact Pipeline Connections
    FSHIn --> SUSHI --> Generated
    FSHIn --> Generated
    CI --> Generated
    CI --> OpenAPI
    CI --> Draw1
    CI --> Draw2
    CI --> Plant1
    CI --> Plant2

    %% Links to Documentation
    Docs --> FSHIn
    Docs --> OpenAPI
    Docs --> XSD

    %% Click Events
    click Primary "https://github.com/gematik/spec-vsdm2/blob/main/src/examples/eGKRead.java"
    click OpenAPI "https://github.com/gematik/spec-vsdm2/blob/main/src/openapi/vsdm2.yaml"
    click Generated "https://github.com/gematik/spec-vsdm2/tree/main/src/fhir/fsh-generated/"
    click FSHIn "https://github.com/gematik/spec-vsdm2/tree/main/src/fhir/input/fsh/"
    click PoPP "https://github.com/gematik/spec-vsdm2/blob/main/docs/vsdm_kontext_popp_zt.md"
    click TI "https://github.com/gematik/spec-vsdm2/blob/main/docs/vsdm_kontext_popp_zt.md"
    click SUSHI "https://github.com/gematik/spec-vsdm2/blob/main/src/fhir/sushi-config.yaml"
    click Draw1 "https://github.com/gematik/spec-vsdm2/blob/main/src/drawio/Systemkontext_VSDM2.drawio"
    click Draw2 "https://github.com/gematik/spec-vsdm2/blob/main/src/drawio/Systemueberblick_VSDM2.drawio"
    click Plant1 "https://github.com/gematik/spec-vsdm2/blob/main/src/plantuml/ClassDiagram.VSDM2.infomodell.puml"
    click Plant2 "https://github.com/gematik/spec-vsdm2/blob/main/src/plantuml/gemSpec_VSDM2_Sequenzdiagramm.puml"
    click CI "https://github.com/gematik/spec-vsdm2/blob/main/ .github/workflows/automatic_image_genration.yml"
    click CI "https://github.com/gematik/spec-vsdm2/blob/main/ .github/workflows/main.yml"
    click Docs "https://github.com/gematik/spec-vsdm2/tree/main/docs/"
    click XSD "https://github.com/gematik/spec-vsdm2/blob/main/src/vsds/vsdmschemaverkuerzt.xsd"

    %% Styles
    classDef external fill:#DCEEFB,stroke:#2B6CB0,color:#2C5282
    classDef core fill:#C6F6D5,stroke:#2F855A,color:#276749
    classDef infra fill:#FEFCBF,stroke:#D69E2E,color:#B7791F
    classDef artifact fill:#EDF2F7,stroke:#A0AEC0,color:#4A5568
    classDef docs fill:#F7FAFC,stroke:#CBD5E0,color:#2D3748
```
