WhiteLotusAI — Data Flow Architecture¶

Document type: Technical Architecture Specification
Product: WhiteLotus AI
Organization: Whitelotus Corporation
Product stage: Beta
Status: Initial source-inspected baseline
Audience: Engineering, QA, DevOps, Security, and Technical Stakeholders

1. Purpose¶

This document describes how requests, messages, and application data move through WhiteLotusAI's frontend, REST API gateway, application services, RabbitMQ workers, and supporting infrastructure.

It establishes a shared reference for understanding service boundaries, communication patterns, request/reply processing, retrieval-augmented generation (RAG), integration workflows, and data-handling requirements.

The specification distinguishes behavior observed in the source repository from behavior that requires runtime verification. It is not a substitute for endpoint specifications, database schemas, security policies, or integration-specific documentation.

2. Scope and System Boundaries¶

The following areas are covered:

• Frontend-to-API communication and gateway routing.
• RabbitMQ request/reply messaging and worker dispatch.
• User, Session, and RAG worker processing.
• Chat and Integrations service communication.
• Document ingestion, retrieval, and vector-store dependencies.
• OAuth token persistence and its unresolved HTTP service boundary.
• Error handling, sensitive-data considerations, and runtime validation.

2.1 Communication boundaries¶

3. High-Level Data Flow¶

WhiteLotusAI uses HTTP for client-facing and selected internal API communication, while RabbitMQ supports asynchronous message delivery and request/reply operations.

At a high level:

1. The user initiates an operation through the Next.js frontend.
2. The frontend sends an HTTP request to the REST API gateway.
3. The gateway processes the request through an explicit API route or an applicable proxy fallback.
4. Supported message-driven operations are published to RabbitMQ.
5. The relevant worker dispatches the request to a registered handler.
6. The result returns through the applicable messaging or HTTP response path.

The exact sequence depends on the endpoint and the service responsible for the operation.

3.1 System-level flow¶

%%{init: {
  "flowchart": {
    "htmlLabels": true,
    "nodeSpacing": 50,
    "rankSpacing": 65,
    "useMaxWidth": true
  },
  "themeVariables": {
    "fontSize": "18px",
    "lineColor": "#9CA3AF"
  }
}}%%

flowchart TD
    User(["End User"])
    Frontend["Next.js Frontend"]
    Gateway["REST API Gateway<br/>FastAPI :8000"]

    subgraph HTTPServices["HTTP Application Services"]
        direction TB
        Chat["Chat Service<br/>FastAPI :8001"]
        Integrations["Integrations Service<br/>FastAPI :8006"]
    end

    Broker["RabbitMQ Broker"]

    subgraph Workers["Message-Driven Workers"]
        direction TB
        UserWorker["User Worker"]
        SessionWorker["Session Worker"]
        RAGWorker["RAG Worker"]
    end

    Redis[("Redis")]
    Database[("PostgreSQL + pgvector")]

    User --> Frontend
    Frontend -->|"HTTP request"| Gateway

    Gateway -.->|"Configured proxy; verify reachability"| Chat
    Gateway -.->|"Configured proxy; verify reachability"| Integrations

    Gateway <-->|"Request/reply operations"| Broker
    Chat <-->|"Selected message operations"| Broker
    Integrations <-->|"Selected message operations"| Broker

    Broker <-->|"Registered handlers"| UserWorker
    Broker <-->|"Registered handlers"| SessionWorker
    Broker <-->|"Registered handlers"| RAGWorker

    Gateway -->|"Rate limiting / caching, as configured"| Redis
    RAGWorker -.->|"Persistence relationship to verify"| Database

    %% Pastel fills with category-specific colored outlines.

    classDef endpoint fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef client fill:#E0E7FF,stroke:#6366F1,stroke-width:1.5px,color:#312E81
    classDef service fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef messaging fill:#FFF2CC,stroke:#EA580C,stroke-width:1.5px,color:#7C2D12
    classDef worker fill:#E0F7FA,stroke:#0891B2,stroke-width:1.5px,color:#164E63
    classDef infrastructure fill:#F1F5F9,stroke:#64748B,stroke-width:1.5px,color:#334155
    classDef verification fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,stroke-dasharray:5 3,color:#7C3E00

    class User endpoint
    class Frontend client
    class Gateway,Chat,Integrations service
    class Broker messaging
    class UserWorker,SessionWorker,RAGWorker worker
    class Redis,Database infrastructure

    %% Dashed borders highlight unverified relationships.

    linkStyle 2,3 stroke:#D97706,stroke-width:1.5px,stroke-dasharray:5 3
    linkStyle 11 stroke:#D97706,stroke-width:1.5px,stroke-dasharray:5 3

    %% Transparent containers preserve the active theme background.

    style HTTPServices fill:transparent,stroke:#7C3AED,stroke-width:1.5px,color:inherit
    style Workers fill:transparent,stroke:#0891B2,stroke-width:1.5px,color:inherit

    %% Neutral connectors remain legible across themes.

    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

