# 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:

- Git
- Python 3.13 or newer
- [uv](https://docs.astral.sh/uv/)
- [Bun](https://bun.sh/)
- Docker with Docker Compose plugin

## Start from a fresh clone

```bash
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

```bash
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:

```bash
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

```bash
uv sync
uv run alembic upgrade head
```

### 3. Start the Lead Scoring API

Run in a separate terminal from the repository root:

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

Check the API:

```bash
curl http://localhost:8000/health
```

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

### 4. Start the Dev Console

Run in a second terminal:

```bash
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

```bash
docker compose down
```

To remove the local database data too:

```bash
docker compose down -v
```

## Verification

Backend:

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

Frontend:

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