# CODEMAP

Карта кода для file ASR + diarization stack.

## Main Flow

- `src/webui/server.py`
  - HTTP upload handler для `/api/file-transcribe`
  - запускает in-process file job runner
  - инжектит NATS/meta config в `/whisper-diarization`
  - в режиме `WEBUI_PAGE_MODE=diagnostics` отдает `/status/` и `/status/api/diagnostics`

- `src/webui/diagnostics.py`
  - backend probes для voice-chat services, NATS, LinTO HTTP и diarization sidecar-ов
  - агрегирует `ok/degraded/fail`
  - запускает optional smoke checks при `smoke=1`

- `src/stt_whisper_to_nats.py`
  - live ASR bridge
  - file worker
  - orchestration ASR chunk loop
  - coarse diarization stage events
  - merge final ASR + diarization result

- `src/diarization.py`
  - HTTP client для `DIARIZATION_HTTP_URL`
  - serialization form fields
  - parsing final diarization JSON
  - friendly pipeline-not-ready errors

- `src/model_transport.py`
  - общий streaming HTTP CONNECT transport для LinTO и diarization multipart
  - isolated proxy session, cancellation cleanup и отсутствие direct fallback

- `src/pyannote_diarization_server.py`
  - pyannote sidecar runtime
  - `/healthz`
  - `/diarize`
  - Hugging Face gated-model startup checks
  - NATS progress publisher
  - hook bridge from `pyannote.audio` to `diar_*` subjects

- `src/sherpa_onnx_diarization_server.py`
  - real sherpa-onnx sidecar runtime
  - downloads/loads segmentation and embedding ONNX models
  - exposes the same `/healthz` and `/diarize` JSON contract as pyannote

- `src/sortformer_diarization_server.py`
  - real NVIDIA NeMo Sortformer sidecar runtime
  - windowed long-file handling for files beyond the model's practical context
  - exposes the same `/healthz` and `/diarize` JSON contract as pyannote

## Browser / UI

- `src/webui/static/index.html`
  - shared layout for `/whisper-trasncription`, `/whisper-diarization`, and case pages
  - status area
  - dedicated speaker-separation progress card

- `src/webui/static/app.js`
  - browser NATS subscriptions
  - upload flow
  - status log rendering
  - читает `requested_diarization` / `run_diarization` прямо из file state events и snapshot
  - live diarization progress card updates
  - final plain/speaker text rendering

- `src/webui/static/nats_ws_client.js`
  - lightweight NATS-over-WebSocket client для browser

- `src/webui/static/diagnostics.html` и `src/webui/static/diagnostics_app.js`
  - отдельная страница `/status/`
  - render grouped diagnostics JSON
  - browser-side NATS WebSocket check через `/ws`

- `src/webui/static/styles.css`
  - page styling
  - progress-card / progress-bar styles
  - diagnostics tables and status badges

## Shared Runtime Helpers

- `src/webui/file_mode.py`
  - `FileModeSettings`
  - NATS subject builders
  - file job storage
  - durable file state payload merge
  - audio normalization
  - chunking helpers
  - transcript builder

- `src/pyannote_healthcheck.py`
  - container health probe для pyannote sidecar

## Build / Packaging

- `docker/diarization-base/Dockerfile`
  - CUDA/PyTorch/TorchCodec base image
  - pyannote import smoke test

- `docker/diarization/Dockerfile`
  - thin runtime image for sidecar
  - healthcheck entrypoint

- `docker/sherpa-onnx/Dockerfile`
  - sherpa-onnx sidecar image

- `docker/sortformer/Dockerfile`
  - NeMo Sortformer sidecar image

- `docker/docker-compose.yml`
  - local composition for worker + pyannote sidecar
  - env parity for NATS + diarization progress

## Deploy Wiring

- `stack/stack.drs`
  - project-owned legacy CPU stack `py_faster_whisper`
  - `stt_whisper_to_nats`, `pyannote_diarization`, `sherpa_onnx_diarization`, `sortformer_diarization`
  - pyannote `DEVICE=cpu`; `PYANNOTE_HF_TOKEN` comes from a protected CI/CD variable
- `stack/otlp.drs`
  - shared logging, telemetry and network overlay applied before `stack/stack.drs`

- `../rag-stack/stack/llm-models.drs`
  - production env wiring
  - `stt_whisper_to_nats`
  - NATS progress prefixes and revision
- `../rag-stack/stack/diarization-models.drs`
  - `pyannote_diarization_shared`
  - `pyannote_diarization_isolated`
  - `sherpa_onnx_diarization`
  - `sortformer_diarization`

## Tests

- `tests/test_diarization.py`
  - diarization helpers
  - file worker progress publish tests
  - pyannote progress hook/publisher tests
  - diarization HTTP client tests

- `tests/test_pyannote_healthcheck.py`
  - healthcheck probe tests