Solid arrows represent the logical communication relationships described by the inspected implementation. Dashed arrows indicate relationships whose complete runtime or persistence behavior still requires verification.

4. Frontend-to-API Request Lifecycle¶

4.1 Request initiation¶

The inspected frontend API client in frontend/src/lib/api.ts reads NEXT_PUBLIC_API_URL and falls back to http://localhost:8000 when the variable is not configured.

The general request lifecycle is:

1. Initiation: A user starts an operation through the frontend.
2. Request construction: The frontend API client builds the HTTP request using the configured API base URL.
3. Gateway reception: The REST API gateway receives the request.
4. Route selection: An explicit gateway route or the applicable proxy fallback handles the request.
5. Processing: The selected handler or upstream service performs the operation.
6. Response delivery: The result returns through the corresponding response path.
7. Client handling: The frontend processes the response or reports an error.

Authentication, authorization, validation, and response formatting are endpoint-specific and must be confirmed against the relevant implementation.

4.2 Gateway routing and proxy behavior¶

The inspected gateway dynamically includes eligible routers from package.app.api and includes the proxy router last as a catch-all.

This ordering is significant: a request that matches an explicit route may be handled directly by the gateway rather than forwarded to an upstream service.

When investigating an endpoint, verify:

• The actual registered HTTP method and path.
• Whether an explicit route matches the request.
• Whether the proxy fallback receives the request.
• The configured upstream service URL.
• The upstream's listening port and mounted route prefix.
• Authentication headers, response status mapping, and streaming behavior where applicable.

5. RabbitMQ Request/Reply Messaging¶

The shared messaging implementation provides a request/reply mechanism used by the REST API and selected message-driven operations.

5.1 Request/reply sequence¶

sequenceDiagram
    autonumber

    participant Caller as API or Service Caller
    participant Broker as RabbitMQ Broker
    participant Worker as Message Worker
    participant Handler as Registered Handler

    rect rgb(219, 234, 254)
        Note over Caller,Broker: 1. REQUEST DISPATCH
        Caller->>Broker: Declare temporary reply queue
        Caller->>Broker: Publish request with correlation ID
        Broker->>Worker: Deliver message to bound queue
    end

    rect rgb(243, 232, 255)
        Note over Worker,Handler: 2. HANDLER EXECUTION
        Worker->>Handler: process_data(data, corr_id)
        Handler-->>Worker: Return processing result
    end

    rect rgb(209, 250, 229)
        Note over Worker,Caller: 3. RESPONSE DELIVERY
        Worker->>Broker: Publish reply when applicable
        Broker-->>Caller: Deliver correlated reply
        Caller->>Caller: Match correlation ID
    end

    Note over Caller,Handler: Verify timeout, retry, acknowledgement, and failure behavior

5.2 Observed messaging behavior¶

The inspected files sharedlib/sharedlib/communication/call_service.py and sharedlib/sharedlib/communication/listen.py establish the following implementation characteristics:

• The caller creates a temporary reply queue configured for automatic deletion.
• Requests include a correlation identifier.
• The destination is identified through an exchange and routing key.
• Workers consume messages from their bound queues.
• BaseHandler.process_data dispatches requests using the message's method name.
• A response can be published to the request's reply destination.
• The caller uses the correlation identifier to associate a response with the original request.
• The listener uses robust RabbitMQ connections and includes connection retry logic.

These characteristics describe the inspected implementation, not a guarantee of successful delivery under every failure condition.

5.3 Worker handler dispatch¶

Worker entry points import their handler modules before starting the shared listener. This allows the handler registry to discover the relevant handler implementations.

The general processing sequence is:

1. A worker receives a RabbitMQ message.
2. The listener extracts the request data and correlation information.
3. The listener invokes BaseHandler.process_data.
4. The handler registry identifies the requested method.
5. The selected handler validates and processes the request according to its implementation.
6. The result is returned through the supported reply mechanism, when applicable.

The complete method registry, payload schemas, acknowledgement behavior, and error response contracts should be documented in the messaging reference after inspecting all registered handlers.

