AI Platform - Lead Scoring Service
Lead Scoring service and internal Dev Console for the AI Platform.
What runs locally
| 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:
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