====================
pyTREMOD Architektur
====================

Das Ziel dieser System- und Architekturdokumentation ist es, eine verständliche, nachvollziehbare und
systematische Grundlage für die Kommunikation und Dokumentation der Architektur des neu entwickelten Systems
zu schaffen, indem relevante Ziele und Anforderungen festgehalten, Abrenzungen und Definitionen zusammengetragen
sowie der inhaltliche und technische Aufbau beschrieben werden.

.. _section-introduction-and-goals:

Einführung und Ziele
====================

**Einführung**

Das Emissionsberechnungsmodell „TREMOD“ (Transport Emission Model) wurde vom ifeu-Institut im Auftrag des
Umweltbundesamtes entwickelt und kontinuierlich fortgeschrieben. Das Modell bildet den motorisierten Verkehr in
Deutschland hinsichtlich seiner Verkehrs- und Fahrleistungen, Energieverbräuche und der zugehörigen
Luftschadstoffemissionen typischerweise für den Zeitraum 1960 bis 2050 ab. Die mit TREMOD berechneten Emissionen
von Treibhausgasen und Luftschadstoffen sind unter anderem die Grundlage der deutschen
Emissionsberichterstattung für den Sektor „Verkehr“. Das Emissionsberechnungsmodell TREMOD (Transport Emission Model)
wurde vom ifeu-Institut im Auftrag des Umweltbundesamtes entwickelt und wird kontinuierlich fortgeschrieben, wobei
das Modell ursprünglich in MS Access implementiert wurde.


**Ziele**

Angesichts stetig steigender Anforderungen an die Datenverarbeitung und der Notwendigkeit zur Integration
komplexerer Berechnungen (wie z.B. die bereits efolgte detaillierte Erfassung von Nicht-CO2-Effekten des Flugverkehrs),
ist eine Überarbeitung der technischen Basis zwingend erforderlich.
Das übergeordnete Ziel dieses Vorhabens ist damit eine Migration in die Programmiersprache Python,
um technische Engpässe aufgrund unter anderem der steigenden Datenmenge und der geringen Ausführungsgeschwindigkeit
von MS-Access zu beseitigen und die Rechenzeiten erheblich zu verkürzen. Zugleich sollen technische,
inhaltliche und methodische Altlasten, die sich in der Access-Version (teilweise auch aus archiviarischen Gründen)
seit den 1980er bzw. 1990er Jahren aufbauten und erhielten, entfernt und ein kontinuierlicher Wissenstransfer
(fachlich und technisch) durch explizite Dokumentation gewährleistet werden.

.. _`_aufgabenstellung`:

Aufgabenstellung
----------------

Die technische Überführung in die Programmiersprache Python zielt darauf ab, die bisherige Datenbank- und
Softwarearchitektur zu überarbeiten. Konkret sind folgende technische Ziele definiert:

1.  Plattformunabhängigkeit und Ausführung: Die neue TREMOD-Version muss **systemunabhängig** sein und vor allem auf
    **Windows-Festrechnern selbstständig lauffähig** sein.
2.  Architekturverbesserung: Die Softwarearchitektur soll das **mehrschichtige Architekturmuster** verwenden und
    die **Datenbank-Schicht** von der **Berechnungs-** und der **Präsentations-Schicht**
    (Benutzeroberfläche/-interaktion) klarer abgrenzen.
3.  Applikationsaufbau: Aufteilung des Access-Modells in eine **Entwicklungs- und eine **Nutzungsvariante**. Das
    Hauptunterscheidungsmerkmal ist der Umfang der Daten- und Berechnungsschritte. Die Entwicklervariante beinhaltet
    die Datenaufbereitung und sämtliche Modellberechnungen, während die Nutzungsvariante nur jene (Zwischen-)Ergebnis-,
    Definitions- und  Berechnungstabellen, die notwendig sind, um die bisherig verfügbaren Features über die Formulare
    der Access-Version darzustellen.
4.  Datenbanktechnologie: Als Datenbanktechnologien sollen primär **PostgreSQL** (für die Entwicklungs-Variante und als
    zentrale Datenbasis) und ausschließlich **SQLite** (für die Nutzungs-Variante) eingesetzt werden.
