WhiteLotusAI - Product Overview¶

Product clarity. Engineering precision. Operational confidence.

WhiteLotusAI is an AI assistant platform with a Next.js frontend and a Python microservices backend. Its repository includes conversational AI orchestration, retrieval-augmented generation (RAG), user and session management, and integrations with external productivity and collaboration platforms.

This page summarizes the product scope represented in the inspected repository. It distinguishes repository evidence from behavior that still requires testing or product-owner approval.

1. Product at a glance¶

2. Product purpose and vision¶

Purpose¶

WhiteLotusAI brings together an AI assistant interface, conversation management, application-managed knowledge-base functionality, and supported external integrations within one application.

The repository includes components intended to support these workflows. Their complete behavior and operational guarantees must be established through appropriate verification.

Product vision¶

The product aims to provide a unified assistant through which users can:

• Interact with a configured language model.
• Work with conversation sessions and message history.
• Retrieve information from an application-managed knowledge base.
• Access supported external productivity and collaboration integrations.

The formally approved product vision, target market, and measurable business outcomes remain subject to product-owner confirmation.

3. Intended audiences¶

These personas describe intended audiences, not proof that every associated workflow is fully implemented.

4. Current capability areas¶

The following sections describe capabilities represented in the inspected repository. They should not be read as end-to-end verification results.

4.1 Conversational AI¶

The application includes a browser-based chat interface and a backend agent workflow.

Repository evidence includes:

• Streaming chat-response functionality.
• Conversation sessions and message-history functionality.
• Agent workflow stages for safety, context, intent, authorization, tool dispatch, language-model interaction, and response formatting.
• Configurable language-model provider paths in the chat service's model factory.

The inspected model factory contains configuration paths for OpenAI and OpenRouter. Credentials, model availability, response quality, and runtime connectivity must be verified in the target environment.

4.2 Knowledge base and retrieval¶

The frontend includes a knowledge-base interface, while the backend repository contains RAG and document-processing components.

The inspected code paths include document-ingestion functionality, retrieval-related operations, and document-management interactions.

Before describing these as supported guarantees, verify:

• Accepted file types and file-size or ingestion limits.
• Ingestion failure handling and document lifecycle behavior.
• Retrieval relevance and answer grounding.
• Authorization and access boundaries for stored documents.
• Deletion behavior and any associated retention requirements.

4.3 User identity and sessions¶

The frontend and REST API contain authentication-related flows for registration, login, token refresh, logout, profile retrieval, profile updates, and password changes.

The application also contains session-management functionality for creating, listing, switching, and deleting conversations.

The existence of these code paths does not establish that all authorization, token-lifecycle, account-security, or session-isolation scenarios have passed testing.

4.4 External integrations¶

The chat service registers plugin implementations for the following providers:

The application also contains integration-connection interfaces and OAuth-related code.

The presence of a provider's implementation does not prove that the provider is connected, operational, correctly authorized, or restricted to read operations.

See the Integration Overview and Read-Only Integration Policy for related documentation.

4.5 User interface¶

The frontend includes components for:

• Chat and conversation navigation.
• Account access and profile settings.
• Knowledge-base interactions.
• Plugin connections.
• Notifications.

Actual behavior may depend on backend availability, user permissions, provider configuration, and browser state.

5. High-level system architecture¶

The repository separates application responsibilities across the frontend, API, and supporting services.

