Zum Inhalt

Architektur

Die Anwendung lässt sich in eine kleine Anzahl von klaren Ebenen aufteilen.

Für den Einstieg ist diese Schichtenlogik wichtig, weil man so versteht, wo ein Request landet, welche Dateien den UI-Teil zusammenbauen und welche Python-Objekte die eigentliche Geschäftsfunktion auslösen.

Hinweis: Die Tabs unter "Architektur" an der linken Navigationsleiste sind analog zu den folgenden abgebildeten und erklärten Ebenen angeordnet.

0. Architektur-Overview-Diagramm

Architektur-Diagramm

Wir verlaufen nun Ebene für Ebene.

1. UI / Frontend-Layer: Dash und Pages

Das Oberflächen-Layer ist der sichtbare Einstieg für den Nutzer. Die App wird in app.py als Dash-Webanwendung gestartet und an einen Flask-Server gehängt.

Die zentrale Infrastruktur ist:

  • app.py erzeugt mit dash.Dash(...) die Dash-App und stellt den Flaschen-Server server bereit.
  • Die Seiten im Ordner pages werden über use_pages=True in der Dash-App registriert.
  • Die Navigation (Sidebar, Page-Links, Rollenlogik) wird ebenfalls in app.py gesteuert.

Das bedeutet:

  • Der Browser zeigt die Dash-Seiten an.
  • Die Dash-Seiten liefern HTML, Komponenten und Nutzerinteraktionen.
  • Die Page-Definitionen liegen in den Modulen unter pages und sind eine echte UI-Orchestrierung der Business-Funktionen.

Auf dieser Ebene wird die UI nicht in jeder einzelnen Datei „vollständig“ implementiert. Vielmehr bildet app.py den geschützten Einstieg, während die Seitenmodule im Ordner pages die einzelnen Features auftragen.

2. API / Routing-Layer: Flask Blueprints und Page-Routes

Die zweite Schicht ist der API-/Route-Layer. Die App erzeugt zunächst einen Flask-Blueprint namens router in app.py:

  • router = Blueprint('routes', __name__, url_prefix='/api')
  • Danach werden diverse Seite-Module mit setup_routes(router) an den Blueprint gehängt.

Der Effekt ist:

  • Jede Page kann ihre eigenen API-Endpunkte oder Route-Callbacks registrieren.
  • Die Page-Module der Seiten unter pages werden so zu einer gemeinsamen API- und Backend-Integration zusammengebunden.
  • Der Web-UI-Layer reicht an die Backend-Handler weiter, ohne selbst die komplette Python-Logik zu kennen.

Das ist die Schnittstelle zwischen “Browser sieht ein UI” (Frontend) und “Python ruft eine Funktion oder ein LLM-Programm auf” (Backend).

3. Python Backend / Service-Orchestrierung-Layer

Die eigentliche Backend-Logik liegt in den Python-Dateien im Bereich python_functions sowie in den Page-Module-Implementierungen unter pages.

Der zentrale Runtime-Knoten ist energyai_elements.py:

  • Hier werden Rollen, Nutzer, LLM-Interfaces, Stream-Objekte und zentrale Runtime-Services initialisiert.
  • Die Datei erzeugt DATA_LOADER, UNITS_LOADER, PRODUCT_LOADER, LIBRARY_MANAGER, LIB_INDEX, OAI und OAI2.
  • Die LLM-Streaming-Funktionen stream_oai() und start_stream_oai() sorgen dafür, dass Antworten als Stream an die Anwendung weitergegeben werden.

Das heißt:

  • Die App ist keine “dumpfe Zusammenhang”-Implementierung einzelner Funktionen.
  • Sie hat einen zentralen Runtime-State, der beim Start der Anwendung durch energyai_elements.py aufgebaut wird.
  • Die einzelnen Page-Module greifen auf diesen Runtime-State zu, statt alles jedes Mal neu zu konfigurieren.

Diese Ebene ist der zentrale Service-/Orchestrierungs-Layer.

