DrNick Agent v4 — Dev & Deploy

Overview #

Every change follows PLAN → PATCH → VERIFY (see DRNICK_RULES_FOR_CLAUDE.md). Hard rules that matter most here:

• user_id / tier come only from verified auth context — never from the request body.
• No verify=False on prod HTTP clients; compare secrets with hmac.compare_digest.
• The only path that moves money is POST /v1/chat/confirm — 2FA mandatory, every action.

Status (2026-06-08): M1–M5 + AdminPanel merged to main; remaining work is go-live only.

Architecture — 4 boundaries #

Every latent bug lives inside one of these or at a junction between them.

Runtime stack: FastAPI + Postgres (pgvector for RAG/memory) + Redis (pending confirm tokens) + OpenAI.

Local development #

Option A — Docker (full stack)

docker compose up            # api :8000 · db (pgvector) :5432 · redis :6379
docker compose exec api alembic upgrade head   # run migrations

Option B — host-run backend + FE proxy

# backend on :8088 with dev-header auth ON
DEV_AUTH_ENABLED=true \
DATABASE_URL=postgresql+psycopg://drnick:drnick@localhost:5432/drnick \
REDIS_URL=redis://localhost:6379/0 \
uvicorn app.main:app --reload --port 8088

# standalone FE (serves web/, proxies /v1 + /dev → backend)
python3 web/serve.py                       # http://localhost:5173 → 127.0.0.1:8088
DRNICK_BACKEND_PORT=8000 python3 web/serve.py   # point at the docker api instead

Quality gates

ruff check . && ruff format --check .   # lint + format
mypy app                                # types (strict)
pytest -q                               # tests (needs live PG+Redis; OpenAI for smoke)

Environment variables #

Dev defaults live in .env. Production template: .env.prod.example — keys marked CUTOVER are the Debt-F blockers and must change for prod.

Auth model #

Three independent mechanisms — pick by caller:

User & chat API #

All paths are under /v1. user auth = JWT or dev header.

{ "confirm_token": "…", "decision": "confirm",  // or "cancel"
  "code": "123456",          // TOTP — required to execute
  "codemail": null }         // optional email OTP (P4.4e)

SSE event format #

GET /v1/chat/stream emits these event types (in event: / data: SSE frames):

event: tool
data: {"name":"user_balance","status":"ok"}

event: token
data: {"delta":"Số dư "}

event: confirm
data: {"confirm_token":"…","summary":"Ủy thác 100 OFT…","summary_rows":[{"k":"Nhận dự kiến","v":"~35.65 USDT","gold":true}],"warning":"…"}

event: done
data: {"sources":[{"namespace":"kb:global","source_ref":"05_product_zeninvest.md"}]}

Admin API #

All under /v1/admin. Bearer ADMIN_TOKEN · 503 if unconfigured · 401 if wrong. Read endpoints don't touch the money path.

{ "postgres":{"status":"ok","kb_chunks":148,"namespace":"kb:global"},
  "redis":   {"status":"ok","pending_count":0},
  "onfa":    {"status":"down","error":"…"},          // down in dev (no PHP)
  "killswitch":{"enabled":false,"error":null} }       // note: {enabled}, not {status}

KB manager

OpenAPI / Swagger #

FastAPI auto-docs are enabled (the app is constructed without disabling them):

• /docs — Swagger UI (interactive)
• /redoc — ReDoc
• /openapi.json — machine-readable schema

Go-live (automated) #

scripts/go-live.sh drives the deploy-box steps end-to-end. Runs on the staging/prod host (it drives docker compose + the local app + /v1/admin/*).

# dry-run the whole pipeline first (changes nothing)
scripts/go-live.sh --target staging --env-file .env --base-url http://localhost:8000 --dry-run all

# real staging run, then prod
scripts/go-live.sh --target staging --env-file .env all
scripts/go-live.sh --target prod    --env-file /path/.env.prod all

Flags: --target staging|prod · --env-file · --base-url · --dry-run · --yes · --skip-build · --killswitch (suspend action tools during the deploy window).

Orphan cleanup helper

scripts/clear_kb_orphans.py auto-detects orphan source_refs via kb_service.list_kb (no hardcoded list) and deletes them from kb:global. Needed because index_kb only REPLACES files it re-globs — files moved out of the glob keep stale chunks.

docker compose exec -T api python /app/scripts/clear_kb_orphans.py --dry-run   # list
docker compose exec -T api python /app/scripts/clear_kb_orphans.py             # delete

Runsheet (manual reference) #

Canonical: docs/DEPLOY-RUNSHEET-2026-06-08.md + docs/tasks/04b-DEPLOY-RUNBOOK-kb-restructure.md. Order:

1. Readiness — CI green; ONFA Task-29 country claim live; prod RS256 public PEM available.
2. Merge → main + tag the release (APP_VERSION).
3. Debt-F .env cutover — set the CUTOVER vars from the secret manager.
4. Vendor React offline — already done (web/vendor/); no CDN at load.
5. Deploy + restart — restart clears the persona @lru_cache (the #1 trap; skip = persona edits invisible).
6. Re-index KB + clear orphans — see automation above.
7. Smoke — language (EN/VI/country), KB (ZenInvest≠Savings, withdrawal limits, USDO), widget, money path 2FA.

Rollback #

• Code: revert the merge + restart. country=None / no-directive degrades to English default — safe.
• KB: git checkout <anchor> -- documents/ → re-run reindex → clear new orphans. Or scripts/go-live.sh --target … rollback.
• Persona: restart picks up restored files.
• .env: keep the prior prod .env backed up before the cutover.

web/ layout #

The web/ tree is the standalone DrNick frontend — vanilla HTML/CSS + React-via-Babel (no build step), served static by serve.py (dev) or from the DrNick origin (prod).

Open this guide locally at http://localhost:5173/docs.html (FE proxy) or directly via the api origin.

Embedding the widget #

One line on any ONFA page. The loader drops a floating cross-origin iframe loaded from the DrNick origin (CSS/JS isolated; all /v1 calls same-origin → no host CORS).

<script src="https://drnick.onfa.io/loader.js"
        data-origin="https://drnick.onfa.io" defer></script>

postMessage bridge (origin-pinned, allowlist by construction):

• host → frame: { type:'drnick:theme', theme:'dark'|'light' } — re-skin to match host.
• frame → host: { type:'drnick:resize', state:'fab'|'panel' } — grow/shrink the iframe.
• auth: loader fetches /drnick/token (ONFA) → drnick:auth → widget sends Authorization: Bearer. The token never leaks up to the host.

Troubleshooting #