Development Environment Setup¶

This guide explains how to prepare, start, and verify a local development environment for WhiteLotus AI. It covers the frontend, Python services, supporting infrastructure, database migrations, and quality checks.

1. Setup overview¶

A typical local development environment includes the following layers:

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

flowchart TB
    Dev["Developer"]
    FE["Next.js Frontend"]
    API["REST API Gateway<br/>FastAPI :8000"]

    subgraph Application["Application Services"]
        direction TB
        CHAT["Chat and Orchestration<br/>FastAPI :8001"]
        SESSION["Session Service<br/>:8002"]
        USER["User Service<br/>:8005"]
        RAG["RAG Service<br/>:8004"]
        INT["Integrations Service<br/>:8006"]
    end

    subgraph Infrastructure["Supporting Infrastructure"]
        direction TB
        REDIS[("Redis")]
        PG[("PostgreSQL + pgvector")]
        MQ[("RabbitMQ<br/>Where enabled")]
    end

    MODEL["Configured Model<br/>Runtime"]
    PROVIDER["External Providers"]

    %% Main request flow
    Dev --> FE
    FE -->|"HTTP API requests"| API

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

    CHAT --> RAG
    CHAT --> INT

    %% Infrastructure dependencies
    SESSION --> PG
    USER --> PG
    RAG -.->|"Vector storage dependency"| PG

    API -->|"Rate limiting / cache"| REDIS
    CHAT <--> MQ

    %% External dependencies
    INT <--> PROVIDER
    INT ~~~ MODEL
    CHAT --> MODEL
    MODEL ~~~ PROVIDER

    %% Pastel fills and category-specific outlines.

    classDef frontend fill:#E8F0FE,stroke:#2563EB,stroke-width:1.5px,color:#23345B
    classDef gateway fill:#E0E7FF,stroke:#6366F1,stroke-width:1.5px,color:#312E81
    classDef application fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#3B267A
    classDef messaging fill:#FFF2CC,stroke:#D97706,stroke-width:1.5px,color:#7C3E00
    classDef infrastructure fill:#DDF5E5,stroke:#059669,stroke-width:1.5px,color:#16452B
    classDef model fill:#FCE7F3,stroke:#DB2777,stroke-width:1.5px,color:#831843
    classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1.5px,color:#334155

    class Dev,FE frontend
    class API gateway
    class CHAT,SESSION,USER,RAG,INT,NOTIFY application
    class MQ messaging
    class PG,REDIS infrastructure
    class MODEL model
    class PROVIDER external

    %% Transparent containers preserve the active theme background.

    style Application fill:transparent,stroke:#7C3AED,stroke-width:1.5px,color:inherit
    style Infrastructure 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. Prerequisites¶

Install the tools required for the components you intend to run.

The repository audit previously observed Node.js 22.23.2 and npm 10.9.8. These are observed versions, not a guarantee that every environment must use those exact patch releases.

Verify the toolchain¶

Run the commands for the tools you plan to use:

git --version
python3 --version
uv --version
node --version
npm --version
docker --version
docker compose version

Confirm that the Python interpreter selected by uv is compatible with the target service. A globally installed Python version does not necessarily mean every project environment uses that interpreter.

3. Obtain the source code¶

Clone the repository URL and branch approved by the project maintainers.

git clone https://gitlab.com/sunilkunkekar/whitelotus_ai.git
cd whitelotus_ai

If dev-master is the intended development branch, check it out explicitly:

git fetch origin
git switch dev-master
git pull --ff-only

Verify the checkout before changing files or installing dependencies:

git status
git branch --show-current
git log -1 --oneline

Inspect the repository structure and locate common setup files:

ls -la
find . -maxdepth 3 \
  \( -name Makefile -o -name pyproject.toml -o -name package.json \
     -o -name compose.yaml -o -name docker-compose.yml \) -print

4. Configure environment variables¶

4.1 Find the environment templates¶

The repository audit identified .env.example and .env.compose files. Locate the current templates before creating local configuration:

find . -maxdepth 3 \
  \( -name ".env.example" -o -name ".env.compose" \) -print