4. Daten- und Cloud-/Storage-Layer

Neben der App und dem Backend steht ein externer Zugriff auf die Datenbasis. Der wichtigste bekannte Zugriffspunkt ist s3connect.py.

Diese Datei stellt die Cloud-/Storage-Klasse s3Client bereit. Die Implementierung greift auf S3/Storage-Assets zu und macht die notwendigen Datenquellen für die App verfügbar.

Der Aufbau sieht ungefähr so aus:

  • Profile, Folder, Buckets und Shared-Umgebungen werden über Cloud-Prefixe adressiert.
  • Die Klasse stellt Methoden für CSV, JSON, Folder-Downloads, Uploads und Datei-Listing bereit.
  • Diese Storage-Logik wird von den Loader- und Library-Services verwendet.

Die wichtigsten Nutzer dieser Cloud-Schicht sind etwa:

Aus Sicht der Architektur ist das der “Warenhaus-/Metadata-/Cloud-Input” der Anwendung. Ein großer Teil der App funktioniert nicht ohne dieses Layer-Setup.

5. External Dependencies: LLM, Secrets und APIs

Die Anwendung arbeitet mit externen Systemen zusammen, die nicht im Code selbst liegen:

  • OpenAI / Azure OpenAI Interface via openaiInterface.py
  • Azure Key Vault Secret Retrieval in energyai_elements.py
  • OAI / OAI2 als runtime-nah aufgesetzte Interface-Objekte
  • Optional weitergehende RAG-/Embedding-Logik über rag

Das ist die LLM- oder “KI-Integration” der Architektur. In der Laufzeit werden die Nutzer- und App-Kontextinformationen aufrufbar gemacht, LLM-Funktionen initialisiert und die Antwort-Streams für die UI-/Serverleistung bereitgestellt.

Die Architektur ist also nicht nur “Flask-Server plus Dash-Seiten”. Es ist ein Zusammenspiel aus:

  • UI-Komponenten
  • API-Router-Schicht
  • Python Backend-Service-Kern
  • Cloud-/Storage-Datenquelle
  • OpenAI-/Azure-LLM-Infrastruktur

6. Cache / Produkt-/Metadaten-Handhabung

Die Code-Base enthält weiterhin eine Produkt-/Metadaten- bzw. Cache-Logik, die das System in seiner Betriebsphase „gefüttert“ hält.

Dazu zählen die Loader-Schichten, aber auch die zentrale Daten- und Runtime-Verbindung in energyai_elements.py. Dort werden unter anderem die Beispieldaten (DATABASE) und Produkt- bzw. LLM-Konfigurationen gezogen.

Die Abstraktion ist:

  • Die App braucht einen persistierbaren Produkt- und Dokumentkontext.
  • Die Daten werden in den Loader-Layers vorbereitet.
  • Die Runtime-Libraries und Seiten greifen darauf zurück.

Das darf in einer High-Level-Architektur nicht als “einfaches cache file” beschrieben werden, sondern eher als “Produkt-/Library-/Datenkontext zur Laufzeit”.

Architektur-Overview

Die Anwendung lässt sich aus Sicht der Sprache und der Verantwortung so sehen:

  1. app.py startet den Web-Server und registriert die UI-/Logik-Module.
  2. Die Page-Module unter pages bauen die Dash-UI und binden die API-Routes ein.
  3. energyai_elements.py baut den Kern-Runtime-State und die LLM-Pipeline auf.
  4. s3connect.py ist die Cloud-/Storage-Bridge für die Datenbasis und Library-Quellen.
  5. Die Runtime-Loader und Library-Services ziehen die Daten und Masken in den Betriebskontext.

Damit ist die Architektur beim ersten Durchlauf vollständig genug: Das System ist eine hybride Dash-/Flask-UI mit Python-Backend-Logik, Cloud-S3-Zugriff, LLM-Ordnern und einer datengetriebenen Page- bzw. API-Trigger-Kette.