5.  Funktionalität und Benutzeroberfläche: **Alle Funktionen der bisherigen Benutzeroberfläche** von TREMOD
    (z. B. MS-ACCESS Formulare) sollen in der neuen Version **beibehalten** werden.

.. _`_qualit_tsziele`:

Qualitätsziele
--------------

Die Migration ermöglicht die Beseitigung von Altlasten und die Erreichung höherer Präzision und Wartbarkeit:

1.  Ergebniskonsistenz: die grundlegende Methodik von TREMOD, einschließlich der Formeln und Algorithmen ist,
    soweit möglich beizubehalten, um eine weitestgehende Ergebnisgleichheit zwischen der ursprünglichen
    MS-Access-Version und der neu entwickelten Python-Version zu gewährleisten. Dies stellt sicher, dass die
    Emissionsberechnung analog zu den Vorjahren erfolgen kann und es durch die technische Umstellung zu keinen
    statistischen Brüchen in den Emissionszeitreihen kommt.
2.  Softwarearchitektur: pyTREMOD basiert auf dem **mehrschichtigen Architekturmuster** (layered architecture pattern),
    wobei eine bessere Wartbarkeit durch die Trennung von Präsentationsschicht, also dem User Interface, Anwendungslogik
    und Datenzugriff zu erreichen. Die Architektur umfasst dabei typische Schichten wie die Präsentationsschicht,
    Geschäftslogikschicht (Emissionsberechnungen) und Datenzugriffsschicht.
3.  Integration neuer Methoden: Die neue Architektur muss die **Integration komplexer, detaillierter Methoden**
    unterstützen. Die Implementierung der kommenden Emissionsfaktoren des Straßenverkehrs aus HBEFA Version 5.1
    (geplant für Herbst 2025) ist über eine separate API-Schnittstelle in das migrierte TREMOD-Modell zu integrieren und
    einer Qualitätsprüfung zu unterziehen.
4.  Datenstruktur: Obsolete Daten und aufgrund der Restriktionen von MS-Access notwendigen Zwischentabellen werden
    entfernt, um mehr Übersichtlichkeit zu schaffen. Die Daten- und Tabellennomenklatur wird konsoidiert.
    Der Datenzugriff erfolgt über die Persistenzschicht, dafür verantwortlich, Anfragen entgegenzunehmen, um Daten
    abzurufen oder zu speichern, indem sie beispielsweise SQL-Anweisungen ausführt, die die entsprechenden Daten aus
    der Datenbank abrufen und für weitere Operationen (zentral) bereitstellt.
5.  **Wissenstransfer und Dokumentation:** Zur Gewährleistung des Wissenstransfers wird die **IT-seitige Umsetzung**
    für das neue Modell in **kompakter Form dokumentiert**. Zudem wird eine **knappe Installations-
    und Bedienungsanleitung** erstellt. Das Refactoring selbst trägt dazu bei, den Code bzw das Modell **einfacher,
    sauberer und leichter verständlich** zu machen.



.. _`_stakeholder`:

Stakeholder
-----------

Die wichtigsten Stakeholder des TREMOD-Migrationsprojekts sowie ihre Erwartungen sind in nachstehender Tabelle gelsitet.

.. csv-table:: Stakeholder im TREMOD-Migrationsprojekt
    :header: "Rolle", "Kontakt", "Erwartungshaltung"
    :width: 100%
    :widths: 15 30 55
    :align: center

    "Auftraggeber", "Umweltbundesamt, Wörlitzer Platz 1, 06844 Dessau-Roßlau (UBA)", "TREMOD (MS-Access Applikation)
    soll in eine technisch überarbeitete Version in der Programmiersprache Python überführt werden,
    die systemunabhängig und auf Windows-Festrechnern selbstständig lauffähig ist, und dabei die Funktionen der
    bisherigen Benutzeroberfläche beibehält, Ergebnisgleichheit mit der alten Access-Version gewährleistet und die
    Emissionsdaten für die deutsche Emissionsberichterstattung (NIR, VEdV, KSG) bereitstellt."
    "Entwickler", "ifeu - Institut für Energie- und Umweltforschung Heidelberg gGmbH, Wilckensstr. 3,
    69120 Heidelberg (ifeu)", "Die Überführung des TREMOD-Modells in eine systemunabhängige Python-Version unter
    Beibehaltung aller bisherigen Benutzeroberflächen-Funktionen. Einfachere Wartbarkeit und Erweiterbarkeit durch die
    Überführung auf Python und die Nutzung eines mehrschichtigen Architekturmusters sowie Konsolidierung der fachlichen
    und technischen Dokumentation."