Use the template intended for the runtime you are starting. Do not copy one root-level file into every service directory unless the repository explicitly documents that approach.

If the root .env.example is confirmed as the correct template for your local setup, create a local copy:

cp .env.example .env

Only run this command after confirming that the file exists and is intended for this environment. If a service uses its own environment template, follow that service's instructions instead.

4.2 Review required settings¶

Identify the exact variable names and required values from the current configuration templates and the code that reads them.

This guide intentionally avoids prescribing unverified environment variable names. Required settings must be confirmed against the active branch.

4.3 Protect secrets¶

• Never commit .env files containing credentials, access tokens, refresh tokens, or private keys.
• Do not copy production credentials into a local development environment.
• Prefer dedicated development OAuth applications and test accounts.
• Confirm that local environment files are excluded by .gitignore.
• Review tracked configuration files before publishing or sharing the repository.
• If a secret is exposed in source control, rotate or revoke it. Removing the file in a later commit does not invalidate an already exposed credential.

5. Set up Python services¶

WhiteLotus AI uses Python for backend services. The repository's service configuration and Makefiles should determine the correct dependency and startup commands.

5.1 Install dependencies¶

Move into the Python service you intend to work on and inspect its project files:

cd chat
ls -la
cat pyproject.toml
cat Makefile

The service Makefiles observed in the repository use:

uv sync --all-extras

Run this command from the directory whose pyproject.toml defines the intended project. Repeat the process for each required service, using its actual directory name and configuration.

Do not assume one service's virtual environment or dependencies cover every other service.

5.2 Verify the environment¶

uv run python --version

Use uv run for project commands when supported by the service configuration. It runs commands in the environment managed for that project.

5.3 Inspect service commands¶

Before starting or testing a service, review its Makefile:

cat Makefile

Repository Makefiles have used patterns such as the following:

uv run uvicorn <APPLICATION_MODULE> --reload
uv run coverage run -m pytest
uvx ruff check .

These are patterns, not universal commands. Replace <APPLICATION_MODULE> with the actual ASGI import path and use the target names and arguments defined by the service. Do not copy a placeholder literally or assume every service exposes the same targets.

6. Set up the frontend¶

The frontend uses Next.js, TypeScript, and Tailwind CSS.

6.1 Install dependencies¶

Navigate to the frontend directory identified by the current repository:

cd frontend
npm install

If the repository commits a lockfile and specifies a reproducible installation command, prefer that documented procedure—for example, npm ci when appropriate for the project's lockfile and workflow.

6.2 Start the development server¶

The frontend's documented npm scripts include dev, build, start, and lint.

npm run dev

The frontend is documented on port 3000 by default. Confirm the actual URL and port from the startup output and frontend configuration.

6.3 Verify the frontend¶

npm run lint
npm run build

A successful build confirms that the production bundle can be generated; it does not prove that login, API connectivity, streaming, or external integrations work end to end.

7. Start supporting infrastructure¶

The documented development architecture uses PostgreSQL with pgvector, Redis, and RabbitMQ. Inspect the active Compose configuration before starting containers.

docker compose config --services
docker compose config

The second command can print resolved configuration and interpolated values. Review its output locally and do not share it if it contains secrets.

Start infrastructure using the service names actually returned by docker compose config --services. For example, only if the names are postgres, redis, and rabbitmq:

docker compose up -d postgres redis rabbitmq

Check container status:

docker compose ps

Inspect logs when startup fails. Replace the example service names with the names in your Compose configuration:

docker compose logs --tail=100 postgres
docker compose logs --tail=100 redis
docker compose logs --tail=100 rabbitmq

7.1 Verify PostgreSQL and pgvector¶

The documented development configuration uses PostgreSQL with pgvector. The database host port has previously been documented as 5433, but container-to-container connections may use a different port.

Confirm the actual port mapping and connection URL in the active Compose and environment configuration.

Before running migrations, verify that:

• The intended PostgreSQL instance is running.
• The target database exists or can be initialized using the documented procedure.
• The configured credentials work.
• Required extensions, including pgvector where applicable, are available.
• The connection URL points to the intended local development database.

