110 lines
8.6 KiB
Markdown
110 lines
8.6 KiB
Markdown
<!-- status: canonical -->
|
|
<!-- lastReviewed: 2026-04-07 -->
|
|
<!-- verifiedAgainst: gateway (codebase audit 2026-04-07, post Automation Unification) -->
|
|
|
|
# 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, CSRF, Token-Refresh-Middleware, JWT |
|
|
| `connectors/` | DB-Connector (PostgreSQL), Provider-Subpakete (Microsoft, Google, ClickUp, FTP), Ticket/Messaging/Geo-Konnektoren |
|
|
| `datamodels/` | Pydantic-Datenmodelle (u. a. Ai, Billing, Chat, Content, Files, Knowledge, Rbac, Subscription, Workflow) |
|
|
| `features/` | Feature-Module (autonome Domänen): workspace, graphicalEditor, 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/` | RBAC (`rbac.py`, `rbacCatalog.py`), Root-Access |
|
|
| `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, Feature-Discovery (`registry.py`: `loadFeatureMainModules`, `loadFeatureRouters`) |
|
|
| `workflows/` | Workflow-Engine mit Methoden, Aktionen, Execution Engine und konsolidiertem Scheduler |
|
|
|
|
## 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.:
|
|
|
|
- `user: User` (gesamtes User-Objekt), `mandateId`, `featureInstanceId`
|
|
- `workflow_id`, `workflow`, `feature_code`
|
|
- `requireNeutralization` (optional) — Neutralisierungsflag auf Chat-Ebene
|
|
|
|
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 (generischer Entry-Point), Routen, Middleware, EventManager, Scheduler-MainLoop |
|
|
| `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/*` | RBAC-Auswertung, RBAC-Katalog, Root-Access |
|
|
| `gateway/modules/auth/*` | CSRF, Token-Refresh-Middleware, JWT, OAuth |
|
|
| `gateway/modules/shared/*` | Querschnitt: Konfiguration, Audit-Logging, Events, Utilities |
|
|
| `gateway/modules/system/registry.py` | Feature-Discovery, Router-Laden, Katalog-Registrierung beim App-Start |
|
|
| `gateway/modules/workflows/workflowManager.py` | Zentrale Workflow-Steuerung (Workspace/Chat Workflows) |
|
|
| `gateway/modules/workflows/automation2/executionEngine.py` | Graph-Execution-Engine (Graphical Editor) |
|
|
| `gateway/modules/workflows/scheduler/mainScheduler.py` | Konsolidierter Workflow-Scheduler |
|
|
| `gateway/modules/interfaces/interfaceBootstrap.py` | System-Bootstrap (Templates, Billing, Stripe) |
|
|
|
|
## 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 (CSRF, Token-Refresh unter `modules/auth/`); RBAC-Auswertung und Katalog unter `modules/security/`.
|
|
- **Code-Konventionen (Projekt):** Interne Hilfsfunktionen mit Präfix **`_`**; Bezeichner in **camelCase** für Variablen und Funktionen.
|