Repository Structure¶

Document status: Architecture-informed reference. Verify directory names, filenames, and implementation details against the active application checkout before treating this page as a definitive source-code inventory.

This guide explains how to navigate the WhiteLotus AI codebase, identify the correct area for an engineering change, and trace functionality across service boundaries.

WhiteLotus AI follows a multi-service architecture that includes a Next.js frontend, Python backend services, AI orchestration, retrieval-augmented generation (RAG), external integrations, and supporting infrastructure.

1. Repository at a glance¶

The repository map should be derived from the checked-out source rather than maintained as a manually assumed directory tree.

The following diagram illustrates the logical architecture and investigation boundaries. It is not a verified directory listing or a complete runtime deployment diagram.

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

flowchart TB
    DEV["Developer"]

    subgraph CLIENT["Client Layer"]
        direction TB
        FE["Next.js Frontend"]
    end

    subgraph BACKEND["Backend Services"]
        direction TB
        API["REST API Gateway"]
        CHAT["Chat and AI Orchestration"]
        SESSION["Session Service"]
        USER["User Service"]
        RAG["RAG Service"]
        INTEG["Integrations Service"]
    end

    subgraph SHARED["Shared and Supporting Components"]
        direction TB
        LIB["Shared Backend Library"]
        DATA[("Database and Vector Storage")]
        CACHE[("Cache and Messaging")]
        MODEL["Model Runtime"]
        PROVIDERS["External Providers"]
    end

    DEV --> FE
    FE -->|"HTTP API requests"| API

    API -.-> CHAT
    API -.-> SESSION
    API -.-> USER

    CHAT --> RAG
    CHAT --> INTEG
    CHAT --> LIB
    SESSION --> LIB
    USER --> LIB

    RAG --> MODEL
    RAG --> DATA
    INTEG --> PROVIDERS
    API --> CACHE

    %% Pastel fills with category-specific colored outlines.

    classDef developer fill:#F1F5F9,stroke:#64748B,stroke-width:1.5px,color:#334155
    classDef client fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef application fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef support fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B
    classDef model fill:#FCE7F3,stroke:#DB2777,stroke-width:1.5px,color:#831843
    classDef cache fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,color:#7C3E00

    class DEV developer
    class FE client
    class API,CHAT,SESSION,USER,RAG,INTEG application
    class LIB,DATA,PROVIDERS support
    class MODEL model
    class CACHE cache

    %% Transparent containers preserve the active theme background.

    style CLIENT fill:transparent,stroke:#2563EB,stroke-width:1.5px,color:inherit
    style BACKEND fill:transparent,stroke:#7C3AED,stroke-width:1.5px,color:inherit
    style SHARED fill:transparent,stroke:#059669,stroke-width:1.5px,color:inherit

    %% Neutral connectors remain legible across themes.

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

2. Repository organization¶

The table below maps known architectural components to their expected responsibilities. Directory names are candidate locations to verify, not guarantees about the current checkout.

3. Find the right place to make a change¶

Use this task-oriented reference to choose an initial investigation point.

4. Generate a verified repository inventory¶

Run the following commands from the application repository root. Review their output locally before adding concrete filenames to this document.

4.1 List tracked and untracked source files¶

find . -maxdepth 3 \
  \( -path './.git' \
  -o -path './.venv' \
  -o -path './venv' \
  -o -path './node_modules' \
  -o -path './__pycache__' \
  -o -path './site' \
  -o -path './dist' \
  -o -path './build' \) -prune \
  -o -type f -print | sort

This command lists files up to three directory levels deep while excluding common generated directories. It does not guarantee that sensitive files are excluded.

4.2 List top-level directories¶

find . -maxdepth 2 -type d \
  -not -path './.git*' \
  -not -path './.venv*' \
  -not -path './venv*' \
  -not -path './node_modules*' \
  -not -path './__pycache__*' \
  -not -path './site*' \
  | sort

Use this output to check which service directories actually exist and how the repository is organized.

4.3 Locate development and build manifests¶

find . -maxdepth 3 \
  \( -name Makefile \
  -o -name pyproject.toml \
  -o -name requirements.txt \
  -o -name package.json \
  -o -name Dockerfile \
  -o -name compose.yaml \
  -o -name docker-compose.yml \
  -o -name .gitlab-ci.yml \) \
  -type f -print | sort

These files help establish the available development commands, dependency boundaries, container build definitions, and CI/CD configuration.

5. Inspect each service consistently¶

Do not assume that every Python service has the same directory layout, startup command, dependency configuration, or migration strategy.

For each verified service, record the following elements where applicable.

Recommended inspection workflow¶

1. Identify the service's actual entry point.
2. Trace the route or event handler into its business logic.
3. Locate data-access code and external dependencies.
4. Identify configuration inputs and authorization checks.
5. Find tests that cover the affected behavior.
6. Verify the supported build and execution commands.
7. Record only confirmed paths in the documentation.

