# MVP Contact Center (KZ) - Sequential 4-Stage Implementation

This repository bootstraps the agreed MVP implementation for the contact center platform.

## What is implemented

- Stage 1 foundation artifacts
  - API gateway skeleton
  - local RBAC auth service
  - users, health, audit contracts
  - Kubernetes + Helm + CI skeleton
  - observability baseline docs and manifests
- Stage 2 operator core APIs
  - customers
  - interactions and escalation
  - queue/routing rules
  - voice events adapter (Asterisk-facing)
  - Telegram webhook adapter
  - Webchat intake adapter
- Stage 3 supervisor/reporting/KB-lite APIs
  - knowledge base categories/articles/search
  - KPI aggregation (SL, ASA, AHT, Abandon, FCR)
  - supervisor realtime endpoints
- Stage 4 pilot hardening package
  - gate checklists
  - UAT package and templates
  - runbooks for backup/restore and pilot operations
- Wave 2 Track 1-2 baseline
  - signed bearer-token auth + optional Keycloak OIDC login
  - first additional digital channels: Webchat and Email
- Wave 2 Track 4 baseline
  - recording-service for managed local voice recordings
  - supervisor playback/download/archive flow
- Wave 2 Track 5 baseline
  - ivr-service for DTMF voice flows and IVR runtime sessions
  - IVR-aware route preview and admin-side IVR management
- Wave 2 Track 6 baseline
  - expanded KPI catalog with channel-aware metrics and coverage endpoint
  - reporting export now includes channel and agent dimensions
- Wave 2 Track 7 baseline
  - production-like Helm scale profile for K8s on-prem
  - Postgres-first DB pooling and formal load/hardening validation scripts
- Wave 2 Track 8 baseline
  - RabbitMQ-backed event bus with transactional outbox
  - first consumers wired for audit and reporting

## Architecture

- Microservices (FastAPI), each service isolated in `services/*`
- API contracts in `contracts/openapi`
- Event schemas in `contracts/events`
- Deployment:
  - Local compose: `deployment/docker-compose.yml`
  - Kubernetes manifests: `deployment/kubernetes`
  - Helm chart: `deployment/helm`
  - GitLab registry server deploy: `deployment/docker-compose.server.registry.yml`
- Service state persistence:
  - SQL storage via `DATABASE_URL` for all services (SQLite by default, PostgreSQL supported)
  - production-like K8s scale validation is PostgreSQL-only

## Quick start (local)

1. Install dependencies

```bash
python -m pip install -r requirements.txt
```

2. Run tests

```bash
pytest -q
```

3. Apply DB migrations

```bash
python scripts/migrate_core_db.py
```

3. Start individual services (example)

```bash
uvicorn services.auth_service.app:app --reload --port 8001
uvicorn services.interaction_service.app:app --reload --port 8004
```

4. Start local gateway

```bash
uvicorn gateway.app:app --reload --port 8080
```

Operator UI is available at:

```text
http://localhost:8080/operator
```

Additional dedicated Wave 2 shells:

```text
http://localhost:8080/supervisor
http://localhost:8080/admin
```

5. Optional helper scripts (PowerShell)

```powershell
powershell -ExecutionPolicy Bypass -File scripts\run_all_local.ps1
powershell -ExecutionPolicy Bypass -File scripts\stop_all_local.ps1
powershell -ExecutionPolicy Bypass -File scripts\prepare_demo.ps1
powershell -ExecutionPolicy Bypass -File scripts\backup_data.ps1
powershell -ExecutionPolicy Bypass -File scripts\restore_data.ps1 -BackupZip e:\Zhan\backups\mvp_cc_data_YYYYMMDD_HHMMSS.zip
powershell -ExecutionPolicy Bypass -File scripts\clean_workspace.ps1
python scripts\local_stack.py status
python scripts\demo_seed.py
python scripts\oidc_smoke.py --base-url http://localhost:8080
python scripts\load_test.py --base-url http://localhost:8080 --profile baseline_100_100
python scripts\track7_check.py --namespace mvp-cc --report-dir .artifacts\track7\<timestamp>
python scripts\postgres_dev_preflight.py --env-file .env.postgres.local.template
python scripts\postgres_dev_preflight.py --env-file .env.postgres.local.template --base-url http://127.0.0.1:8080
python scripts\live_smoke_gate12.py
python scripts\live_smoke_gate12.py --database-url postgresql://mvp:mvp@localhost:5432/mvpcc
python scripts\track9_preflight.py --base-url http://127.0.0.1:8080 --check-sftp
powershell -ExecutionPolicy Bypass -File scripts\start_track9_qa.ps1
python scripts\asterisk_lab_smoke.py --base-url http://127.0.0.1:8080 --database-url <database-url>
python scripts\track9_check.py --base-url http://127.0.0.1:8080 --database-url <database-url> --require-recording
python scripts\track9_collect_evidence.py --base-url http://127.0.0.1:8080 --database-url <database-url> --run-checks --require-recording
powershell -ExecutionPolicy Bypass -File scripts\track9_2_cutover.ps1 -KubeContext <context> -Namespace <namespace> -Release <release> -GatewayBaseUrl http://<gateway-host> -DatabaseUrl postgresql://<...> -ImageTag <image-tag> -AmiHost <asterisk-host> -AmiUser <ami-user> -AmiSecret <ami-secret> -SftpHost <asterisk-host> -SftpUser <sftp-user> -SftpPassword <sftp-password> -QueueId <queue-id> -AppTokenSecret <app-token-secret>
python scripts\gate3_check.py --auto-start
python scripts\gate4_check.py
python scripts\uat_preflight.py --auto-start
python scripts\uat_dry_run.py --auto-start --update-defect-register
python scripts\uat_manual_prepare.py --environment-url http://<pilot-gateway>:8080
python scripts\finalize_mvp_pilot.py --session-dir docs/uat/evidence/manual_<session-id> --dry-run
python scripts\finalize_mvp_pilot.py --session-dir docs/uat/evidence/manual_<session-id>
```

