Component	Purpose	Default address
PostgreSQL 16	Stores scoring runs and migrations	`localhost:5433`
Lead Scoring API	REST API, async scoring worker, OpenAPI	`http://localhost:8000`
Dev Console	Internal fixture and contract-testing UI	`http://localhost:5173`
AIHub	Optional external AI inference dependency	`http://localhost:8080`

The service still runs if local AIHub is unavailable: the default config uses rules_only_review fallback. A reachable AIHub and a valid tenant VKey are required for live AI scoring.

Requirements

Install before starting:

Git
Python 3.13 or newer
uv
Bun
Docker with Docker Compose plugin

Start from a fresh clone

git clone https://github.com/HungTran24/dotb_ai-platform.git
cd dotb_ai-platform
cp .env.example .env
cp apps/dev-console/.env.example apps/dev-console/.env

The copied .env files are local only and ignored by Git. Their example values are intentionally for development only.

1. Start PostgreSQL

docker compose up -d postgres
docker compose ps

The included Compose service exposes PostgreSQL on port 5433 to avoid conflicting with other local projects. If port 5433 is occupied, choose another port and update both values before migration:

POSTGRES_PORT=15432 docker compose up -d postgres
# Then set DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:15432/lead_scoring in .env

2. Install backend dependencies and migrate the database

uv sync
uv run alembic upgrade head

3. Start the Lead Scoring API

Run in a separate terminal from the repository root:

uv run uvicorn lead_scoring.main:app --reload --host 0.0.0.0 --port 8000

Check the API:

curl http://localhost:8000/health

OpenAPI UI: http://localhost:8000/docs

4. Start the Dev Console

Run in a second terminal:

cd apps/dev-console
bun install --frozen-lockfile
bun run dev

Open http://localhost:5173.

Local configuration

Root .env configures the backend. apps/dev-console/.env configures the Vite development server.

Variable	Default	Purpose
`DATABASE_URL`	PostgreSQL at `localhost:5433`	Backend database connection
`AIHUB_BASE_URL`	`http://localhost:8080`	Optional AIHub endpoint
`DEV_CONSOLE_API_URL`	`http://localhost:8000`	Dev Console API proxy target
`DEV_CONSOLE_PORT`	`5173`	Dev Console development port
`DEV_CONSOLE_PREVIEW_PORT`	`4173`	Dev Console preview port
`DEV_CONSOLE_SERVICE_TOKEN`	`local-dev-token`	Must match the local backend `SERVICE_CALLERS` entry
`DEV_CONSOLE_TEST_VKEY`	`local-test-vkey`	Forwarded only to AIHub calls; replace for real AIHub use

The local backend template includes an allowlisted dev-console caller and baseline scoring config version 1.0.0, so the Dev Console can open immediately after startup.

Stop local services

docker compose down

To remove the local database data too:

docker compose down -v

Verification

Backend:

uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run pyright
uv run ty check

Frontend:

cd apps/dev-console
bun run check
bun run test
bun run build