Skip to content

Latest commit

 

History

History
185 lines (127 loc) · 3.27 KB

PLAYBOOK.md

File metadata and controls

185 lines (127 loc) · 3.27 KB

TPOT Analyzer Playbook

Operational workflow for day-to-day development and verification.

1) Backend

From tpot-analyzer/:

source .venv/bin/activate
python -m scripts.start_api_server

Health check:

curl http://localhost:5001/api/health

Expected:

{"service":"tpot-analyzer","status":"ok"}

2) Frontend

From tpot-analyzer/graph-explorer/:

npm install
npm run dev

Open:

  • http://localhost:5173

3) Deterministic Test Dataset (Optional)

From tpot-analyzer/:

python - <<'PY'
from pathlib import Path
from tests.fixtures.create_test_cache_db import create_test_cache_db

snapshot_dir = Path("data/test_mode")
snapshot_dir.mkdir(parents=True, exist_ok=True)
cache_db = snapshot_dir / "cache.db"
counts = create_test_cache_db(cache_db)
print(f"Created {cache_db} with rows: {counts.as_dict()}")
PY

Run backend against this dataset:

SNAPSHOT_DIR="$PWD/data/test_mode" \
CACHE_DB_PATH="$PWD/data/test_mode/cache.db" \
python -m scripts.start_api_server

4) Verification Commands

Interpreter + dependency contract (local):

make verify-louvain-contract
python3 -m scripts.verify_test_runner_contract
python3 -m scripts.verify_dev_onboarding

Backend smoke test suite (venv-enforced via Makefile):

make test-smoke

Backend API smoke:

.venv/bin/python -m pytest tests/test_api.py -q

Discovery endpoint smoke (requires backend running):

.venv/bin/python -m scripts.verify_discovery_endpoint

Frontend/backend route contract audit:

.venv/bin/python -m scripts.verify_api_contracts

API route/service regression bundle:

.venv/bin/python -m scripts.verify_api_services_tests

Firehose relay verifier (local mock endpoint):

.venv/bin/python scripts/verify_firehose_relay.py

Continuous firehose relay (spectator streams -> Indra endpoint):

.venv/bin/python scripts/relay_firehose_to_indra.py

Override endpoint if needed:

.venv/bin/python scripts/relay_firehose_to_indra.py \
  --endpoint-url http://localhost:7777/api/firehose/ingest

Frontend unit:

cd graph-explorer
npx vitest run

Frontend E2E (mock):

cd graph-explorer
npm run test:e2e:mock

Frontend E2E (real backend):

cd graph-explorer
npm run test:e2e:real

5) Logs and Diagnostics

  • API logs: tpot-analyzer/logs/api.log
  • Frontend log events: tpot-analyzer/logs/frontend.log
  • Vite logs (if started via dev script): tpot-analyzer/logs/vite.log

Useful helper:

.venv/bin/python -m scripts.tail_cluster_logs --help

6) Common Reset Steps

If backend is stuck on port 5001:

lsof -nP -iTCP:5001 -sTCP:LISTEN
kill <PID>

If frontend cache/state causes stale behavior:

# restart Vite server
cd graph-explorer
npm run dev

7) Docs Release Checklist

When shipping doc updates:

  1. Run docs hygiene verification:
python3 -m scripts.verify_docs_hygiene
  1. Update docs/index.md for new docs, moved docs, or superseded docs.
  2. Add a timestamped entry in docs/WORKLOG.md with file paths, line numbers, and verification command results.
  3. For historical docs under docs/tasks/ or docs/archive/, add or refresh modernization/historical notes when legacy commands are mentioned.