wiki/b-reference/gateway/architecture.md

Gateway -- Architektur

Überblick

Das Gateway ist das Python-Backend der PowerOn-Plattform (FastAPI, PostgreSQL). Es kapselt Mandanten- und Feature-Logik hinter einer REST-API und folgt einer klaren Schichtenfolge: Connectors sprechen externe Systeme und Datenbanken an, Interfaces normalisieren Zugriffe und DTOs, Services bündeln fachliche Operationen darauf, und das ServiceCenter löst diese Services pro Request mit einheitlichem Kontext auf. Routen in modules/routes/ sind der HTTP-Einstieg; Security-Middleware und gemeinsame Utilities liegen in modules/security/ bzw. modules/shared/. Feature-spezifische Domänen leben in modules/features/ als weitgehend autonome Module.

Modulstruktur

Unter gateway/modules/ (Kontext-Audit):

Modul	Zweck
aicore/	Model-Registry, Model-Selector, Provider-Plugins (Anthropic, OpenAI, Mistral, Perplexity, Tavily, PrivateLLM)
auth/	Authentifizierung
connectors/	DB-Connector (PostgreSQL), externe Konnektoren
datamodels/	Pydantic-Datenmodelle (u. a. Ai, Billing, Chat, Content, Files, Knowledge, Rbac, Subscription, Workflow)
features/	Feature-Module (autonome Domänen): workspace, automation, automation2, chatbot, commcoach, neutralization, realEstate, trustee, teamsbot
interfaces/	DB-Interfaces (App, Billing, Chat, Knowledge, Management, Subscription), AI-Objects, RBAC, Features, Messaging
migration/	Daten-Migrationen
routes/	REST-API-Routen (u. a. Admin, Billing, DataFiles, DataSources, Security, Store, System)
security/	Sicherheits-Middleware
serviceCenter/	Zentrale Service-Orchestrierung (Registry, Resolver, Kontext, Haupt-Services)
serviceHub/	Service-Registry und Dependency Injection (u. a. PublicService-Wrapper)
shared/	Gemeinsame Utilities (attributeUtils, Konfiguration, Logging, …)
system/	System-Konfiguration
workflows/	Workflow-Engine mit Methoden und Aktionen

ServiceCenter (Kern-Orchestrierung)

Das ServiceCenter ist die zentrale Schicht, die Kern- und importierbare Services verbindet. Pro Request/Session wird ein ServiceCenterContext (serviceCenter/context.py) mitgeführt und propagiert u. a.:

• userId, mandateId, featureInstanceId
• requireNeutralization (optional) — Neutralisierungsflag auf Chat-Ebene
• Provider-Restrictions, Billing-Context

Die öffentliche API umfasst u. a. getService(key, context) zur Auflösung einer Service-Instanz; registrierte Services sind in registry.py als CORE_SERVICES und IMPORTABLE_SERVICES hinterlegt, mit feature-spezifischer Auflösung und optionaler Vorabladung (preWarm).

Services (serviceCenter/services/)

Service	Hauptmodul (Auszug)	Zweck
serviceAgent	mainServiceAgent.py	AI-Agent mit vielen Tools (u. a. Dateien, Suche, Container, Web, Mail)
serviceAi	mainServiceAi.py	AI-Call-Gateway: Neutralisierung, Billing-Preflight, Provider-Auswahl, Streaming, Extraktion, Generierung
serviceKnowledge	mainServiceKnowledge.py	Knowledge Store: Indexierung, semantische Suche, RAG-Kontext (buildAgentContext)
serviceBilling	mainServiceBilling.py	Billing-Checks, Transaktionen
serviceChat	mainServiceChat.py	Chat-Persistenz
serviceExtraction	mainServiceExtraction.py	Dokument-Extraktion (PDF, DOCX, XLSX, …)
serviceGeneration	mainServiceGeneration.py	Dokument-Generierung
serviceMessaging	mainServiceMessaging.py	E-Mail, Notifications
serviceSubscription	mainServiceSubscription.py	Subscription-Verwaltung
serviceWeb	mainServiceWeb.py	Web-Scraping

Hinweis (Agent): Agent-Tools liefern Rohdaten; Neutralisierung vor dem Versand an ein Sprachmodell erfolgt zentral im serviceAi (mainServiceAi.py), nicht in den Tools selbst.

Einordnung (Framework)