5.4 Delivery and reliability boundaries¶

The inspected request/reply mechanism does not, on its own, establish:

• Exactly-once execution.
• Successful processing of every published message.
• Guaranteed recovery of every in-flight request.
• A uniform timeout policy across all callers.
• Consistent error responses for all handler failures.
• Acknowledgement and retry semantics for every worker.

These properties must be verified from the relevant producer, consumer, broker configuration, and handler implementations.

6. Service-Specific Data Flows¶

6.1 User operations¶

The REST API contains authentication, profile, and administrative handlers that send operations to the User exchange.

The User worker entry point imports its handler modules and starts the RabbitMQ listener. The entry point also checks encryption-key configuration during startup.

%%{init: {
  "flowchart": {
    "htmlLabels": true,
    "nodeSpacing": 50,
    "rankSpacing": 65,
    "useMaxWidth": true
  },
  "themeVariables": {
    "fontSize": "18px",
    "lineColor": "#9CA3AF"
  }
}}%%

flowchart LR
    Client(["Frontend Client"])
    API["REST API Gateway"]
    Broker[("RabbitMQ Broker")]
    Worker["User Worker"]
    Handler["Registered User Handler"]

    Client -->|"HTTP request"| API
    API -->|"User operation"| Broker
    Broker --> Worker
    Worker --> Handler
    Handler --> Worker
    Worker --> Broker
    Broker -->|"Correlated reply"| API
    API -->|"HTTP response"| Client

    %% Pastel fills with category-specific colored outlines.

    classDef endpoint fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef service fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef messaging fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,color:#7C3E00
    classDef worker fill:#E0F7FA,stroke:#0891B2,stroke-width:1.5px,color:#164E63
    classDef handler fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B

    class Client endpoint
    class API service
    class Broker messaging
    class Worker worker
    class Handler handler

    %% Neutral connectors remain legible across themes.

    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

The exact behavior of each authentication, profile, or administrative operation depends on its API handler and registered worker handler.

6.2 Session operations¶

The REST API contains handlers that send operations to the Session exchange. The Session worker imports its handler modules and starts the RabbitMQ listener.

%%{init: {
  "flowchart": {
    "htmlLabels": true,
    "nodeSpacing": 50,
    "rankSpacing": 65,
    "useMaxWidth": true
  },
  "themeVariables": {
    "fontSize": "18px",
    "lineColor": "#9CA3AF"
  }
}}%%

flowchart LR
    Client(["Frontend Client"])
    API["REST API Gateway"]
    Broker[("RabbitMQ Broker")]
    Worker["Session Worker"]
    Handler["Session Handler"]

    Client -->|"HTTP request"| API
    API -->|"Session operation"| Broker
    Broker --> Worker
    Worker --> Handler
    Handler --> Worker
    Worker --> Broker
    Broker -->|"Correlated reply"| API
    API -->|"HTTP response"| Client

    %% Pastel fills with category-specific colored outlines.

    classDef endpoint fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef service fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef messaging fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,color:#7C3E00
    classDef worker fill:#E0F7FA,stroke:#0891B2,stroke-width:1.5px,color:#164E63
    classDef handler fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B

    class Client endpoint
    class API service
    class Broker messaging
    class Worker worker
    class Handler handler

    %% Neutral connectors remain legible across themes.

    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

This diagram represents the observed message-driven path. It does not prove that all session methods are implemented, that persistence works for every operation, or that every request succeeds.

6.3 RAG document and retrieval operations¶

The REST API contains handlers that send operations to the RAG exchange. The RAG worker initializes its embedding model and vector-store pool before starting its listener.

%%{init: {
  "flowchart": {
    "htmlLabels": true,
    "nodeSpacing": 50,
    "rankSpacing": 65,
    "useMaxWidth": true
  },
  "themeVariables": {
    "fontSize": "18px",
    "lineColor": "#9CA3AF"
  }
}}%%

