gateway/modules/features/chatAlthaus/COMPONENT_DIAGRAM.md

Komponentendiagramm: Kunden-Chatbot Althaus

Übersicht

Dieses Diagramm zeigt die High-Level-Architektur der Althaus Chatbot-Anwendung mit allen beteiligten Komponenten, Datenflüssen und Kommunikationswegen.

Komponentendiagramm

graph TB
    subgraph "PowerOn Chat UI"
        ChatUI[Chat Interface]
    end
    
    subgraph "PowerOn Platform"
        Gateway[Gateway Backend<br/>Event Scheduler & Data Query API]
        GatewayDB[(PostgreSQL)]
        AIServices[Dynamic AI, Tavily]
    end
    
    subgraph "Tenant althaus-ag.ch"
        subgraph "PowerOn PreProcessing"
            PreProcessing[Pre-Processing Service]
            PreProcessingDB[(PostgreSQL<br/>Memory DB)]
        end
        
        subgraph "MSFT Services"
            PowerBI[Power BI]
            TenantServices[Azure DC, DNA Center]
        end
    end
    
    %% Hauptkommunikation
    ChatUI -->|"Data Queries<br/>User/Password Auth"| Gateway
    Gateway -->|"SQL Queries<br/>X-PP-API-Key"| PreProcessing
    Gateway -->|"Config Update<br/>Daily 01:00 UTC"| PreProcessing
    
    %% Datenfluss
    PowerBI -->|"Rohdaten"| PreProcessing
    PreProcessing --> PreProcessingDB
    PreProcessingDB -->|"Query Results"| Gateway
    Gateway --> ChatUI
    Gateway --> GatewayDB
    
    %% Styling
    classDef platform fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef frontend fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef preprocessing fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef customer fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef database fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    
    class Gateway,AIServices platform
    class ChatUI frontend
    class PreProcessing preprocessing
    class PowerBI,TenantServices customer
    class GatewayDB,PreProcessingDB database

Komponentenbeschreibungen

1. Gateway Backend (gateway.poweron-center.net)

Hauptkomponenten:

• FastAPI Application: Zentrale Backend-Anwendung der PowerOn Platform
• Event Scheduler (chatAlthaus):
  • Täglicher Scheduler um 01:00 UTC
  • Sendet Konfigurations-Updates an Pre-Processing Service
  • Verwendet X-PP-API-Key Header für Authentifizierung
• Configuration Management:
  • Verwaltung von Secrets und Environment-Variablen
  • Verschlüsselung/Entschlüsselung von Secrets
  • Unterstützt verschiedene Umgebungen (dev, int, prod)
• Data Query API:
  • POST /api/v1/dataquery/query - SQL Query ausführen
  • GET /api/v1/dataquery/schema - Datenbankschema abrufen
  • GET /api/v1/dataquery/schema/{table_name} - Tabellenschema abrufen
• PostgreSQL Database: Zentrale Datenbank für Gateway-Daten

Technologie:

• Python/FastAPI
• PostgreSQL
• APScheduler für Event-Management

Externe AI-Services:

• Dynamic AI: LLM Service für AI-Anfragen
• Tavily: Web-Such-Service für Web-Recherchen

2. PowerOn Chat UI (althaus-chat.poweron-center.net)

Hauptkomponenten:

• React Application: Frontend-Interface für den Chatbot
• Authentication: User/Password-basierte Authentifizierung mit JWT-Token

Kommunikation:

• Nutzt 3 Data Query Endpunkte vom Gateway
• Authentifiziert sich mit User/Password beim Gateway
• Erhält Antworten über Gateway API

Technologie:

• React
• REST API Calls

3. Tenant althaus-ag.ch

3.1 PowerOn PreProcessing

Hauptkomponenten:

• FastAPI Application: Pre-Processing Service im Azure-Tenant des Kunden
• Pre-Processing API:
  • POST /api/v1/dataprocessor/update-db-with-config - Datenbank mit Konfiguration aktualisieren
  • Authentifizierung: X-PP-API-Key Header