## Demo-ready local run

Use one command to start the stack, run smoke checks, and preload demo data:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\prepare_demo.ps1
```

This starts every service in the background without opening extra PowerShell windows, writes logs to `.local_stack\logs`, and seeds:

- a demo customer
- a closed escalated voice interaction
- an active follow-up interaction
- voice + Telegram integration events
- one `recording.ready` event imported into managed storage
- one IVR flow with a completed demo session and route preview
- KB demo article
- supervisor snapshot
- KPI sample rows

Stop the stack with:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\stop_all_local.ps1
```

Local runtime state under `.data*`, `.local_stack`, and `.artifacts` is disposable.
To reset the local workspace back to a clean baseline, run:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\clean_workspace.ps1
```

Relevant PostgreSQL cutover runbooks:

- [local-run.md](/e:/Zhan/docs/runbooks/local-run.md)
- [postgres-dev-cutover.md](/e:/Zhan/docs/runbooks/postgres-dev-cutover.md)
- [postgres-server-docker.md](/e:/Zhan/docs/runbooks/postgres-server-docker.md)
- [postgres-server-parallel-stack.md](/e:/Zhan/docs/runbooks/postgres-server-parallel-stack.md)
- [deployment-onprem.md](/e:/Zhan/docs/runbooks/deployment-onprem.md)

## Wave 2 enterprise auth baseline (Track 1)

Track 1 introduces signed application bearer tokens and optional Keycloak-backed OIDC login.

Default local/demo mode:

- `OIDC_ENABLED=0`
- `ALLOW_LEGACY_HEADER_AUTH=1`

Enterprise-shaped mode:

- `OIDC_ENABLED=1`
- `ALLOW_LEGACY_HEADER_AUTH=0`
- set `APP_TOKEN_SECRET`
- set `OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_REDIRECT_URI`

Quick checks:

```powershell
python scripts\migrate_core_db.py
python scripts\oidc_smoke.py --base-url http://localhost:8080
python scripts\oidc_smoke.py --base-url http://localhost:8080 --require-enabled
```

Detailed rollout guidance:

- `docs/runbooks/keycloak-oidc.md`
- `docs/runbooks/deployment-onprem.md`

## Wave 2 Track 3 dedicated shells

Track 3 starts moving critical workflows out of the single operator shell:

- `/supervisor` for realtime, KPI, agent status, and queue snapshot controls
- `/admin` for users, queues, and routing previews

## Wave 2 Track 4 recordings

Track 4 introduces the first voice recording lifecycle:

- `recording-service` stores metadata for voice recordings
- audio files are copied into managed local storage
- `/supervisor` can import, preview, download, and archive recordings

Operational runbook:

- `docs/runbooks/recordings-local.md`

## Wave 2 Track 5 IVR

Track 5 introduces the first IVR runtime for voice:

- `ivr-service` stores IVR flow configs and runtime sessions
- DTMF steps can complete a session into an `ivr.completed` event
- `/admin` can create flows, start sessions, send digits, and preview routing with `ivr_session_id`

Operational runbook:

- `docs/runbooks/ivr-local.md`

## Wave 2 Track 6 KPI Expansion

Track 6 expands reporting beyond the MVP core subset:

- `reporting-service` now stores `channel` and `agent_id`
- `/reports/kpi` adds expanded metrics and channel breakdowns
- `/reports/coverage` exposes the implemented KPI catalog

Reference:

- `docs/kpi/definitions.md`

## Wave 2 Track 7 Scale-Up and Hardening

Track 7 adds the first production-shaped scale profile:

- Helm is now the canonical path for K8s scale validation
- `DATABASE_URL` is required for the `scale500` profile
- runtime DB pooling is configurable with:
  - `DB_POOL_SIZE`
  - `DB_MAX_OVERFLOW`
  - `DB_POOL_TIMEOUT_SECONDS`
  - `DB_POOL_RECYCLE_SECONDS`
- `scripts/load_test.py` now runs mixed load profiles and writes evidence to `.artifacts/track7/*`
- `scripts/track7_check.py` validates the load report plus K8s pod/HPA health

Operational runbook:

- `docs/runbooks/track7-scale-validation.md`

## Wave 2 Track 8 Event Bus

Track 8 adds the first asynchronous integration backbone:

- `event_outbox` / `event_inbox` tables for reliable publication and idempotent consumption
- `event-bus-service` for outbox dispatch and operational retry
- RabbitMQ as the first canonical message bus
- first consumers:
  - `audit-service`
  - `reporting-service`

Operational runbook:

- `docs/runbooks/event-bus-local.md`

## Wave 2 Track 9 Asterisk Lab Integration

Track 9 adds the first real telephony bridge toward Asterisk:

- `asterisk-bridge-service` listens to AMI `UserEvent` messages with the `MVPCC` prefix
- Asterisk `QueueCode` values are mapped to platform `queue_id` values through config
- `MVPCCCallStarted` creates a real `voice` interaction and forwards `call.started`
- `MVPCCCallEnded` forwards `call.ended` and keeps the interaction linked
- `MVPCCRecordingReady` can fetch a recording from a Linux VM over `SFTP` and upload it into `recording-service`
- bridge internal auth mode is configurable:
  - `ASTERISK_BRIDGE_AUTH_MODE=legacy_headers` (Track 9 QA baseline)
  - `ASTERISK_BRIDGE_AUTH_MODE=bearer_first|bearer` (Track 9.1 hardening)
- strict service-token hardening adds subject allowlists:
  - `VOICE_ADAPTER_TRUSTED_SERVICE_SUBJECTS`
  - `RECORDING_IMPORT_TRUSTED_SERVICE_SUBJECTS`
  - `RECORDING_IMPORT_ALLOW_ADMIN=0` in strict mode

Repository assets for the Linux VM lab:

- `deployment/asterisk/pjsip.conf`
- `deployment/asterisk/extensions.conf`
- `deployment/asterisk/manager.conf`

Operational runbook:

- `docs/runbooks/asterisk-lab-linux-vm.md`
- `docs/runbooks/.env.production.checklist.md`
- `deployment/helm/values.track9-strict.yaml` (strict bridge auth overlay)
- `docs/runbooks/track9-2-production-cutover.md` (controlled production cutover)

Track 9 QA config artifacts:

- `.env.production.template`
- `docs/acceptance/track9/track9-acceptance.md`

## Wave 2 Track 11 Live Operator Voice Control

Track 11 extends the Asterisk bridge with operator call control:

- new bridge routes:
  - `/asterisk/live-calls`
  - `/asterisk/live-calls/{call_id}/claim`
  - `/asterisk/live-calls/{call_id}/hangup`
  - `/asterisk/live-calls/{call_id}/blind-transfer`
  - `/asterisk/live-calls/{call_id}/actions`
- operator shell gets a `Живые звонки` block with claim/hangup/blind-transfer controls
- own-call RBAC guard for operator role
- additive voice events:
  - `call.connected`
  - `call.transferred`

Runbook and acceptance templates:

- `docs/runbooks/track11-live-operator-call-control.md`
- `docs/acceptance/track11/README.md`
- `docs/acceptance/track11/track11-acceptance.template.md`

## PostgreSQL run (docker-compose)

```bash
cd deployment
docker compose up -d postgres
cd ..
python scripts/migrate_core_db.py
```

## Shared Docker host PostgreSQL for call-center

When the server already hosts other Docker projects and the running `call-center` stack is still SQLite-backed, use the isolated server-side PostgreSQL asset instead of reusing an existing database:

- compose: `deployment/docker-compose.postgres.server.yml`
- template: `.env.postgres.server.template`
- runbook: `docs/runbooks/postgres-server-docker.md`

To bring up a second PostgreSQL-backed application stack in parallel on the same host:

- compose: `deployment/docker-compose.parallel.server.yml`
- template: `.env.postgres.parallel.server.template`
- runbook: `docs/runbooks/postgres-server-parallel-stack.md`

## Stage-by-stage execution

- Stage 1: see `docs/roadmap/01-foundation.md`
- Stage 2: see `docs/roadmap/02-operator-core.md`
- Stage 3: see `docs/roadmap/03-supervisor-reporting-kb.md`
- Stage 4: see `docs/roadmap/04-pilot-hardening.md`

Every stage has a gate checklist in `docs/gates`.