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

python -m pip install -r requirements.txt

2. Run tests

pytest -q

3. Apply DB migrations

python scripts/migrate_core_db.py

3. Start individual services (example)

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

4. Start local gateway

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

Operator UI is available at:

http://localhost:8080/operator

Additional dedicated Wave 2 shells:

http://localhost:8080/supervisor
http://localhost:8080/admin

5. Optional helper scripts (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 -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 -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 -ExecutionPolicy Bypass -File scripts\clean_workspace.ps1

Relevant PostgreSQL cutover runbooks:

• local-run.md
• postgres-dev-cutover.md
• postgres-server-docker.md
• postgres-server-parallel-stack.md
• 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:

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)

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.