.. _section-architecture-constraints:

Randbedingungen
===============

Aus der Aufgabenstellung ergeben sich folgende wesentliche architektonische Randbedingungen, die eingehalten werden
müssen.

.. csv-table:: Architektonische Randbedingungen
    :header: "Kategorie", "Randbedingung"
    :width: 100%
    :widths: 40 60
    :align: center

    "Technologie/Sprache", "Die gesamte Anwendung (Berechnung und Benutzeroberfläche) ist in Python und mit für
    diese Sprache frei verfügbaren (Open-Source) Frameworks und Modulen zu entwickeln, wie beispielsweise
    PySide, Pandas, Numpy."
    "Datenbank (Dualität)", "Es ist die Verwendung von PostgreSQL (Entwicklung/Remote) und
    SQLite (Nutzungs-Variante/Offline-Entwicklung) zu Verwenden."
    "Legacy-Datenabgleich", "Ergebnisse und Zwischenergebnisse der neuen Version müssen mit der letzten
    MS-Access-Version verglichen und Abweichungen dokumentiert und begründet werden."
    "Schnittstellen", "Die Anwendung muss weiterhin die Übergabe der TREMOD-Ergebnisse im ZSE-Format
    (Zentrales System Emissionen) ermöglichen. Ferner werden die Emissionsfaktoren des HBEFA über dessen API in das
    System eingebunden und definierte qualitätssichernden Routinen nach Abfrage der Daten ausgeführt."
    "Quellcode-Verwaltung", "Die Versionsverwaltung muss über Git (intern gehostete GitLab-Instanz) erfolgen,
    und der Quell-Code muss dem UBA zur Verfügung gestellt werden."
    "Deployment / Hardware", "Die Nutzervariante muss auf üblichen Büro-Festrechnern oder -Notebooks mit der
    aktuell verwendeten Windows OS Version des Umweltbundesamtes lauffähig und nutzbar sein. Als Referenz dient ein
    Notebook mit Windows 11 und 8GB RAM. Für die Entwicklungsvariante müssen alle notwendigen Abhängigkeiten zur
    Inbetriebnahme/Lauffähigkeit auf Drittsystemen dokumentiert sein. Die Hardwarelimitationen der Nutzer-Variante
    gelten hier nicht."
    "Freigabe", "Die fachliche und methodische Freigabe bei Änderungen gegenüber der Access-Version, beispielsweise
    durch die Implementierung der neuen HBEFA-Version obliegt dem Umweltbundesamt."
    "Versionierung", "Die Versionierung erfolgt gemäß der Fertigstellung fachlicher Inhalte, z.B. Emissionsinventar nach
    Absprache mit dem UBA."
    "Funktionaler Umfang (Scope)", "Das Modell deckt alle relevanten Verkehrsträger für die Emissionsbilanzierung ab,
    wie Straßenverkehr (Pkw, LNF, SNF, Busse, MZR), Schienenverkehr, Binnenschifffahrt, Mobile Maschinen und Luftverkehr
    (von Deutschland abgehender Flugverkehr bis zur ersten Zwischenlandung). Die Nutzervarianten bietet für all diese
    Kategorien ein entsprechendes User-Interface, dass die Möglichkeiten der Access-Version wiederspiegelt. Ferner
    werden die Exportschnittstellen für alle entsprechenden Fachdaten (z.B. ZSE-Schnittstelle) bereitsgestellt.
    Alle Funktionen der bisherigen MS-ACCESS Benutzeroberfläche (z. B. Formulare wie „Common data“, „Results“) sollen
    in der neuen Version beibehalten werden."

.. _section-context-and-scope:

Kontextabgrenzung
=================

Das System im Zentrum dieser Abgrenzung ist das migrierte TREMOD-Modell (Transport Emission Model) in seiner
neuen Python-basierten Architektur. Der Zweck des Systems ist die Modellierung des motorisierten Verkehrs
in Deutschland zur Ermittlung von Verkehrs- und Fahrleistungen, Energieverbräuchen und den zugehörigen
Emissionen von Treibhausgasen und Luftschadstoffen, unter anderem für für die deutsche Emissionsberichterstattung
(NIR, Vorläufige Emissionsdaten des Vorjahres - VEdV nach KSG).