flowchart TB
    U(["User"])
    FE["Next.js Frontend"]
    API["REST API Gateway"]

    subgraph APP["Application Services"]
        direction TB
        CHAT["Chat Service"]
        SESSION["Session Service"]
        USER["User Service"]
        RAG["RAG Service"]
        INT["Integrations Service"]
    end

    MODEL["Configured Model Provider"]
    PG[("PostgreSQL")]
    REDIS[("Redis")]
    MQ[("RabbitMQ")]
    EXT["External Productivity Services"]

    U --> FE
    FE --> API
    API --> CHAT
    API --> SESSION
    API --> USER

    CHAT --> MODEL
    CHAT --> INT
    CHAT --> RAG
    INT --> EXT

    SESSION --> PG
    USER --> PG
    RAG --> PG

    API --> REDIS
    CHAT --> MQ
    SESSION --> MQ
    USER --> MQ


    %% Pastel fills and colored borders for clear visual grouping.
    classDef client fill:#E8F0FE,stroke:#4F83CC,stroke-width:1.5px,color:#23345B
    classDef gateway fill:#EDE9FE,stroke:#7C3AED,stroke-width:2px,color:#3B267A
    classDef application fill:#E0F7FA,stroke:#0891B2,stroke-width:1.5px,color:#164E63
    classDef data fill:#DDF5E5,stroke:#25804B,stroke-width:1.5px,color:#16452B
    classDef messaging fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,color:#7C3E00
    classDef external fill:#FCE8E6,stroke:#C2410C,stroke-width:1.5px,color:#7F2718

    class U,FE client
    class API gateway
    class CHAT,SESSION,USER,RAG,INT application
    class PG,REDIS data
    class MQ messaging
    class MODEL,EXT external

    %% Transparent group background preserves the active theme.
    style APP fill:transparent,stroke:#0891B2,stroke-width:1.5px,color:inherit

    %% Consistent connector contrast across themes.
    linkStyle default stroke:#9CA3AF,stroke-width:1.3px

Conceptual overview derived from the repository's documented service responsibilities. It is not a verified sequence diagram for every request. Confirm individual request paths against the relevant implementation and configuration.

The local Docker Compose configuration defines PostgreSQL, Redis, RabbitMQ, and application services. The production Compose configuration additionally defines frontend, Nginx, and Certbot components.

The precise communication path varies by operation. Consult the architecture overview, system design, and API reference for the verified flow of a specific request.

6. Technology overview¶

Exact dependency versions and environment-specific configuration are maintained in the repository's dependency and deployment files.

7. Product boundaries and constraints¶

The following boundaries should guide product documentation and implementation reviews.

1. Read-only integrations: Do not expose integration write operations until explicitly approved, implemented, tested, and documented.
2. Authorization: Tool execution and access to user data must be controlled by trusted application code.
3. External dependencies: Model providers and third-party integrations may require valid credentials, permissions, network connectivity, and available upstream services.
4. Knowledge-base accuracy: Retrieved content and generated answers must not be treated as inherently complete or correct.
5. Environment differences: Local Compose, production Compose, and developer-host configurations must not be assumed to behave identically.
6. Security and privacy: Credentials, tokens, and user data require appropriate protection, access controls, and retention policies.

8. Verification and release readiness¶

This overview is based on repository inspection rather than a complete runtime acceptance test.

Before declaring the product ready for release, verify at least the following areas:

• Registration, login, authorization, token refresh, and logout.
• Chat responses, streaming, session history, and failure handling.
• Document ingestion, retrieval, deletion, and access boundaries.
• Provider authentication, permissions, and read-only tool enforcement.
• Service health, database persistence, and message-broker communication.
• Deployment configuration, secret handling, monitoring, and recovery procedures.

Record the test evidence and results in the Testing and Governance sections.

9. Open product decisions¶

The product owner should confirm and maintain the following decisions:

Until approved, these items should remain clearly identified as open decisions rather than finalized product commitments.

10. Review and maintenance¶

Review this document whenever product scope, user workflows, supported integrations, architecture, or release commitments change.

For each implementation claim:

1. Identify the relevant source code or configuration.
2. Determine whether the claim concerns implementation, intended behavior, or observed runtime behavior.
3. Attach appropriate test or runtime evidence for behavioral claims.
4. Update related pages and cross-references when scope or behavior changes.
5. Record unresolved discrepancies and assign them for follow-up.

Related documentation¶

Maintenance note: Keep this page aligned with the current repository, approved product decisions, relevant tests, and release-specific evidence.