flowchart TD
    Start(["RAG Worker Startup"])
    Model["Initialize Embedding Model"]
    Pool["Initialize Vector-Store Pool"]
    Listener["Start RabbitMQ Listener"]
    Message["Receive RAG Message"]
    Dispatch["Dispatch Registered Handler"]
    Process["Process Ingestion or Retrieval"]
    Result(["Return Operation Result"])
    Cleanup["Close Search Cache and Vector-Store Pool"]

    Start --> Model
    Model --> Pool
    Pool --> Listener
    Listener --> Message
    Message --> Dispatch
    Dispatch --> Process
    Process --> Result
    Listener -.->|"Shutdown"| Cleanup

    %% Pastel fills with category-specific colored outlines.

    classDef endpoint fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef initialization fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef messaging fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,color:#7C3E00
    classDef processing fill:#E0F7FA,stroke:#0891B2,stroke-width:1.5px,color:#164E63
    classDef response fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B
    classDef lifecycle fill:#F1F5F9,stroke:#64748B,stroke-width:1.5px,stroke-dasharray:5 3,color:#334155

    class Start endpoint
    class Result response
    class Model,Pool initialization
    class Listener,Message messaging
    class Dispatch,Process processing
    class Cleanup lifecycle

    %% Dashed lifecycle edge identifies the shutdown relationship.

    linkStyle 7 stroke:#64748B,stroke-width:1.5px,stroke-dasharray:5 3

    %% Neutral connectors remain legible across themes.

    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

The inspected handler registration includes modules for:

• Document ingestion.
• File ingestion.
• Search and retrieval.
• Document listing.
• Document deletion.
• Context operations.
• Publishing operations.

Registration establishes that the worker can discover these handler modules. It does not establish that every feature has passed functional testing.

The vector-store initialization indicates a database-related dependency. The actual storage schema, embedding representation, document lifecycle, and persistence behavior must be verified against the vector-store and database implementation.

6.4 Chat operations¶

The Chat service exposes FastAPI routes under /api/chat-svc and starts a RabbitMQ listener during application startup.

The inspected Chat implementation also uses message-driven operations for selected RAG and other service interactions.

Depending on the operation:

• An HTTP request may be handled by a Chat FastAPI endpoint.
• A message-driven operation may be published to the relevant RabbitMQ exchange.
• An agent or tool workflow may make additional internal HTTP or messaging calls.
• The result may return through an HTTP response or a streaming response path, depending on the endpoint.

The exact agent execution sequence, tool-selection behavior, authorization checks, and streaming contract should be documented only after tracing the relevant API endpoint and implementation.

6.5 Integrations operations¶

The Integrations service exposes HTTP routers for integration-related operations, webhooks, MCP, and OAuth-related functionality.

The inspected MCP implementation calls Chat HTTP endpoints to retrieve tool schemas and dispatch tool calls. The tool executor also contains message-driven operations, including RAG-related calls.

A typical logical interaction may therefore cross several service boundaries:

%%{init: {
  "flowchart": {
    "htmlLabels": true,
    "nodeSpacing": 50,
    "rankSpacing": 65,
    "useMaxWidth": true
  },
  "themeVariables": {
    "fontSize": "18px",
    "lineColor": "#9CA3AF"
  }
}}%%

flowchart TD
    Client(["Client or Caller"])
    Integration["Integrations Service"]
    Chat["Chat HTTP Endpoints"]
    Executor["Tool Executor"]
    Broker[("RabbitMQ Broker")]
    Worker["Relevant Worker"]

    Client -->|"Integration request"| Integration
    Integration -->|"Tool schema or dispatch request"| Chat
    Chat -->|"Selected tool operation"| Executor
    Executor -->|"Message-driven operation, when applicable"| Broker
    Broker -->|"Deliver message"| Worker
    Worker -->|"Processing result"| Broker
    Broker -->|"Message reply"| Executor
    Executor -->|"Tool result"| Chat
    Chat -->|"HTTP response"| Integration
    Integration -->|"Response to caller"| Client

    %% Pastel fills with category-specific colored outlines.

    classDef endpoint fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef service fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef processing fill:#E0F7FA,stroke:#0891B2,stroke-width:1.5px,color:#164E63
    classDef messaging fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,color:#7C3E00
    classDef worker fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B

    class Client endpoint
    class Integration,Chat service
    class Executor processing
    class Broker messaging
    class Worker worker

    %% Neutral connectors remain legible across themes.

    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

This is a logical illustration of selected communication relationships, not a claim that every integration follows the same sequence.

For each supported provider, the integration-specific documentation should identify the requested data, authentication method, internal destination, authorization boundary, and resulting response.

7. OAuth Token Persistence¶

Status: Open verification item

The inspected Gmail client sends an HTTP PUT request to:

/api/user-svc/internal/oauth/token

The destination is derived from the configured User service URL. The inspected User entry point starts a RabbitMQ listener, while a separate OAuth token handler module defines an APIRouter.

The available evidence does not establish that the HTTP endpoint is mounted and served by a running application.

7.1 Expected interaction boundary¶