Daten- und Steuerfluss: Client oder Workflow → Service Center → Service → Interface → Connector → externes System. Das Service Center bündelt dabei Erkennbarkeit (Registry), Konfiguration und querschnittliche Aspekte wie Logging, RBAC-Objekt-Registrierung (registerServiceObjects) und konsistente Service-Lebenszyklen; serviceHub ergänzt dies mit PublicService, sodass nur bewusst exponierte Methoden nach außen sichtbar sind.

Interfaces (DB-Schicht)

Die genannten Module kapseln die Datenbankzugriffe bzw. die zugehörigen Fachverträge (Audit-Liste):

Interface	Verantwortlich für
interfaceDbApp.py	User, Mandate, FeatureAccess, UserConnections, Preferences
interfaceDbBilling.py	BillingAccount, BillingTransaction, Subscriptions
interfaceDbChat.py	ChatWorkflow, ChatMessage, ChatDocument
interfaceDbKnowledge.py	FileContentIndex, ContentChunk, RoundMemory (RAG/Knowledge Store)
interfaceDbManagement.py	FileItem, Folder, Prompt, DataSource (mandantenweite Stammdaten)
interfaceDbSubscription.py	Subscription-Verwaltung
interfaceAiObjects.py	AI-Call-Abstraktion (Text, Embedding, Vision, Streaming)
interfaceFeatures.py	Feature-Instanz-Lifecycle, Template-Rollen-Kopie
interfaceRbac.py	RBAC-Regelauswertung

Weitere Interface-Dateien im Ordner (z. B. Voice, Tickets, Messaging, Bootstrap) erfüllen dieselbe Normalisierungsrolle gegenüber Connectors bzw. externen APIs; die Tabelle oben entspricht der expliziten DB-/Kern-Zuordnung aus dem Kontext-Audit.

Schlüssel-Dateien

Datei / Pfad	Rolle
gateway/app.py	FastAPI-Anwendung, Einbindung von Routen und Middleware
gateway/modules/serviceCenter/__init__.py	Service Center: getService, preWarm, RBAC-Registrierung für Service-Objekte
gateway/modules/serviceCenter/context.py	ServiceCenterContext pro Request
gateway/modules/serviceCenter/registry.py	Service-Registry (CORE / IMPORTABLE)
gateway/modules/serviceCenter/resolver.py	Auflösung von Service-Instanzen inkl. Cache
gateway/modules/serviceHub/__init__.py	Hub / DI, PublicService-Wrapper für kontrollierte Oberflächen
gateway/modules/routes/*.py	HTTP-Endpunkte, Aufruf in Richtung Service Center / Features
gateway/modules/interfaces/*.py	Stabile Verträge und DB-Zugriffe (keine direkte Vendor-Logik in Services)
gateway/modules/connectors/*.py	Vendor-spezifische Adapter (Auth, Transport, Mapping)
gateway/modules/security/*	CSRF, Token-Refresh-Middleware, JWT/Auth-Utilities
gateway/modules/shared/*	Querschnitt: Konfiguration, Audit-Logging, Events, Utilities
gateway/modules/features/init.py	Initiale Trigger beim App-Start
gateway/modules/workflows/workflowManager.py	Zentrale Workflow-Steuerung

Regeln / Invarianten

• Schichten: Connectors sind anbieterspezifisch und ersetzbar; Services hängen von Interfaces ab, nicht direkt von Connectors. Geschäftslogik und Guardrails liegen in den Services.
• Datenbank: Persistenz und die genannten Domänen-Reads/Writes laufen über die Interface-Schicht, nicht ad hoc aus Routen heraus.
• Service Center: Aufrufe laufen über die zentrale Auflösung (getService + Kontext); Workflows und Routen konsumieren dieselbe Landschaft.
• Sicherheit & Governance: RBAC und Geheimnisse werden zentral geführt; Service-Aufrufe und Workflow-Schritte sollen nachvollziehbar sein (Audit); Kontingente und Limits pro Mandant/Service sind vorgesehen.
• HTTP-Einstieg: Globale Middleware u. a. CSRF und Token-Refresh; zusätzliche AuthN/AuthZ-Utilities unter modules/security/.
• Code-Konventionen (Projekt): Interne Hilfsfunktionen mit Präfix _; Bezeichner in camelCase für Variablen und Funktionen.