.. _`_fachlicher_kontext`:

Fachlicher Kontext
------------------

Der fachliche Kontext beschreibt die Kommunikationspartner (Interessenten und Nachbarsysteme) und die
ausgetauschten Datenströme, die für die Emissionsberechnung relevant sind.

*Anmerkung: Hinsichtlich der weiteren Nutzergruppen könnte sich der Kreis der Nutzenden aufgrund der Nutzungsbedingungen
aktuell verengen oder aufgrund regulatorischer Vorgaben erweitern.*

.. graphviz::
   :caption: Fachlicher Kontext des migrierten TREMOD-Modells

   digraph G {
       rankdir=LR;
       node [shape=box, fontsize=24];
       edge [fontsize=18];
       compound=true;

       // Datenaufbereitung außerhalb des Clusters

       // Definition des zentralen Systems (Blackbox)
       subgraph cluster_core {
           label = "(Öko-)System TREMOD\n (UBA & Dienstleister)";
           style = "rounded, filled";
           fillcolor = "#e6f3ff";
           fontsize = 26;
           T_Core [label="TREMOD-\n Applikation", shape=box, style="filled", fillcolor="#CCFFCC"];
           T_Prep [label="Daten-\n &\n Methodikaufbereitung", shape=box, style="filled", fillcolor="#FFE6CC"];
           T_Prep -> T_Core [label="aufbereitete\nDaten"];
           T_Prep -> T_Core [label="Methodikimplementierung"];
       }
       // Externe Kommunikationspartner / Datenquellen
       A [label="Umweltbundesamt\n(UBA) / Nutzer"];
       B [label="DESTATIS & KBA\n(Statistiken/Bestand)"];
       C [label="HBEFA Konsortium\n(Emissionsfaktoren)"];
       D [label="Deutsche Bahn AG\n (Betriebs-/Emissionsdaten)"];
       E [label="AG Energiebilanzen / BAFA\n(Kraftstoffabsatz)"];
       F [label="Weitere Modelle / Prognosen\n (Szenariendaten/Methodik)"];
       G [label="Weitere Nutzer\n (Institute, Behörden, etc)"];
       H [label="Weitere\n Wissenschaftsgemeinschaft\n (Methodiken, Statistiken,\n Emissionsfaktoren)"];


       // Input-Flüsse zur Datenaufbereitung
       A -> T_Core [label="Dateninput & Methodikfreigabe", lhead=cluster_core];
       B -> T_Prep [label="Datenbereitstellung"];
       C -> T_Prep [label="Datenbereitstellung"];
       D -> T_Prep [label="Datenbereitstellung"];
       E -> T_Prep [label="Datenbereitstellung"];
       F -> T_Prep [label="Daten- und Methodikinput"];
       H -> T_Prep [label="Daten- und Methodikinput"];

       // Output-Flüsse vom Modellkern
       T_Core -> A [label="Output"];
       T_Core -> G [label="Output"];
   }

Nachstehende Tabelle präzisiert den skizzierten Fachkontext sowie die Daten- und Informationsflüsse.