sequenceDiagram
    autonumber

    participant Gmail as Gmail Client
    participant UserURL as Configured User Service URL
    participant Endpoint as OAuth Token HTTP Endpoint
    participant Storage as Token Persistence Layer

    rect rgb(219, 234, 254)
        Note over Gmail,Endpoint: 1. TOKEN REQUEST
        Gmail->>UserURL: Send HTTP PUT token request
        UserURL->>Endpoint: Route request if endpoint is served
    end

    rect rgb(243, 232, 255)
        Note over Endpoint,Storage: 2. ENDPOINT AND PERSISTENCE
        Note over Endpoint: Route mounting and reachability unverified
        Endpoint->>Storage: Persist token if implementation supports it
        Storage-->>Endpoint: Return persistence result
    end

    rect rgb(209, 250, 229)
        Note over Endpoint,Gmail: 3. HTTP RESPONSE
        Endpoint-->>Gmail: Return HTTP response if reachable
    end

    Note over Gmail,Storage: Verify endpoint registration, authentication, encryption, persistence, and failure handling

Dashed assumptions are intentionally excluded from this sequence: the diagram shows the intended boundary and conditional steps, not a confirmed successful execution.

7.2 Required verification¶

Before treating token persistence as operational, verify:

1. Which running application serves the endpoint.
2. Whether the route is mounted at the expected path and prefix.
3. Whether the caller and server agree on the HTTP method, payload schema, and response format.
4. How internal requests are authenticated and authorized.
5. How access and refresh tokens are encrypted, stored, refreshed, and retrieved.
6. How token persistence failures are reported and retried.
7. Whether sensitive tokens or authorization headers can appear in application logs.

8. Data Categories and Handling Requirements¶

The following classification identifies major categories suggested by the inspected components. It is a starting point for a formal data inventory, not a complete field-level inventory or a claim of regulatory compliance.

8.1 Data-handling principles¶

• Minimize collection: Process only the information required for the requested operation.
• Enforce authorization: Validate access to user data, sessions, documents, and connected accounts at the appropriate service boundary.
• Protect credentials: Keep tokens and secrets out of source control, documentation, and ordinary diagnostic output.
• Control persistence: Define how long documents, messages, sessions, cache entries, and integration credentials are retained.
• Handle deletion consistently: Verify that document or account deletion covers applicable indexes, caches, and persisted records.
• Review logs: Ensure request bodies, document content, and authentication material are not unnecessarily exposed.

These are engineering requirements and review criteria. Their presence in this document does not establish that they are already implemented everywhere.

9. Error Handling and Failure Scenarios¶

Failures can occur at HTTP, messaging, handler, storage, and external-provider boundaries. The following table separates observed implementation characteristics from the remaining validation work.

The listed scenarios are verification requirements, not assertions that the implementation currently handles each failure incorrectly.

9.1 Recommended error-path validation¶

For each important workflow, record:

• The failure point and triggering condition.
• The expected HTTP status or message response.
• Whether the operation is retried.
• Whether a retry can duplicate side effects.
• Whether temporary resources are cleaned up.
• Whether logs preserve diagnostic context without exposing sensitive data.
• Whether the frontend receives an actionable and appropriately sanitized error.

10. Runtime Validation Plan¶

Use the following checklist before promoting this document from a source-inspected baseline to a runtime-verified specification.

• Confirm the frontend uses the intended API base URL in the target environment.
• Exercise representative explicit gateway routes.
• Verify proxy route selection and upstream reachability.
• Confirm User, Session, and RAG requests reach their intended RabbitMQ handlers.
• Validate correlation IDs, reply matching, timeouts, and temporary queue cleanup.
• Test unknown methods, handler exceptions, and message acknowledgement behavior.
• Exercise Chat HTTP endpoints independently.
• Exercise Integrations HTTP endpoints and representative provider workflows.
• Verify all configured HTTP proxy destinations against actual running servers.
• Test OAuth token persistence through the configured runtime path.
• Validate RAG ingestion, retrieval, listing, and deletion against the active vector-store implementation.
• Confirm authorization and tenant or user isolation where applicable.
• Review logs and error responses for sensitive-data exposure.
• Record environment, date, test evidence, result, and known limitations.

10.1 Verification record template¶

Do not store credentials or raw sensitive payloads in the verification record.

Related documentation¶

Maintenance requirement: When a service boundary, transport, route prefix, message contract, persistence mechanism, or authentication flow changes, update the corresponding data-flow description and revalidate the affected workflow.