PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/concepts/Kontext-20260329.md
ValueOn AG 70649218f1 unified failsafe neutralization architecture
2026-03-29 21:55:05 +02:00

14 KiB
Raw Blame History

PowerOn Applikations-Kontext (Stand 2026-03-29)

Multi-Tenant SaaS-Applikation mit Feature-Store-Modell, AI-Agent-Workspace und mandantenweiter Datenneutralisierung.

1. Technologie-Stack

Layer Technologie Pfad
Backend (Gateway) FastAPI (Python), PostgreSQL @poweron/gateway
Frontend React/TypeScript (Vite) @poweron/frontend_nyla
AI Core Multi-Provider (Anthropic, OpenAI, Mistral, Perplexity, Tavily, PrivateLLM) @poweron/gateway/modules/aicore
DB-Connector PostgreSQL mit pgvector (Embeddings) @poweron/gateway/modules/connectors/connectorDbPostgre.py

2. Gateway-Architektur (Backend)

Modulstruktur (gateway/modules/)

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 (30+ Dateien: 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 (30+ Dateien: Admin, Billing, DataFiles, DataSources, Security, Store, System...)
security/ Sicherheits-Middleware
serviceCenter/ Zentrale Service-Orchestrierung (siehe Abschnitt 3)
serviceHub/ Service-Registry und Dependency Injection
shared/ Gemeinsame Utilities (attributeUtils, etc.)
system/ System-Konfiguration
workflows/ Workflow-Engine mit Methoden und Aktionen (siehe Abschnitt 4)

Interfaces (DB-Schicht)

Die Interfaces kapseln alle Datenbankzugriffe:

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-Abstraction (Text, Embedding, Vision, Streaming)
interfaceFeatures.py Feature-Instanz-Lifecycle, Template-Rollen-Kopie
interfaceRbac.py RBAC-Regelauswertung

3. ServiceCenter (Kern-Orchestrierung)

Das ServiceCenter ist die zentrale Schicht, die alle Services verbindet. Es wird pro Request/Session erstellt und propagiert einen ServiceCenterContext (context.py).

Services (serviceCenter/services/)

Service Pfad Zweck
serviceAgent mainServiceAgent.py (3400+ Zeilen) AI-Agent mit 30+ Tools (readFile, writeFile, searchInFileContent, browseContainer, summarizeContent, readContentObjects, webSearch, sendMail, etc.)
serviceAi mainServiceAi.py (1700+ Zeilen) AI-Call-Gateway: Neutralisierung, Billing-Preflight, Provider-Selection, Streaming, Extraction, Generation
serviceKnowledge mainServiceKnowledge.py Knowledge Store: Indexierung, Semantic Search, RAG-Kontext-Aufbau (buildAgentContext)
serviceBilling Billing-Checks, Transaktionen
serviceChat Chat-Persistence
serviceExtraction Dokument-Extraktion (PDF, DOCX, XLSX...)
serviceGeneration Dokument-Generierung
serviceMessaging E-Mail, Notifications
serviceSubscription Subscription-Verwaltung
serviceWeb Web-Scraping

ServiceCenterContext (context.py)

Propagiert pro Request:

  • userId, mandateId, featureInstanceId
  • requireNeutralization: Optional[bool] — Chat-Level Neutralisierungsflag
  • Provider-Restrictions, Billing-Context

Agent-Tools (in mainServiceAgent.py)

Der Agent hat 30+ registrierte Tools. Tools liefern direkt Rohdaten — Neutralisierung erfolgt zentral im AI-Service (mainServiceAi.py) bevor Daten an ein AI-Modell gesendet werden.

Datenschutz-relevante DataSource-Tools:

  • _resolveDataSource() — liest neutralize-Flag der DataSource als 4. Tuple-Element
  • _downloadFromDataSource() — vererbt neutralize-Flag auf erstellte FileItems
  • _queryFeatureInstance() — setzt requireNeutralization=True auf Sub-Agent AI-Calls wenn FeatureDataSource neutralize=True

4. Workflow-Engine

WorkflowManager (workflows/workflowManager.py, 1400+ Zeilen)

Zentrale Workflow-Steuerung für Automation und dynamische Workflows.

Methoden (workflows/methods/)

Methode Aktionen
methodContext extractContent, neutralizeData, saveContent, transformContent
methodAi AI-Analyse, Summarization, Prompt-Processing
methodChatbot Chatbot-spezifische Aktionen
methodSharepoint SharePoint-Integration
methodOutlook Outlook/E-Mail-Integration
methodJira Jira-Integration
methodTrustee Trustee-Feature-Aktionen

5. Neutralisierungs-System (KRITISCH)

Architektur, Prozess und Code-Karte (ein Dokument): wiki/compliance/Neutralisierung.md

Prinzip: Zentrales Gate — ALLE Daten, die an ein AI-Modell gehen, werden AUSSCHLIESSLICH in mainServiceAi.py neutralisiert.

Architektur: Einzige zentrale Stelle

Neutralisierung findet nur an einer einzigen Stelle statt: _shouldNeutralize() und _neutralizeRequest() in mainServiceAi.py. Kein anderer Service, kein Tool und kein Workflow prüft oder neutralisiert eigenständig. Failsafe: Wenn Neutralisierung erforderlich ist (requireNeutralization=True) und fehlschlägt, wird der AI-Call blockiert (RuntimeError).

Neutralisierungs-Trigger (Prioritätsreihenfolge)

  1. Per-Request: AiCallRequest.requireNeutralization = True/False — expliziter Override
  2. Chat-Level: ServiceCenterContext.requireNeutralization = True — Session-Level-Flag
  3. Mandate-Config: NeutralizationConfig.enabled — mandantenweite Konfiguration

Was neutralisiert wird (in _neutralizeRequest)

  • request.prompt — Benutzer-Prompt
  • request.context — RAG-Kontext (externe Dokumente)
  • request.messages — Chat-Nachrichten (OpenAI-Style)

Schlüssel-Dateien

Datei Rolle
features/neutralization/serviceNeutralization/mainServiceNeutralization.py processText(text) → {neutralized_text, mappings}, resolveText(text) → Rehydrierung
routes/routeDataFiles.py PATCH /{fileId}/neutralize — Toggle löscht Index synchron, re-indexiert im Background
serviceAi/mainServiceAi.py Zentrales Gate: _shouldNeutralize() prüft Request → Context → Config; _neutralizeRequest() neutralisiert prompt, context, messages. Hard-Mode bei requireNeutralization=True
serviceKnowledge/mainServiceKnowledge.py indexFile() neutralisiert bei FileItem.neutralize=True (Data-at-rest-Schutz). RAG-Chunks werden neutral gespeichert
serviceAgent/mainServiceAgent.py _resolveDataSource() liest neutralize-Flag der DataSource. _downloadFromDataSource() vererbt Flag auf erstellte FileItems. _queryFeatureInstance() setzt requireNeutralization=True wenn FeatureDataSource neutralize-Flag gesetzt
workflows/methods/methodContext/actions/neutralizeData.py Explizite Neutralisierungs-Aktion in Workflows (prüft nur Config, nicht Context-Flag)

Failsafe-Kette

  1. Toggle ON: Index + Chunks werden synchron gelöscht → kein Leak bei Background-Re-Index-Fehler
  2. Indexierung: indexFile() neutralisiert Chunks bei FileItem.neutralize=True → Data-at-rest ist sicher
  3. DataSource-Download: neutralize-Flag wird auf erstellte FileItems vererbt
  4. FeatureDataSource: _queryFeatureInstance() setzt requireNeutralization=True auf Sub-Agent AI-Calls
  5. AI-Calls (Zentrales Gate): Hard-Mode (requireNeutralization=True) → Prompt-/Context-Fehler = RuntimeError (AI-Call blockiert), Message-Fehler = Message entfernt
  6. _rehydrateResponse() bleibt als Utility-Methode verfügbar, wird aber nicht mehr automatisch aufgerufen

NeutralizationPanel (Frontend)

frontend_nyla/src/pages/views/workspace/NeutralizationPanel.tsx — zeigt alle Files mit neutralize-Flag, deren Status und Platzhalter-Mappings. API: GET /api/workspace/{instanceId}/files → {files: [...]}.

6. Frontend-Architektur

Struktur (frontend_nyla/src/)

Ordner Inhalt
pages/ Seiten: admin/, basedata/, billing/, settings/, views/ (workspace, commcoach, chatbot, trustee, automation)
components/ Wiederverwendbar: FormGenerator, FolderTree, Navigation, UnifiedDataBar, Automation2FlowEditor, OnboardingAssistant
hooks/ useApi, useFiles, useNavigation, useConfirm, usePrompt, useResizablePanels, etc.
contexts/ FileContext, PekContext, ToastContext, WorkflowSelectionContext
api/ API-Client (api.ts) und Feature-spezifische API-Module
core/ PageManager
layouts/ Layout-Komponenten
locales/ i18n
types/ TypeScript-Typen
utils/ Utility-Funktionen

Wichtige UI-Komponenten

Komponente Zweck
UnifiedDataBar (UDB) Multi-Tab-Panel: Chats, Files, Sources — wird in Workspace und CommCoach genutzt
FormGenerator Dynamische Formulare/Tabellen aus Backend-Attribut-Definitionen
FolderTree Rekursiver Ordnerbaum mit Drag&Drop, Multi-Selection, Inline-Editing
MandateNavigation Feature-Baum-Navigation mit Mandanten-Kontext
Automation2FlowEditor n8n-style Flow-Builder für Automation2
WorkspacePage AI-Workspace mit Chat, UDB, Agent-Streaming

UI-Regeln

  • Keine Browser-Dialoge (alert/confirm/prompt) — stattdessen useConfirm() und usePrompt() Hooks
  • Alle internen Funktionen mit _ Prefix
  • camelCase für Variablen und Funktionen

7. RBAC-System (Zwei getrennte Rollensysteme!)

Mandantenrollen

  • Labels: admin, user, viewer
  • Scope: mandateId, kein featureCode/featureInstanceId
  • Junction: UserMandateRole

Feature-Instanz-Rollen

  • Labels: workspace-admin, workspace-user, workspace-viewer, etc.
  • Scope: mandateId + featureCode + featureInstanceId
  • Junction: FeatureAccessRole

Strikte Regel: NIE eine Mandantenrolle einer FeatureAccessRole zuweisen oder umgekehrt.

8. Billing & Subscriptions

  • Modell: PREPAY_MANDATE (kein PREPAY_USER)
  • Billing-Check: Vor jedem AI-Call via _preflightBillingCheck und _checkBillingBeforeAiCall
  • Datenvolumen: assertCapacity("dataVolumeMB") prüft RAG-Index-Grösse
  • Trial: 5 CHF, Standard: 10 CHF/Monat

9. AI-Core (Provider-Abstraction)

Model-Registry (aicoreModelRegistry.py)

Registriert alle Provider-Plugins und deren Modelle dynamisch.

Model-Selector (aicoreModelSelector.py)

Wählt optimal basierend auf: Operation Type, Prompt-Grösse, Provider-Restrictions, Score-Ranking.

Provider-Plugins

  • aicorePluginAnthropic.py — Claude Sonnet/Haiku/Opus
  • aicorePluginOpenai.py — GPT-4o, Embeddings (text-embedding-3-small/large), DALL-E
  • aicorePluginMistral.py — Mistral Large/Small, Mistral Embed
  • aicorePluginPerplexity.py — Sonar/Sonar-Pro
  • aicorePluginTavily.py — Web-Search
  • aicorePluginPrivateLlm.py — Private LLM
  • aicorePluginInternal.py — Interne Extraktoren/Generatoren/Renderer

Operation Types

dataExtract, dataAnalyse, agent, embedding, imageGeneration, vision, webSearch

10. Knowledge Store (RAG)

Datenmodelle (datamodelKnowledge.py)

  • FileContentIndex — Pro File: Struktur, Metadaten, isNeutralized, neutralizationStatus, totalObjects, totalSize
  • ContentChunk — Semantische Chunks mit Embedding-Vektor, fileId, data, metadata
  • RoundMemory — Kontext aus früheren Runden (file_ref, etc.)

Indexierung (serviceKnowledge.indexFile())

  1. Extraktion via serviceExtraction
  2. Optional: Neutralisierung via serviceNeutralization.processText()
  3. Chunking + Embedding
  4. Speicherung in FileContentIndex + ContentChunk

RAG-Kontext (serviceKnowledge.buildAgentContext())

  1. Semantic Search via pgvector
  2. Context-Budget: Priorisierte Layer (File-Refs, Instance Docs, Mandate Docs)
  3. Neutralisierung erfolgt zentral im AI-Service wenn der RAG-Kontext als request.context an ein AI-Modell geht

11. Feature-Module

Feature Beschreibung
workspace AI-Agent-Workspace mit Chat, Tools, RAG, Streaming
automation Workflow-Automatisierung (v1)
automation2 Flow-Editor n8n-Style (v2)
chatbot Chatbot-Feature
commcoach Kommunikations-Coach mit Voice, Dossier, UDB
neutralization Datenneutralisierungs-Service und Config
trustee Trustee/Treuhand-Feature (Buchhaltung, Positionen)
realEstate Immobilien-Feature
teamsbot MS Teams Bot

12. Coding-Konventionen

  • Alle internen Funktionen beginnen mit _ Prefix
  • camelCase für Variablen und Funktionsnamen (kein snake_case)
  • Keine Browser-Dialoge — useConfirm() / usePrompt() Hooks
  • Fehler propagieren — keine stillen Fallbacks bei kritischen Pfaden
  • Pydantic-Models als einzige Quelle für UI-Feld-Definitionen
  • PowerOnModel als Basis mit sysCreatedAt, sysCreatedBy, sysModifiedAt, sysModifiedBy