.. csv-table:: Fachlicher Kontext und Datenflüsse des TREMOD-Modells
    :header: "Kommunikationspartner", "Bereitstellung/Eingabe (Input)", "Ausgabe (Output)"
    :width: 100%
    :align: center
    :widths: 20, 40, 40

    "Umweltbundesamt (UBA) / Hauptnutzer", "CO2-Emissionsfaktoren Kraftstoffe und Strom;
    Fachliche Freigabe der Methodik", "Ergebnisse im ZSE-Format
    (Zentrales System Emissionen); VEdV (Vorläufige Emissionsdaten des Vorjahres);  Emissionsberichterstattung des
    nationalen Inventarberichts (NIR) und Informative Inventory Report (IIR)."
    "Kraftfahrtbundesamt (KBA)", "Bestands- und Neuzulassungsdaten aus dem zentralen Fahrzeugregister", "Keine
    direkten Ausgaben."
    "Statistisches Bundesamt (DESTATIS)", "
    Sonderabfragen zur Binnenschifffahrt, zum Flugverkehr, oder Busverkehr", "Keine
    direkten Ausgaben."
    "Deutsche Bahn AG", "Verkehrsleistungen, Betriebsleistungen, Auslastungsgrade nach Traktionsarten
    (z.B. Dieselanteil), detaillierte Betriebsdaten (Zuggattungen, Baureihen, Motoren), den erfassten Dieselverbrauch
    der DB AG, die Aufteilung des Dieselkraftstoffverbrauchs auf Verkehrsarten wie Personenfernverkehr,
    Personennahverkehr und Güterverkehr inklusive Rangieren, sowie baureihenspezifische Emissionsfaktoren.", "Keine
    direkten Ausgaben."
    "AG Energiebilanzen / BAFA", "Absatzzahlen von Kraftstoffen (z. B. Diesel, Otto, Biokraftstoffe);
    Amtliche Mineralöldaten (AMS) zur VEdV-Ermittlung.", "Keine direkten Ausgaben."
    "HBEFA-Schnittstelle", "Emissionsfaktoren und spezifische Verbrauchsfaktoren des
    Straßenverkehrs", "Keine direkten Ausgaben."
    "Weitere Modelle / Prognosen (BMV, DLR)", "Verkehr in Zahlen (ViZ) zum Abgleich der Verkehrs- und Fahrleistungen,
    Prognosen zur Verkehrsleistungsentwicklung und sozioökonomische
    Randbedingungen (z. B. Gleitende Langfrist-Verkehrsprognose 2022)", "Keine direkten Ausgaben."
    "Weitere Nutzer (Institutionen und Unternehemen, wie ifeu, DB AG, BASt, Destatis)", "ggf. Szenarienanpassungen;
    kein Input.", "Emissionsfaktoren, Emissionen, Fahrzeugbestände, Aktivitätsdaten, etc."



.. _`_technischer_kontext`:

Technischer Kontext
-------------------

.. image:: images/Schaubild_Infratruktur_und_Datenfluss.png

.. csv-table:: Technischer Kontext und Datenflüsse des TREMOD-Modells
    :header: "Komponente", "Beschreibung"
    :width: 100%
    :align: center
    :widths: 20, 80

    "Inputdaten", "Diese werden in Formaten, wie PDF-Berichte, CSV- oder Excel-Dateien bereitgestellt und durch Experten
    mit Hilfe von Tabellenkalkulationsprogrammen oder Analyseprogrammen geprüft und konsolidiert. Die Emissionsfaktoren
    des Straßenverkehrs werden über die API des HBEFA übermittelt. Diese Daten werden über ETL-Prozesse in die zentrale
    Postgresdatenbank der Enwickler-Variante geladen."
    "Entwicklungs-Variante", "Die Entwicklungsvariante beinhaltet Teile der Datenaufbereitung und sämtliche komplexen
    Modellberechnungen (wie zum Beispiel die Integration des HBEFA 5.1 über eine API)."
    "Nutzungs-Variante", "Die Nutzungsvariante (auch Nutzer-Variante genannt) wird nur jene (Zwischen-)Ergebnis-,
    Definitions- und Berechnungstabellen enthalten, die notwendig sind, um die bisherig verfügbaren Features über die
    Formulare der Access-Version darzustellen. Sie soll auf einem Büro-Festrechner oder -Notebook unter MS-Windows
    lauffähig sein."
    "Web-API", "Eine WEB-API zum Abruf von Ergebnistabellen ist optional und soll aktuell nicht umgesetzt werden."
    "Versionsverwaltung", "Die Versionsverwaltung erfolgt mittels Git über eine ifeu-intern gehostete GitLab-Instanz.
    Der Quellcode entwickelter Versionen soll auch auf ein Cloud-Repository, das durch den Auftraggeber festgelegt
    wird, gespiegelt werden."

**Externe technische Schnittstellen**

- **HBEFA 5.1 API:** REST-Schnittstelle zum Bezug von Emissionsfaktoren.
- **SQL-Schnittstelle:** JDBC/ODBC-Verbindung zu PostgreSQL bzw. lokale Datei-Schnittstelle für SQLite.
- **ZSE-Export:** CSV/Excel-basierte Dateischnittstelle für das Umweltbundesamt.

