docs: add runnable local setup

.env.example

@@ -1,12 +1,13 @@
+# Local development only. Replace all credentials in deployed environments.
 ENVIRONMENT=development
-DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/lead_scoring
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5433/lead_scoring
 AIHUB_BASE_URL=http://localhost:8080
 DEBUG=false
 
-# JSON arrays consumed by pydantic-settings.
-SERVICE_CALLERS=[]
-TENANT_ALLOWLIST=[]
-SCORING_CONFIGS=[]
+# JSON arrays consumed by pydantic-settings. These values work with the Dev Console example.
+SERVICE_CALLERS=[{"caller_id":"dev-console","token":"local-dev-token","allowed_apps":["dev-console"],"allowed_features":["lead-scoring"],"allowed_tenants":["omni-account-42","omni-test-tenant-42"]}]
+TENANT_ALLOWLIST=["omni-account-42","omni-test-tenant-42"]
+SCORING_CONFIGS=[{"version":"1.0.0","confidence":0.8,"confidence_threshold":0.7,"hitl_policy_version":"1.0.0","effort_profile":"medium","fallback_policy":"rules_only_review","ai_model":"openai/gpt-4o-mini"}]
 
 WORKER_LEASE_SECONDS=30
 WORKER_RECOVERY_INTERVAL_SECONDS=5

README.md

@@ -1,3 +1,133 @@
 # AI Platform - Lead Scoring Service
 
-Python-first Lead Scoring service for AI Platform.
+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
+```

apps/dev-console/.env.example

@@ -1,5 +1,7 @@
 DEV_CONSOLE_API_URL=http://localhost:8000
 DEV_CONSOLE_PORT=5173
 DEV_CONSOLE_PREVIEW_PORT=4173
-DEV_CONSOLE_SERVICE_TOKEN=replace-with-allowlisted-dev-console-token
-DEV_CONSOLE_TEST_VKEY=replace-with-test-only-vkey
+# Must match SERVICE_CALLERS in the root .env for the local setup.
+DEV_CONSOLE_SERVICE_TOKEN=local-dev-token
+# Used only to call a local AIHub. Any non-empty value exercises rules-only fallback when AIHub is absent.
+DEV_CONSOLE_TEST_VKEY=local-test-vkey

compose.yaml

@@ -0,0 +1,14 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: lead_scoring
+    ports:
+      - "${POSTGRES_PORT:-5433}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d lead_scoring"]
+      interval: 5s
+      timeout: 5s
+      retries: 10