7.2 Verify Redis and RabbitMQ¶

Confirm that each service is reachable using the configured endpoint and credentials. A running container alone does not prove that application-level connections, authentication, queue declarations, or message consumption work correctly.

8. Initialize database migrations¶

The repository contains migration scripts for the user and session services:

• user/config/migrate.sh
• session/config/migrate.sh

Inspect the scripts and migration configuration before executing them:

sed -n '1,220p' user/config/migrate.sh
sed -n '1,220p' session/config/migrate.sh

Check the relevant service's Alembic configuration and migration files to identify the supported initialization command. Where the service configuration confirms Alembic is used, the standard command is:

uv run alembic upgrade head

Run it from the appropriate service directory, with the intended development database configured.

After migration, inspect the service logs and verify the database state. Do not assume that running the user service's migrations also initializes the session service's schema, or vice versa.

9. Start the application services¶

The following ports are documented in the development architecture. Verify host bindings and enabled services against the active configuration.

9.1 Start a service directly¶

Use the service's Makefile or README to identify its development command:

cat Makefile

A documented development pattern is:

uv run uvicorn <APPLICATION_MODULE> --reload

Replace <APPLICATION_MODULE> with the actual ASGI application import path specified by the service. Run the command from the correct service directory and include any required host, port, or environment options from the repository instructions.

9.2 Start services with Compose¶

If the active Compose configuration defines the backend services, list the available services first:

docker compose config --services

Then start the required services using their actual Compose names. Start infrastructure dependencies before application services. Unless Compose explicitly manages the frontend, start it separately using its npm development script.

9.3 Verify startup¶

For each required service, confirm that:

• The process or container remains running.
• The expected host and port are reported.
• Required environment variables are present.
• Database, cache, and messaging connections succeed where applicable.
• Startup logs contain no unresolved configuration, dependency, or authentication errors.

Do not assume a health-check URL exists. Use a health endpoint only if it is defined in the service's routes or documented configuration.

10. Run tests and quality checks¶

Run checks from the relevant service directory and prefer its Makefile targets when available.

10.1 Python tests¶

The repository's documented test pattern includes:

uv run coverage run -m pytest
uv run coverage report

Confirm the exact Makefile target, test discovery settings, and coverage arguments before using these commands in each service.

10.2 Python linting¶

The repository uses Ruff for Python linting:

uvx ruff check .

Run it from the intended service directory so it checks the correct project. If the repository pins Ruff or exposes a Makefile target, follow that configuration instead.

10.3 Frontend checks¶

npm run lint
npm run build

Use the scripts declared in the frontend's package.json; do not assume a script exists if it is absent from the checked-out branch.

10.4 Test safely¶

Before running tests, confirm that:

• The environment points to a local or dedicated test database.
• Tests cannot accidentally modify production data.
• Test credentials are separate from real user credentials.
• Integration tests use authorized test accounts or mocked provider responses.
• Tests do not send real messages or modify external resources.
• Migration and cleanup procedures are safe for the selected test environment.

A passing unit-test suite does not establish that all integrations, streaming paths, or deployment configurations work end to end.

11. Troubleshooting¶

When reporting a setup issue, include:

1. The exact command executed.
2. The complete error message, with secrets removed.
3. Relevant service logs.
4. Python, Node.js, npm, Docker, and dependency versions.
5. Relevant non-secret configuration details.
6. Reproduction steps and the result after applying a fix.

12. Completion checklist¶

Use this checklist to decide whether the environment is ready for development.

• Required tools are installed and use supported versions.
• Python dependencies install for each service in scope.
• Frontend dependencies install and the development server starts.
• Required infrastructure services are available.
• Database migrations complete for the intended services.
• Required backend services start with valid configuration.
• The frontend can reach the configured API gateway.
• Applicable lint, build, and test checks complete successfully.
• Required integration and model-runtime checks pass in the intended test environment.
• No production credentials or unintended production endpoints are in use.

Record optional components that were not started and integration paths that were not tested. Do not mark an untested component as verified.

Related documentation¶

Document maintenance: When setup commands or service boundaries change, update this guide in the same change set as the corresponding code or configuration.