.. _section-solution-strategy:

Lösungsstrategie
================

Um die gesetzten Ziele zu erreichen, basiert die Lösung auf folgenden strategischen Entscheidungen:

1.  **Migration zu Python:** Ablösung der MS-Access-Basis durch eine moderne, plattformunabhängige Architektur in Python. Dies ermöglicht die Nutzung leistungsfähiger Bibliotheken wie Pandas und NumPy für die Datenverarbeitung.
2.  **Mehrschichtarchitektur:** Striktes Layering zur Trennung von UI (PySide6), Geschäftslogik und Datenzugriff (Persistence Layer), um die Wartbarkeit und Testbarkeit zu erhöhen.
3.  **Datenbank-Dualität:** Unterstützung von PostgreSQL für die zentrale Datenhaltung in der Entwicklung und SQLite für die lokale, portable Nutzung in der Anwendervariante.
4.  **Automatisierte Datenaufbereitung:** Integration von ETL-Prozessen zur Konsolidierung heterogener Datenquellen (Destatis, KBA, HBEFA-API).
5.  **Beibehaltung der Methodik:** Sicherstellung der Ergebniskonsistenz durch Portierung der bewährten Berechnungsalgorithmen aus der Access-Version.


.. _section-building-block-view:

Bausteinsicht
=============

.. _`_whitebox_gesamtsystem`:

Whitebox Gesamtsystem
---------------------

**<Übersichtsdiagramm>**

.. graphviz::
   :caption: Whitebox Gesamtsystem

    digraph G {
        // Globale Attribute fuer das Diagramm
        graph [rankdir=TB, splines=spline, nodesep=0.7, ranksep=0.7];
        node [shape=box, style="rounded,filled", fontname="Helvetica"];
        edge [fontname="Helvetica"];

        // Definition der Komponenten und Schichten

        // Externe Systeme (Dritte/Eingangsdaten)
        node [shape=cylinder, style="filled", fillcolor="#99DDFF", color="#3366AA", fontcolor="#000000"];
        DataSources [label="Eingangsdaten (Destatis, KBA, BLE)"];
        HBEFA_API [label="HBEFA 5.1 API"];

        // 1. Praesentationsschicht (Benutzeroberflaeche)
        subgraph cluster_1 {
            label = "Praesentationsschicht (UI)";
            style = "rounded, filled";
            fillcolor = "#F0F0FF";
            node [fillcolor="#FFFFFF"];

            UIAccess [label="UI (PySide6) / Formulare"];
        }

        // 2. Berechnungsschicht (Geschaeftslogik)
        subgraph cluster_2 {
            label = "Berechnungsschicht (Logik)";
            style = "rounded, filled";
            fillcolor = "#CCFFCC";
            node [fillcolor="#FFFFFF"];

            CalculationEngine [label="TREMOD Algorithmen (Python)\n(Verkehr, Energie, Emission)"];
            HBEFA_Integration [label="HBEFA 5.1 Integration (Entw.-Var.)"];

            // Interne Abhaengigkeiten innerhalb der Logik
            HBEFA_Integration -> CalculationEngine [label="Emissionsfaktoren"];
        }

        // 3. Persistenzschicht (Datenzugriffslogik)
        subgraph cluster_3 {
            label = "Persistenzschicht (Datenzugriff)";
            style = "rounded, filled";
            fillcolor = "#FFFFCC";
            node [fillcolor="#FFFFFF"];

            PersistenceLayer [label="Datenzugriffslogik\n(Lese/Schreib)"];
        }

        // 4. Datenbankschicht (Datenhaltung)
        subgraph cluster_4 {
            label = "Datenbankschicht (Datenhaltung)";
            style = "rounded, filled";
            fillcolor = "#FFEEEE";
            node [shape=box, style="filled", fillcolor="#FFDDDD", color="#AA6666"];

            PostgreSQL [label="PostgreSQL (Entwicklungsvariante / Remote)"]; // Entwicklung [1]
            SQLite [label="SQLite (Nutzungsvariante / Offline)"]; // Nutzung [1]
        }

        // Output-System
        node [shape=cylinder, style="filled", fillcolor="#FFDD99", color="#AA8855"];
        ZSE_Output [label="ZSE-Schnittstelle (Ausgabe)"]; // ZSE-Format [2, 3]

        // Definition der Datenfluesse und Abhaengigkeiten (Konnektoren)

        // Externe Abhaengigkeiten
        DataSources -> CalculationEngine [label="Daten Input"];
        HBEFA_API -> HBEFA_Integration [label="API-Abruf"];

        // Interne Schichtenfluesse
        UIAccess -> PersistenceLayer [label="Datenanfragen"];

        CalculationEngine -> PersistenceLayer [label="Daten Lesen/Schreiben"];

        PersistenceLayer -> PostgreSQL [label="Zugriff Entw.-DB"];
        PersistenceLayer -> SQLite [label="Zugriff Nutz.-DB"];

        PostgreSQL -> PersistenceLayer [label="Daten liefern"];
        SQLite -> PersistenceLayer [label="Daten liefern"];

        // Uebergabe der Ergebnisse
        CalculationEngine -> ZSE_Output [label="Ergebnisse (ZSE-Format)"];
    }