• PostgreSQL Memory Database:
  • Speichert verarbeitete Daten
  • Wird vom Chat für Queries genutzt

Datenfluss:

• Empfängt Rohdaten aus Power BI Semantikmodell
• Verarbeitet Daten nach konfigurierten Schritten (keep, fillna, to_numeric, dropna, etc.)
• Speichert verarbeitete Daten in Memory Database
• Beantwortet SQL-Queries vom Gateway

Technologie:

• Python/FastAPI
• PostgreSQL
• Azure App Service (im Kunden-Tenant althaus-ag.ch)

3.2 MSFT Services

Power BI Semantikmodell:

• Datenquelle für Rohdaten
• Wird vom Pre-Processing Service gelesen

Azure Domänen-Controller:

• Authentifizierungs-Service
• Wird vom Gateway für Authentifizierung genutzt

DNA Center:

• Netzwerk-Management-Service
• Wird vom Gateway genutzt

Datenfluss

1. Datenaktualisierung (Scheduled)

Power BI Semantikmodell (Tenant althaus-ag.ch)
  → PowerOn PreProcessing (verarbeitet Daten)
  → PostgreSQL Memory DB (speichert verarbeitete Daten)
  
Gateway Event Scheduler (01:00 UTC täglich)
  → POST /api/v1/dataprocessor/update-db-with-config
  → PowerOn PreProcessing (aktualisiert Konfiguration)

2. Chat-Interaktion (User Request)

PowerOn Chat UI
  → POST /api/v1/dataquery/query (mit User/Password Auth)
  → Gateway Data Query API
  → POST /api/v1/dataquery/query (mit X-PP-API-Key)
  → PowerOn PreProcessing
  → PostgreSQL Memory DB (führt Query aus)
  → PowerOn PreProcessing (gibt Ergebnisse zurück)
  → Gateway Data Query API
  → PowerOn Chat UI (zeigt Antwort)

3. AI-Integration

PowerOn Chat UI
  → Gateway (vermittelt AI-Anfragen)
  → Dynamic AI & Tavily (in PowerOn Platform)
  → Gateway (kombiniert Ergebnisse)
  → PowerOn Chat UI (zeigt Antwort)

Authentifizierung

Gateway → PowerOn PreProcessing

• Header: X-PP-API-Key
• Wert: Aus Gateway Config (PREPROCESS_ALTHAUS_CHAT_SECRET)
• Verwendung: Event Scheduler und Data Query API

PowerOn Chat UI → Gateway

• Methode: User/Password
• Token: JWT Token (nach erfolgreicher Authentifizierung)
• Verwendung: Alle API-Calls vom Chat Frontend

Weitere Authentifizierung

• Gateway nutzt Azure Domänen-Controller für zusätzliche Authentifizierung
• Verschiedene API-Endpunkte können unterschiedliche Authentifizierungsmechanismen haben

Deployment

• PowerOn Platform: gateway.poweron-center.net
• PowerOn Chat UI: althaus-chat.poweron-center.net
• PowerOn PreProcessing: Azure App Service im Kunden-Tenant (althaus-ag.ch)
  • URL: poweron-althaus-preprocess-prod-e3fegaatc7faency.switzerlandnorth-01.azurewebsites.net
• Tenant althaus-ag.ch: Enthält PowerOn PreProcessing und MSFT Services (Power BI, Azure DC, DNA Center) im Azure-Tenant von Althaus AG

Konfiguration

Gateway Config Keys

• PREPROCESS_ALTHAUS_CHAT_SECRET: API-Key für Pre-Processing Service
• APP_ENV_TYPE: Umgebung (dev, int, prod)
• Weitere Gateway-spezifische Konfigurationen

Pre-Processing Config

• Konfiguration wird als JSON im Gateway Code definiert
• Wird täglich um 01:00 UTC an Pre-Processing Service gesendet
• Definiert Tabellen, Spalten, Verarbeitungsschritte