wiki/appdoc/doc_gateway_architecture_overview.md

Gateway Architektur – Überblick (aktuell in gateway/)

Diese Seite fasst die aktuelle Struktur des Gateways zusammen und stellt sie mit Mermaid‑Diagrammen dar. Die Ebenen entsprechen deinem Schema: Connectors → Interfaces → Services → Workflows, ergänzt um Routes, Security/Middlewares, Shared und Datamodels.

---

Layered Overview

flowchart LR
  %% Entry
  Client([Client / Frontend / Tests]) -->|HTTP| App[FastAPI app.py]

  %% Routes
  subgraph Routes[gateway/modules/routes]
    RA[routeAdmin]
    RAttr[routeAttributes]
    RConn[routeDataConnections]
    RFiles[routeDataFiles]
    RMand[routeDataMandates]
    RNeut[routeDataNeutralization]
    RProm[routeDataPrompts]
    RUsers[routeDataUsers]
    RWF[routeWorkflows]
    RChat[routeChatPlayground]
    RSecL[routeSecurityLocal]
    RSecM[routeSecurityMsft]
    RSecG[routeSecurityGoogle]
    RVoiceG[routeVoiceGoogle]
    RVoiceS[routeVoiceStreaming]
    RSecA[routeSecurityAdmin]
  end

  App --> RA & RAttr & RConn & RFiles & RMand & RNeut & RProm & RUsers & RWF & RChat & RSecL & RSecM & RSecG & RVoiceG & RVoiceS & RSecA

  %% Middlewares / Security / Shared
  subgraph Security[gateway/modules/security]
    CSRF[csrf]
    TRM[tokenRefreshMiddleware]
    JWT[jwtService]
    AUTH[auth]
    TOK[tokenManager]
  end
  App -. middleware .-> CSRF & TRM
  App -. uses .-> JWT & AUTH & TOK

  subgraph Shared[gateway/modules/shared]
    CFG[configuration]
    LOG[auditLogger]
    EVT[eventManagement]
    TZ[timezoneUtils]
    ATTR[attributeUtils]
  end
  App -. uses .-> CFG & LOG & EVT

  %% Features (init triggers etc.)
  subgraph Features[gateway/modules/features]
    FInit[init]
    FChat[chatPlayground]
    FNeutral[neutralizePlayground]
    FSync[syncDelta]
  end
  App --> FInit
  RChat --> FChat

  %% Service Center
  subgraph ServiceCenter[gateway/modules/services/__init__.py]
    SC[Services registry/factory<br/>(PublicService wrappers)]
  end

  %% Services
  subgraph Services[gateway/modules/services]
    SAi[serviceAi]
    SDocE[serviceDocumentExtraction]
    SDocG[serviceDocumentGeneration]
    SNeut[serviceNeutralization]
    SShare[serviceSharepoint]
    STicket[serviceTicket]
    SWeb[serviceWeb]
    SWF[serviceWorkflow]
  end

  %% Interfaces
  subgraph Interfaces[gateway/modules/interfaces]
    IApp[interfaceAppObjects]
    IComp[interfaceComponentObjects]
    IChat[interfaceChatObjects]
    IWeb[interfaceWebObjects]
    IAi[interfaceAiObjects]
  end

  %% Connectors
  subgraph Connectors[gateway/modules/connectors]
    KOpenAI[connectorAiOpenai]
    KAnth[connectorAiAnthropic]
    KTavily[connectorWebTavily]
    KJira[connectorTicketsJira]
    KClickup[connectorTicketsClickup]
    KGSpeech[connectorGoogleSpeech]
    KPg[connectorDbPostgre]
    KJson[connectorDbJson]
  end

  %% Datamodels
  subgraph Datamodels[gateway/modules/datamodels]
    DMUAM[datamodelUam]
    DMChat[datamodelChat]
    DMAi[datamodelAi]
    DMWeb[datamodelWeb]
    DMFiles[datamodelFiles]
    DMVoice[datamodelVoice]
    DMNeut[datamodelNeutralizer]
    DMWork[datamodelWorkflow]
    DMInit[__init__ (namespace)]
  end

  %% Workflows
  subgraph Workflows[gateway/modules/workflows]
    WM[workflowManager]
    WMethods[methods/*]
    WProc[processing/*]
  end

  %% Flows
  Routes -->|calls| SC
  SC --> SAi & SDocE & SDocG & SNeut & SShare & STicket & SWeb & SWF
  SAi & SDocE & SDocG & SNeut & SShare & STicket & SWeb & SWF --> IApp & IComp & IChat & IWeb & IAi
  IApp & IComp & IChat & IWeb & IAi --> KOpenAI & KAnth & KTavily & KJira & KClickup & KGSpeech & KPg & KJson

  WMethods & WM --> SC
  Services --> DMUAM & DMChat & DMAi & DMWeb & DMFiles & DMVoice & DMNeut & DMWork

---

Request / Action Sequence

sequenceDiagram
  participant C as Client
  participant A as app.py (FastAPI)
  participant R as Route (z.B. routeWorkflows)
  participant SC as Services registry
  participant S as Service (z.B. WorkflowService)
  participant I as Interface (z.B. interfaceWebObjects)
  participant K as Connector (z.B. connectorWebTavily)
  participant EXT as External API

  C->>A: HTTP Request
  A->>R: Dispatch via APIRouter
  R->>SC: get Services(user, workflow)
  SC->>S: resolve service (PublicService proxy)
  S->>I: normalized call (search/summarize/...)
  I->>K: vendor-spezifischer Request
  K->>EXT: API/SDK Call (Auth, Retries)
  EXT-->>K: Response
  K-->>I: Mapping → DTO
  I-->>S: Normalized result
  S-->>R: Business output
  R-->>A: Response model
  A-->>C: JSON

---

Hinweise

• Die Services werden zentral in modules/services/__init__.py registriert und als PublicService nur mit öffentlichen Methoden exponiert.
• Interfaces kapseln Vendor‑Details; Services hängen von Interfaces, nicht direkt von Connectors.
• modules/features/init.py startet initiale Trigger beim App‑Start.
• Security/Middlewares: CSRF + Token‑Refresh sind global aktiviert; zusätzliche AuthN/AuthZ Utilities in modules/security/*.