Begründung
   Das Gesamtsystem folgt einem klassischen Schichtenmodell, das eine klare Trennung der Verantwortlichkeiten gewährleistet. Die Präsentationsschicht interagiert ausschließlich mit der Persistenzschicht, um Daten anzuzeigen oder Nutzereingaben zu verarbeiten. Die Berechnungsschicht (Business Logic) führt die komplexen Emissionsmodelle aus und nutzt ebenfalls die Persistenzschicht für den Datenzugriff, was eine Datenbankunabhängigkeit (PostgreSQL vs. SQLite) ermöglicht.




Enthaltene Bausteine
   Die Bausteine des Gesamtsystems sind nach funktionalen Schichten gegliedert:

   - **Präsentationsschicht (UI):** Beinhaltet die PySide6-basierten Formulare und Ansichten (z.B. `MainWindow`, `TremodRail`), die dem Nutzer den Zugriff auf Parameter und Ergebnisse ermöglichen.
   - **Berechnungsschicht (Logik):** Das Herzstück des Systems, welches die verkehrsträgerspezifischen Algorithmen (z.B. `RailEmissions`) implementiert.
   - **Persistenzschicht:** Abstrahiert den Zugriff auf die unterschiedlichen Datenbanksysteme (`DatabaseManager`) und stellt ein einheitliches API bereit.
   - **Datenbankschicht:** Sorgt für die physische Speicherung der Daten in PostgreSQL oder SQLite.

Wichtige Schnittstellen
   - **Datenbankschnittstelle:** SQL-basiertes Interface zwischen Persistenzschicht und den Datenbanken.
   - **HBEFA API:** REST-Schnittstelle zum automatisierten Abruf von Emissionsfaktoren (HBEFA 5.1).
   - **ZSE-Export:** Dateibasierte Schnittstelle (CSV/Excel) zur Übergabe der Ergebnisse an das Umweltbundesamt.

.. _`__name_blackbox_1`:

Benutzeroberfläche (UI)
~~~~~~~~~~~~~~~~~~~~~~~

