WhiteLotusAI — Architecture Overview¶

Document type: Technical Architecture
Product stage: Beta
Documentation status: Initial implementation baseline
Audience: Engineering, QA, DevOps, Security, and Technical Stakeholders

1. Purpose and Scope¶

WhiteLotusAI uses a multi-service architecture designed to separate the user interface, API access, conversational processing, integrations, asynchronous workers, and supporting infrastructure.

This document establishes a shared understanding of:

• The major architectural components and their responsibilities.
• The HTTP and RabbitMQ communication patterns observed in the repository.
• The relationship between the API gateway and backend services.
• The supporting database, caching, and messaging infrastructure.
• Known interface discrepancies, implementation questions, and verification requirements.

The architecture is documented from the perspective of the inspected implementation. Intended behavior, configured connectivity, and verified runtime behavior are treated as separate concerns.

Architecture documentation principles¶

2. Architecture at a Glance¶

The observed architecture consists of a Next.js frontend, a FastAPI REST API gateway, dedicated Chat and Integrations services, RabbitMQ-backed workers, and supporting infrastructure.

Two primary communication patterns are present:

• HTTP: Used by the frontend, the REST API gateway, and selected backend interfaces and internal requests.
• RabbitMQ messaging: Used for asynchronous message consumption and request/reply operations involving the gateway and backend workers.

The architecture is therefore hybrid. The presence of an HTTP proxy route does not establish that its upstream service exposes the corresponding HTTP interface.

Core architectural layers¶

3. High-Level Architecture Diagram¶

The following diagram represents the major components and their observed relationships. It deliberately separates confirmed implementation patterns from interfaces whose runtime availability remains unresolved.

flowchart TB
    Browser["User's Browser"]
    Frontend["Next.js Frontend"]
    Gateway["REST API Gateway<br/>FastAPI :8000"]

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

    subgraph Messaging["RabbitMQ Message Processing"]
        Broker["RabbitMQ Broker"]

        subgraph Workers["Message-Consuming Workers"]
            UserWorker["User Worker"]
            SessionWorker["Session Worker"]
            RAGWorker["RAG Worker"]
        end
    end

    subgraph Infrastructure["Supporting Infrastructure"]
        Redis[("Redis<br/>Rate-Limiting Support")]
        Database[("PostgreSQL + pgvector")]
    end

    Browser --> Frontend
    Frontend -->|"HTTP API requests"| Gateway

    Gateway -.->|"Configured HTTP proxy;<br/>runtime reachability to verify"| Chat
    Gateway -.->|"Configured HTTP proxy;<br/>runtime reachability to verify"| Integrations

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

    Broker <-->|"User operations"| UserWorker
    Broker <-->|"Session operations"| SessionWorker
    Broker <-->|"Retrieval and document operations"| RAGWorker

    Gateway -->|"Rate limiting"| Redis
    RAGWorker -.->|"Vector-store dependency;<br/>exact persistence path to verify"| Database

    %% Pastel fills and category-specific colored outlines.
    classDef frontend fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef application fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef messaging fill:#FFF2CC,stroke:#D97706,stroke-width:2px,color:#7C3E00
    classDef worker fill:#F1F5F9,stroke:#64748B,stroke-width:1.5px,color:#334155
    classDef infrastructure fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B

    class Browser,Frontend frontend
    class Gateway,Chat,Integrations application
    class Broker messaging
    class UserWorker,SessionWorker,RAGWorker worker
    class Redis,Database infrastructure

    %% Transparent containers preserve the documentation theme.
    style HTTPServices fill:transparent,stroke:#7C3AED,stroke-width:1.5px,color:inherit
    style Messaging fill:transparent,stroke:#D97706,stroke-width:1.5px,color:inherit
    style Workers fill:transparent,stroke:#64748B,stroke-width:1px,color:inherit
    style Infrastructure fill:transparent,stroke:#059669,stroke-width:1.5px,color:inherit

    %% Neutral connectors remain visible in both themes.
    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

Diagram interpretation

• The frontend sends API requests to the REST API gateway.
• The gateway contains explicit API routers and a proxy fallback.
• RabbitMQ provides message transport and request/reply functionality.
• The User, Session, and RAG workers are observed as message consumers.
• The gateway's Redis-backed rate limiter is an observed implementation detail.
• The precise database access patterns and end-to-end connectivity require further verification.

4. Major Components and Responsibilities¶

The following table summarizes the technologies and responsibilities observed in the inspected repository.

5. Communication Model¶

5.1 HTTP communication¶

The frontend, REST API gateway, and inspected Chat and Integrations entry points initialize FastAPI or Next.js application components as appropriate.

The frontend reads NEXT_PUBLIC_API_URL when constructing API requests. The fallback configured in frontend/src/lib/api.ts is:

http://localhost:8000

The REST API gateway contains explicit routers and a proxy fallback. Its proxy configuration maps paths associated with Chat, Session, RAG, User, and Integrations to configured upstream URLs.

Important distinction: Proxy configuration does not prove that the upstream service runs an HTTP server or implements the expected endpoint.

For every HTTP interface, verify:

1. The receiving application starts successfully.
2. The endpoint is registered and mounted.
3. The configured upstream URL and port are correct.
4. Authentication and authorization are enforced.
5. Request and response schemas match the caller's expectations.
6. Connection failures and non-success responses are handled correctly.

5.2 RabbitMQ messaging¶

The shared messaging implementation uses RabbitMQ for message dispatch and request/reply operations.

The observed request/reply sequence is:

sequenceDiagram
    autonumber

    participant C as Requesting Component
    participant B as RabbitMQ Broker
    participant W as Worker
    participant R as Temporary Reply Queue

    C->>B: Publish request with correlation ID
    Note over C,R: Requesting component waits for the matching response

    B->>W: Route request to worker queue
    W->>W: Dispatch through registered handler
    W->>B: Publish response with correlation ID
    B->>R: Route response to reply queue
    R-->>C: Deliver matching response

    Note over C,W: Timeout and failure behavior must be verified

    %% Theme-adaptive fills and text; colored participant borders
    %% identify the responsibilities of each component.

    participant C as Requesting Component
    participant B as RabbitMQ Broker
    participant W as Worker
    participant R as Temporary Reply Queue

    rect rgba(37, 99, 235, 0.08)
        Note over C,B: Request dispatch
        C->>B: Publish request
        B->>W: Deliver request
    end

    rect rgba(5, 150, 105, 0.08)
        Note over W,R: Processing and response
        W->>W: Execute registered handler
        W->>B: Publish correlated response
        B->>R: Route response
        R-->>C: Return matching response
    end

The inspected messaging implementation follows this general sequence:

1. Declares a temporary reply queue.
2. Publishes a message containing a correlation identifier.
3. Routes the message to the destination exchange and corresponding queue.
4. Waits for a response associated with the correlation identifier.
5. Dispatches incoming worker messages through BaseHandler.process_data.
6. Publishes a reply when the request includes a reply destination.

Worker entry points import handler modules before starting their listeners so that handler registration can occur.

The messaging implementation also uses robust RabbitMQ connections and includes connection retry behavior.

The exact guarantees for timeouts, retry limits, message acknowledgements, duplicate delivery, idempotency, and failure recovery must be established from the complete implementation and its tests.

5.3 Hybrid communication¶

WhiteLotusAI is neither exclusively HTTP-based nor exclusively message-based. Components can expose HTTP interfaces while also participating in message-driven processing.

Each documented interface should specify the following:

6. Known Architecture Verification Items¶

The following items remain open until the relevant code paths, configuration, and runtime behavior have been verified.

6.1 User HTTP interface¶

The inspected User service entry point starts a RabbitMQ listener rather than a FastAPI server. An OAuth token handler module defines an APIRouter, but the inspected entry point does not demonstrate that the router is mounted in an HTTP application.

The Integrations Gmail client sends an HTTP request to an internal OAuth token endpoint associated with the User service.

Required verification

• Identify whether another application mounts and serves the OAuth token routes.
• Trace the Gmail client's token request to its actual receiving process.
• Confirm the internal URL, port, authentication, and response contract.
• If no HTTP server exposes the endpoint, record the interface mismatch as an implementation defect and determine the intended communication pattern.

6.2 Session and RAG HTTP proxy paths¶

The inspected Session and RAG entry points operate as message consumers. The gateway proxy nevertheless contains HTTP upstream mappings associated with these services.

Required verification

• Trace the gateway routes that use these upstream mappings.
• Inspect container startup commands and exposed ports.
• Search for additional applications or processes that serve the expected HTTP endpoints.
• Test each relevant route against the running deployment.
• Reconcile unused or incompatible proxy mappings only after establishing the intended architecture.

6.3 Database implementation¶

Docker Compose configures PostgreSQL with pgvector support, and the RAG worker initializes vector-store components.

These observations do not, by themselves, establish the complete persistence architecture.

Required verification

• Inspect ORM models and database connection code.
• Review database migrations and initialization logic.
• Identify the actual vector-store implementation and its persistence mechanism.
• Confirm document and chunk schemas, relationships, and indexes.
• Verify embedding dimensions and their compatibility with the configured vector representation.
• Test document ingestion, retrieval, persistence, and failure handling.

Until this work is complete, database schema and persistence guarantees should be documented only to the level supported by implementation evidence.

6.4 Security and deployment¶

Security and deployment require dedicated review beyond this architecture overview.

Areas requiring verification include:

• Historical credential exposure and secret-management practices.
• CORS allowlists and browser-origin restrictions.
• HTTPS termination and secure production transport.
• Authentication and authorization at service boundaries.
• Protection of internal endpoints and service-to-service credentials.
• RabbitMQ access control and network exposure.
• Database access restrictions and migration practices.
• Error handling that avoids leaking tokens, secrets, or sensitive internal details.

7. Architecture Verification Checklist¶

Use this checklist when validating the architecture against source code and a running deployment.

• Confirm the frontend API base URL in each environment.
• Verify gateway startup, route registration, authentication, and CORS behavior.
• Confirm that Chat and Integrations HTTP endpoints are reachable through their intended paths.
• Resolve the User OAuth token endpoint discrepancy.
• Resolve the Session and RAG proxy-interface discrepancies.
• Test RabbitMQ routing, request/reply correlation, timeout handling, and message acknowledgements.
• Confirm handler registration and worker startup behavior.
• Verify PostgreSQL connectivity, schema migrations, and pgvector persistence.
• Validate Redis-backed rate limiting under expected and failure conditions.
• Test service-to-service authorization and secret handling.
• Record test evidence and update the documentation status.

8. Documentation Status and Maintenance¶

This document represents the initial beta-stage architecture baseline.

Maintain it according to the following rules:

• Separate current implementation from intended future architecture.
• Identify untested behavior and unresolved interfaces explicitly.
• Record implementation defects in the appropriate issue-tracking location.
• Update service responsibilities and communication diagrams when interfaces change.
• Validate diagrams against source code and runtime behavior.
• Keep credentials, tokens, private keys, and other secrets out of documentation.
• Revisit this document when deployment topology, service boundaries, or messaging contracts change.

Suggested verification record¶

For significant architecture changes, maintain a record containing:

This record supplements the overview; it does not replace detailed test reports or the project issue tracker.

Related documentation¶

Review status: Initial source-inspected baseline. Runtime validation, interface reconciliation, and detailed database verification remain outstanding.