# gemeente-delft/gemeentelijk-gegevensmodel architecture

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

- Interactive diagram: https://gitdiagram.com/gemeente-delft/gemeentelijk-gegevensmodel
- Repository: https://github.com/gemeente-delft/gemeentelijk-gegevensmodel

## Overview

Stap 1: Projecttype en doel
- Dit project is géén traditionele full-stackapplicatie, maar een open-source datamodel-generator en documentatie-framework.
- Het primaire doel is het Gemeentelijk Gegevensmodel (GGM) als logisch UML-model beschikbaar te stellen, te vertalen naar fysieke databasetabellen (DDL) en te voorzien van uitgebreide documentatie.

Stap 2: Analyse van de bestandsstructuur
- Topniveau:
- README.md, LICENSE, PDF’s en UML-XMI-bestanden (bron-modellen)
- Versiemappen (v1.0.3 t/m v2.3.0) met EA, XMI en templatedefinities
- docs/ voor MkDocs-gebaseerde website en modeldefinities per domein
- tools/ voor codegeneratie, Docker-scripts en Jupyter notebooks
- mkdocs.yml voor documentatieconfiguratie
- Patroon: een duidelijke scheiding tussen
1. Modelleringartefacten (UML, XMI, EA, templates)
2. Documentatie (markdown + MkDocs)
3. Tooling (scripts, notebooks, Docker)

Stap 3: Belangrijke inzichten uit de README
- Het GGM is een logisch UML-model met lagen en domeinen
- Er is een “Code Template Framework” (Enterprise Architect) om DDL te genereren
- Ondersteuning voor externe tools: Enterprise Architect, Bizzdesign, BlueDolphin
- Tooling voor import/export: Jupyter notebooks en shell-scripts

Stap 4: Componenten en interacties voor het systeemschema
##### Componentenidentificatie
- UML-Model Repository
- Versie-mappen met .eap/.qea/.xmi
- Codegeneratie-templates (XML)
- Codegenerator Service
- Enterprise Architect met Code Template Framework
- Input: XMI/EAP_models + templates
- Output: DDL (Oracle, MySQL), CSV exports
- Documentatie-Website
- Markdown-bestanden onder docs/
- MkDocs (mkdocs.yml) genereert statische site
- Tooling Container
- Dockerfile & docker-compose in tools/
- Shell scripts (deploy.sh, process_excel.sh, translate.sh)
- Jupyter Notebooks voor data-manipulatie (tools/notebooks/)
- Version Control & Release Artifacts
- GitHub repo
- Versiemappen (v1.x, v2.x) met gegenereerde artefacten

##### Relaties en dataflow
- Developer checkt UML-model in Git →
- Codegenerator Service leest model + templates → genereert DDL & CSV → commit/output in tools/output of release-mappen
- MkDocs leest docs/ → bouwt en publiceert website
- Tooling Container biedt omgeving voor notebooks → verwerkt Excel/CSV → werkt GGM data bij of converteert

##### Architectuurpatronen en ontwerpprincipes
- Separation of Concerns: modellering, documentatie en tooling strikt gescheiden
- Layered Architecture in het UML-model zelf: horizontale vs. verticale domeinen
- Template-gedreven generatie (Code Template Framework)
- Containerisatie voor reproduceerbaarheid (Docker, Compose)

##### Belangrijke technologieën en libraries
- UML/XMI (Enterprise Architect, ArchiMate)
- Code Template Framework (EA)
- MkDocs (Python, Markdown)
- Jupyter Notebooks (Python)
- Docker, docker-compose, shell-scripts

- Focus op kernfunctionaliteit: GGM-modellering + codegeneratie
- Extensiepunten: nieuwe templates, extra notebooks, ondersteuning voor andere DB’s
- Laat integratie met externe tools (EA, Bizzdesign, BlueDolphin) zien

- Componentenblocks met duidelijke labels (Model Repository, Codegenerator, Documentation Site, Tooling Container, Externe Tools)
- Pijlen voor dataflow (XMI → generator → DDL, docs/ → MkDocs → Site, Excel → notebooks → CSV)
- Blauwe blokken = data/artifact stores
- Groene blokken = verwerkingscomponenten (generator, MkDocs, notebooks)
- Oranje blokken = externe tools/services

Voorbeeldindeling componentdiagram:
[Model Repository]
| (XMI/EAP + templates)
v
[Codegenerator Service: EA + Code Template Framework] ──> [DDL / CSV outputs]
[docs/] ──> [MkDocs] ──> [Website]
[tools/notebooks] ──> [Jupyter Engine] ──> [CSV/JSON exports]
[tools/Docker] ondersteunt alle toolingcomponenten in container omgeving
[Externe Tools: EA viewer, Bizzdesign, BlueDolphin] lezen artefacten direct uit versie-mappen