.. graphviz::
   :caption: Whitebox UI (Klassendiagramm)

    digraph classes {
      rankdir=LR;
      "app.database.db_manager.DatabaseManager" [shape=box];
      "app.ui.components.table_view.DataFrameModel" [shape=box];
      "app.ui.components.table_view.TableView" [shape=box];
      "app.ui.views.base_analytical_window.BaseAnalyticalWindow" [shape=box];
      "app.ui.views.definition_tables_window.DefinitionTablesWindow" [shape=box];
      "app.ui.views.main_window.MainWindow" [shape=box];
      "app.ui.views.trmd_allmodes.AllModes" [shape=box];
      "app.ui.views.trmd_aviation.TremodAviation" [shape=box];
      "app.ui.views.trmd_rail.TremodRail" [shape=box];
      "app.ui.views.trmd_road.TremodRoad" [shape=box];
      "app.ui.views.trmd_waterway.TremodWaterway" [shape=box];
      "app.ui.views.trmd_allmodes.AllModes" -> "BaseAnalyticalWindow" [arrowhead=empty];
      "app.ui.views.trmd_waterway.TremodWaterway" -> "BaseAnalyticalWindow" [arrowhead=empty];
      "app.ui.views.trmd_aviation.TremodAviation" -> "BaseAnalyticalWindow" [arrowhead=empty];
      "app.ui.views.main_window.MainWindow" -> "QMainWindow" [arrowhead=empty];
      "app.ui.views.trmd_road.TremodRoad" -> "BaseAnalyticalWindow" [arrowhead=empty];
      "app.ui.views.trmd_rail.TremodRail" -> "BaseAnalyticalWindow" [arrowhead=empty];
      "app.ui.views.base_analytical_window.BaseAnalyticalWindow" -> "QMainWindow" [arrowhead=empty];
      "app.ui.views.definition_tables_window.DefinitionTablesWindow" -> "QMainWindow" [arrowhead=empty];
      "app.ui.components.table_view.DataFrameModel" -> "QStandardItemModel" [arrowhead=empty];
      "app.ui.components.table_view.TableView" -> "QWidget" [arrowhead=empty];
      "BaseAnalyticalWindow" [shape=ellipse, style=dashed];
      "QMainWindow" [shape=ellipse, style=dashed];
      "QStandardItemModel" [shape=ellipse, style=dashed];
      "QWidget" [shape=ellipse, style=dashed];
    }


.. graphviz::
   :caption: Whitebox UI (Moduldiagramm)

    digraph modules {
      rankdir=LR;
      "app.__init__" [shape=box];
      "app.database.__init__" [shape=box];
      "app.database.db_manager" [shape=box];
      "app.models.__init__" [shape=box];
      "app.ui.__init__" [shape=box];
      "app.ui.components.__init__" [shape=box];
      "app.ui.components.table_view" [shape=box];
      "app.ui.views.__init__" [shape=box];
      "app.ui.views.base_analytical_window" [shape=box];
      "app.ui.views.definition_tables_window" [shape=box];
      "app.ui.views.main_window" [shape=box];
      "app.ui.views.trmd_allmodes" [shape=box];
      "app.ui.views.trmd_aviation" [shape=box];
      "app.ui.views.trmd_rail" [shape=box];
      "app.ui.views.trmd_road" [shape=box];
      "app.ui.views.trmd_waterway" [shape=box];
      "app.utils.__init__" [shape=box];
      "main" [shape=box];
      "app.ui.views.base_analytical_window" -> "app.database.db_manager";
      "app.ui.views.base_analytical_window" -> "app.ui.components.table_view";
      "app.ui.views.definition_tables_window" -> "app.database.db_manager";
      "app.ui.views.definition_tables_window" -> "app.ui.components.table_view";
      "app.ui.views.main_window" -> "app.ui.views.definition_tables_window";
      "app.ui.views.main_window" -> "app.ui.views.trmd_allmodes";
      "app.ui.views.main_window" -> "app.ui.views.trmd_aviation";
      "app.ui.views.main_window" -> "app.ui.views.trmd_rail";
      "app.ui.views.main_window" -> "app.ui.views.trmd_road";
      "app.ui.views.main_window" -> "app.ui.views.trmd_waterway";
      "app.ui.views.trmd_allmodes" -> "app.ui.views.base_analytical_window";
      "app.ui.views.trmd_aviation" -> "app.ui.views.base_analytical_window";
      "app.ui.views.trmd_rail" -> "app.ui.views.base_analytical_window";
      "app.ui.views.trmd_road" -> "app.ui.views.base_analytical_window";
      "app.ui.views.trmd_waterway" -> "app.ui.views.base_analytical_window";
      "main" -> "app.ui.views.main_window";
    }

Zweck/Verantwortung
   Die Benutzeroberfläche ermöglicht dem Anwender die Interaktion mit dem Modell, die Auswahl von Szenarien und die Visualisierung von (Zwischen-)Ergebnissen. Sie ist mit PySide6 implementiert und folgt dem Muster einer Desktop-Applikation.

.. _section-glossary:

Glossar
=======

**Erstellt agelehnt an:**

.. image:: images/arc42-logo.png
    :width: 100px
    :align: left


arc42, das Template zur Dokumentation von Software- und Systemarchitekturen.
Template Version 8.2 DE. (basiert auf AsciiDoc Version), Januar 2023
Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. Siehe https://arc42.org.

