WhiteLotusAI — System Design¶

Document type: System Design Specification
Product stage: Beta
Status: Source-inspected baseline; runtime verification pending
Audience: Software Engineers, QA Engineers, DevOps, Security Reviewers, and Technical Stakeholders
Organization: Whitelotus Corporation

1. Purpose and Scope¶

This document defines the system-level design of WhiteLotusAI, including its application components, service boundaries, communication mechanisms, supporting infrastructure, deployment considerations, and outstanding architectural questions.

It establishes a common technical reference for implementation, testing, maintenance, and future architectural decisions.

The specification is based on the source-code and configuration observations documented in the current engineering baseline. It distinguishes configured behavior from runtime-verified behavior and identifies areas that require further investigation.

1.1 Scope¶

This document covers:

• Logical system architecture and component responsibilities.
• HTTP and RabbitMQ communication patterns.
• Application services and message-processing workers.
• Database, caching, and message-broker dependencies.
• Deployment and runtime considerations.
• Known design risks, verification requirements, and maintenance principles.

Detailed API contracts, database schemas, integration-specific behavior, and deployment procedures belong in their respective documentation pages.

2. System Design Overview¶

WhiteLotusAI follows a multi-service architecture combining a Next.js frontend, a FastAPI API gateway, dedicated application services, message-driven workers, and supporting infrastructure.

The system uses synchronous HTTP communication for web-facing and service API operations, alongside RabbitMQ messaging for selected inter-service requests and background processing.

2.1 Architectural characteristics¶

2.2 High-level design principles¶

These principles guide implementation decisions, architectural reviews, testing, and documentation maintenance. They do not imply that every requirement has already been implemented or verified.

3. Logical System Architecture¶

The following diagram represents the observed logical relationships between the main application components and supporting infrastructure. It deliberately distinguishes configured HTTP proxy relationships from verified service interfaces.

3.1 Architecture diagram¶

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 with colored outlines for the reference design.
    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 active theme background.
    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 dark and light themes.
    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

3.2 Architecture interpretation¶

1. The browser loads the Next.js frontend.
2. The frontend sends API requests to the configured gateway base URL.
3. The FastAPI gateway handles explicit API routes and then applies its configured proxy behavior for applicable unmatched requests.
4. The gateway, Chat service, and Integrations service participate in selected RabbitMQ workflows.
5. User, Session, and RAG workers process messages through the shared listener and handler infrastructure.
6. Redis supports the gateway's configured rate-limiting functionality.
7. PostgreSQL with pgvector is configured as database infrastructure, while the precise schema and persistence relationships remain subject to verification.

The diagram describes the logical design baseline. It is not a network topology, deployment guarantee, or end-to-end execution trace.

4. Component Responsibilities¶

4.1 Component inventory¶

4.2 REST API gateway¶

The REST API gateway is implemented using FastAPI and is configured on port 8000.

Its inspected responsibilities include:

• Exposing application API routers.
• Applying the configured CORS policy.
• Initializing Redis-backed rate limiting.
• Dispatching requests through explicit route handlers.
• Forwarding applicable unmatched requests through a proxy router.
• Initiating RabbitMQ request/reply operations for supported backend methods.
• Configuring API documentation availability according to the execution environment.

The gateway configuration references Chat, Session, RAG, User, and Integrations upstream URLs.

4.3 Chat service¶

The Chat service is a FastAPI application configured on port 8001, with the route prefix /api/chat-svc.

The inspected startup sequence includes:

1. Registering plugins.
2. Performing plugin health checks.
3. Starting a health-check loop.
4. Warming the agent.
5. Starting a RabbitMQ listener for chat messages.
6. Loading configured service URLs and messaging settings for selected operations.

The service therefore participates in HTTP and message-based workflows.

4.4 Integrations service¶

The Integrations service is a FastAPI application configured on port 8006.

Its inspected application includes integration and webhook routers under /api/integrations-svc, alongside MCP and OAuth-related routers.

Observed responsibilities include:

• Exposing integration-related APIs.
• Handling webhook routes.
• Providing MCP-related functionality.
• Supporting OAuth-related operations.
• Calling Chat HTTP endpoints for tool-schema discovery and tool dispatch.
• Participating in selected message-driven workflows.

The service's HTTP contracts, integration-specific authorization, OAuth lifecycle, and message-based dependencies should be documented in their respective reference pages.

4.5 User worker¶

The User entry point imports user handler modules and starts the shared RabbitMQ listener. It also checks encryption-key configuration before listening.

The inspected entry point establishes a message-driven worker. It does not establish that this entry point creates a FastAPI application or mounts the User OAuth token APIRouter.

The existence and availability of any separate User HTTP interface must be verified independently.

4.6 Session worker¶

The Session entry point imports session handlers and starts the shared RabbitMQ listener.

The inspected implementation establishes a message-consumer entry point, but does not establish that the worker exposes an HTTP API.

Session operations should be documented using the actual registered message methods and payload contracts rather than inferred from the gateway's configured upstream URLs.

4.7 RAG worker¶

The RAG entry point imports its handler modules and initializes supporting components before starting its listener.

The inspected startup sequence is:

1. Load the embedding model.
2. Initialize the vector-store pool.
3. Start the RabbitMQ listener.
4. Close the search cache and vector-store pool during shutdown.

The configured responsibilities include document ingestion, retrieval, and document-management operations through message handlers.

The exact vector-store implementation, database schema, embedding configuration, and runtime persistence guarantees require further inspection.

5. Inter-Service Communication¶

WhiteLotusAI uses HTTP and RabbitMQ for distinct interaction patterns. The communication contract must be understood in terms of the initiating component, destination, transport, payload, and expected response.

5.1 HTTP request/response¶

HTTP is used for frontend-to-gateway requests and for APIs exposed by FastAPI applications.

The Integrations service also calls Chat endpoints for MCP tool-schema discovery and tool dispatch.

The gateway defines HTTP proxy mappings for multiple services. However, the inspected User, Session, and RAG entry points are message consumers, which creates an interface-alignment question for corresponding proxy paths.

HTTP verification checklist¶

• Confirm each configured upstream URL resolves to the intended process.
• Confirm the destination exposes the expected HTTP routes and methods.
• Verify authentication and authorization at each applicable boundary.
• Verify request and response schemas.
• Verify timeout behavior and upstream error propagation.
• Verify proxy routing does not unintentionally bypass security controls.

5.2 RabbitMQ request/reply¶

The shared messaging implementation provides a message-based request/reply mechanism.

sequenceDiagram
    autonumber

    participant C as Requesting Component
    participant Q as RabbitMQ Broker
    participant W as Worker
    participant H as Registered Handler

    rect rgb(219, 234, 254)
        Note over C,Q: 1. REQUEST DISPATCH
        C->>C: Prepare request and correlation ID
        C->>Q: Publish request with routing key
        Q->>W: Deliver message to worker
    end

    rect rgb(243, 232, 255)
        Note over W,H: 2. HANDLER EXECUTION
        W->>H: Dispatch through process_data
        H-->>W: Return handler result
    end

    rect rgb(209, 250, 229)
        Note over W,Q: 3. RESPONSE DELIVERY
        W->>Q: Publish reply when applicable
        Q-->>C: Deliver correlated reply
    end

    Note over C,H: Verify timeout, retry, acknowledgement, and failure behavior

The sequence illustrates the observed design pattern, not a guarantee that every request follows the complete sequence successfully.

The observed flow is:

1. The caller creates or obtains a reply destination.
2. The caller publishes a request to the configured exchange.
3. A routing key identifies the destination queue.
4. The request includes a correlation identifier.
5. The worker dispatches the request through BaseHandler.process_data.
6. The worker sends the result to the request's reply destination when applicable.
7. The caller correlates the reply with the original request.

The listener uses robust RabbitMQ connections and includes connection retry logic.

5.3 Handler registration¶

The inspected worker entry points import their handler modules before invoking the shared listen(...) function.

This import-based registration pattern makes handler availability dependent on module imports and successful handler registration.

The following contracts require verification before publishing a complete messaging API reference:

• Registered method names and destination queues.
• Request and response payload schemas.
• Unknown-method handling.
• Handler exceptions and error serialization.
• Message acknowledgements and retry behavior.
• Correlation identifiers and reply timeouts.

5.4 Communication pattern comparison¶

Neither transport should be considered reliable solely because its client library or connection configuration supports retries.

6. Supporting Infrastructure¶

6.1 Infrastructure inventory¶

Versions and image references above describe the inspected configuration baseline. They should be reconciled with the active deployment manifests before a release.

6.2 PostgreSQL and pgvector¶

The Docker Compose configuration uses pgvector/pgvector:pg16.

This establishes the configured database image but does not establish the complete database design or which application services access specific tables.

The database architecture reference should be based on verified:

• ORM models and table definitions.
• Migration history and current schema.
• Primary and foreign key relationships.
• Vector dimensions and index configuration.
• Transaction boundaries and persistence ownership.
• Database connection settings for each service.

6.3 Redis¶

The Docker Compose configuration uses Redis 7. The REST API initializes a Redis-backed rate limiter during application startup.

Other Redis responsibilities should be documented only after inspecting the relevant clients, call sites, key prefixes, expiration policies, and failure handling.

6.4 RabbitMQ¶

The configured RabbitMQ deployment uses the rabbitmq:3.13-management image.

The inspected application components use exchanges and queues for message consumption and request/reply operations.

A dedicated messaging reference should identify:

Do not infer queue durability, delivery guarantees, or dead-letter configuration from the presence of RabbitMQ alone.

7. Deployment and Runtime Considerations¶

The repository contains Docker Compose configurations for local and production-oriented deployment. The inspected configuration includes application services, PostgreSQL, Redis, RabbitMQ, a frontend container in the production-oriented setup, Nginx, and a Certbot renewal container.

The presence of deployment configuration is not equivalent to verified production readiness.

7.1 Deployment validation¶

7.2 Configuration and secrets¶

Credentials, encryption keys, OAuth tokens, and internal service secrets must be managed outside committed source files.

Configuration should be validated at startup, with missing or invalid required values producing explicit failures rather than silent degradation.

For related configuration details, see Configuration.

8. Known Design Risks and Open Questions¶

The following register captures outstanding issues in the source-inspected baseline. These are investigation items, not assertions that every affected workflow is broken.

9. Design Principles for Beta Development¶

The following principles should guide architectural changes and documentation maintenance.

1. Explicit interfaces: Every service must have identifiable supported HTTP routes, message methods, or both.
2. Traceable communication: Document the caller, destination, transport, payload, and expected response for each important interaction.
3. Verified contracts: Derive API schemas and messaging contracts from implementation and tests.
4. Secure configuration: Keep credentials, encryption keys, and OAuth tokens outside committed source files.
5. Observable operation: Health checks should reflect meaningful service readiness rather than process existence alone.
6. Defined failure handling: Test timeouts, retries, broker outages, partial failures, and recovery.
7. Incremental documentation: Update affected reference pages when implementation changes.
8. Evidence-based status: Mark a component or workflow as verified only when sufficient evidence supports the claim.

9.1 Verification maturity¶

Use the following distinctions when reviewing architecture statements.

These classifications are not interchangeable. In particular, configuration confirmation does not establish runtime or production behavior.

10. Review and Maintenance¶

Review this document whenever service responsibilities, communication mechanisms, deployment dependencies, security boundaries, or persistence architecture change.

Before promoting this baseline to a production-ready system-design specification:

• Resolve or formally accept the outstanding interface questions.
• Validate the principal frontend-to-backend workflows.
• Verify message contracts and failure-handling behavior.
• Reconcile database documentation with the actual schema and persistence code.
• Review production network boundaries, CORS, secrets, and TLS configuration.
• Ensure architectural diagrams remain consistent with the implementation.

Document changes should be reviewed alongside relevant code changes so that architectural claims remain traceable to the implementation.

Related documentation¶

Document status: Initial source-inspected system-design baseline. Runtime verification and resolution of the outstanding design questions remain pending.