Let erop dat je in de legenda en titels de gebruikte technologieën benoemt en eventuele versie-mappen opneemt als artifact nodes.
Met deze bouwstenen kun je een volledig en gedetailleerd systeemontwerpdiagram tekenen dat exact de structuur en dataflows van het GGM-project weerspiegelt.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Model Repository
    subgraph "Model Repository" 
        direction TB
        V1["v1.0.3"]:::datastore
        V2["v2.0.0"]:::datastore
        V3["v2.1.0"]:::datastore
        V4["v2.2.0"]:::datastore
        V5["v2.3.0"]:::datastore
    end

    subgraph "Templates" 
        direction TB
        T1["v1.0.3/CodegeneratieTemplates.xml"]:::datastore
        T2["v2.0.0/CodegeneratieTemplates.xml"]:::datastore
        T3["v2.1.0/CodegeneratieTemplates.xml"]:::datastore
        T4["v2.2.0/CodegeneratieTemplates.xml"]:::datastore
        T5["v2.3.0/CodegeneratieTemplates.xml"]:::datastore
    end

    subgraph "Input Models" 
        direction TB
        M1["v1.0.3/gemeentelijk gegevensmodel.eap"]:::datastore
        M2["v1.0.3/gemeentelijk gegevensmodel.xml"]:::datastore
        M3["v2.0.0/gemeentelijk gegevensmodel.eapx"]:::datastore
        M4["v2.0.0/gemeentelijk gegevensmodel EA16.qea"]:::datastore
        M5["v2.0.0/Gemeentelijk Gegevensmodel XMI1.1.xml"]:::datastore
        M6["v2.0.0/Gemeentelijk Gegevensmodel XMI2.1.xml"]:::datastore
    end

    %% Codegenerator Service
    CodeGen["Codegenerator Service\n(EA + Code Template Framework)"]:::process

    %% Outputs from Codegenerator
    DDL["DDL Outputs\n(Oracle, MySQL)"]:::datastore
    CSVOut["CSV Exports"]:::datastore

    %% Documentation Site
    DocsSrc["docs/"]:::datastore
    MkDocs["MkDocs Site Generator"]:::process
    Site["Generated Documentation Website"]:::datastore

    %% Tooling Container
    subgraph "Tooling Container" 
        direction TB
        DockerEnv["tools/Dockerfile & docker-compose.yml"]:::process
        Scripts["Shell Scripts"]:::process
        Nbsrc["tools/notebooks/"]:::datastore
        Jupyter["Jupyter Engine"]:::process
        InputData["tools/input/"]:::datastore
        Outputs["tools/output/"]:::datastore
    end

    %% External Tools
    Ext["Externe Tools\n(EA viewer, Bizzdesign,\nBlueDolphin)"]:::external

    %% Data Flows
    V1 & V2 & V3 & V4 & V5 -->|"contains templates"| T1 & T2 & T3 & T4 & T5
    V1 & V2 -->|"contains models"| M1 & M2 & M3 & M4 & M5 & M6
    M1 & M2 & M3 & M4 & M5 & M6 & T1 & T2 & T3 & T4 & T5 -->|XMI/EAP + templates| CodeGen
    CodeGen -->|generates| DDL & CSVOut

    DocsSrc -->|source markdown| MkDocs
    MkDocs -->|builds site| Site

    DockerEnv & Scripts & Nbsrc -->|runtime env| Jupyter
    InputData -->|process| Jupyter
    Jupyter -->|exports| Outputs

    V1 & V2 & V3 & V4 & V5 -->|release artifacts| Ext
    DDL & CSVOut -->|artifacts| Ext

    %% Click Events
    click V1 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/v1.0.3/"
    click V2 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/v2.0.0/"
    click V3 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/v2.1.0/"
    click V4 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/v2.2.0/"
    click V5 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/v2.3.0/"
    click T1 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v1.0.3/CodegeneratieTemplates.xml"
    click T2 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.0.0/CodegeneratieTemplates.xml"
    click T3 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.1.0/CodegeneratieTemplates.xml"
    click T4 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.2.0/CodegeneratieTemplates.xml"
    click T5 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.3.0/CodegeneratieTemplates.xml"
    click M1 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v1.0.3/gemeentelijk gegevensmodel.eap"
    click M2 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v1.0.3/gemeentelijk gegevensmodel.xml"
    click M3 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.0.0/gemeentelijk gegevensmodel.eapx"
    click M4 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.0.0/gemeentelijk gegevensmodel EA16.qea"
    click M5 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.0.0/Gemeentelijk Gegevensmodel XMI1.1.xml"
    click M6 "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/v2.0.0/Gemeentelijk Gegevensmodel XMI2.1.xml"
    click DockerEnv "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/tools/Dockerfile"
    click Scripts "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/blob/master/tools/deploy.sh"
    click Nbsrc "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/tools/notebooks/"
    click InputData "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/tools/input/"
    click Outputs "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/tools/output/"
    click DocsSrc "https://github.com/gemeente-delft/gemeentelijk-gegevensmodel/tree/master/docs/"

    %% Styles
    classDef datastore fill:#cfe2f3,stroke:#0b5394,color:#073763;
    classDef process fill:#d9ead3,stroke:#38761d,color:#274e13;
    classDef external fill:#fce5cd,stroke:#e69138,color:#974f0c;
```