6. AI orchestration and tool registry¶

The chat service owns conversation processing and AI orchestration. Its exact implementation should be identified from the active source rather than inferred from a high-level architecture diagram.

When auditing orchestration, locate the following responsibilities:

• Safety and context preparation: Input handling, safety checks, and conversation context.
• Intent classification and routing: Selection of the appropriate processing path.
• Authorization: Server-side verification of the user's identity and permissions.
• Tool registration: Declaration of available tools and supported operations.
• Tool dispatch: Selection and invocation of authorized operations.
• Model invocation: Construction of model inputs and processing of responses.
• Response formatting: Normalization of results and user-facing output.
• Streaming and errors: Event delivery, cancellation, and failure handling.
• Regression tests: Coverage for routing, authorization, tool execution, and streaming.

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

flowchart TD
    INPUT["Incoming Chat Request"]
    SAFETY["Safety and Context"]
    INTENT["Intent Classification"]
    AUTH["Server-Side Authorization"]
    DISPATCH["Tool Registry and Dispatch"]
    EXEC["Authorized Operation"]
    MODEL["Model Processing"]
    FORMAT["Response Formatting"]
    OUTPUT["Response or Stream"]

    INPUT --> SAFETY
    SAFETY --> INTENT
    INTENT --> AUTH
    AUTH --> DISPATCH
    DISPATCH --> EXEC
    EXEC --> MODEL
    MODEL --> FORMAT
    FORMAT --> OUTPUT

    %% Pastel fills with category-specific colored outlines.

    classDef boundary fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef execution fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef output fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B

    class INPUT,SAFETY,INTENT,AUTH boundary
    class DISPATCH,EXEC,MODEL,FORMAT execution
    class OUTPUT output

    %% Neutral connectors remain legible across themes.

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

Diagram note: This is an illustrative investigation model, not a verified representation of the exact production graph, node order, or error branches. Confirm the actual execution sequence in the current implementation.

7. Integration implementations¶

The intended integration scope includes Gmail, Google Calendar, Google Drive, Jira, Slack, and Microsoft Teams.

For each provider, locate the verified implementation for the following areas.

8. Configuration and secrets¶

Configuration should be documented from the service settings implementation, environment templates, and deployment definitions.

Use placeholders in examples rather than real secrets.

# Illustrative placeholders only; verify names against the actual settings.
DATABASE_URL=<database-connection-string>
REDIS_URL=<redis-connection-string>
INTERNAL_SERVICE_SECRET=<locally-configured-secret>

The names above are examples, not a declaration that these variables exist in the current application.

9. Tests and quality assurance¶

Map the test suites to the behaviors and boundaries they verify. The following categories are audit targets; their existence and coverage must be confirmed from the repository.

Pull request verification checklist¶

Use this checklist when reviewing a change that affects service behavior.

• The implementation and its callers have been identified.
• Authentication and authorization boundaries have been reviewed.
• Relevant unit, API, and regression tests have been updated.
• External provider operations and error paths have been checked.
• Configuration changes are reflected in safe environment templates.
• Documentation and architecture diagrams match verified behavior.
• No credentials, local data, or generated artifacts have been committed.
• The relevant tests and documentation build complete successfully.

10. Deployment and CI/CD assets¶

Inspect the active repository and deployment configuration for the assets that actually exist.

Keep local-development instructions distinct from production deployment procedures.

11. Ownership and change management¶

Apply the following rules when maintaining the repository and its documentation.

• Assign clear ownership to security-critical modules, authentication logic, and provider adapters.
• Preserve service boundaries and keep architecture diagrams aligned with verified source.
• Update tests when changing routes, tool dispatch, data access, or authorization.
• Treat generated code and build artifacts as generated content.
• Keep secrets, local databases, caches, virtual environments, and build output out of published repository maps.
• Update this guide when major directories, service responsibilities, or development workflows change.
• Verify paths and commands against the active branch before merging documentation changes.

12. Completion criteria¶

A repository map is ready to be treated as verified when all applicable criteria below have been met.

• Documented service directories have been checked against the active checkout.
• Application entry points and dependency manifests have been identified.
• Configuration, tests, migrations, and deployment assets have been located.
• Security-critical modules and integration boundaries have been mapped.
• No credentials or sensitive local paths are included.
• Confirmed facts are clearly distinguished from assumptions.
• All documented commands have been tested or their limitations stated.
• The documentation build completes successfully.

13. Build and maintain this page¶

After editing the page, run the documentation build from the documentation repository root, where zensical.toml is configured.

zensical build --clean --strict

If the command reports an error, resolve it before merging. In particular, verify front matter, Markdown formatting, Mermaid rendering, internal links, and any admonition or extension syntax used by the site configuration.