How gematik/spec-vsdm2 works
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.