Контракт-чек — Production Architecture

Контракт-чек — Production Architecture An architecture diagram generated by Archify. Telegram User · chat client · Architecture component Telegram User chat client Web User · browser / SPA · Architecture component Web User browser / SPA B2B Client · X-API-Key · Architecture component B2B Client X-API-Key Admin · /admin panel · Architecture component Admin /admin panel Telegram Bot · aiogram · HTTP-only · Single VPS · Docker Compose · adapter Telegram Bot aiogram · HTTP-only adapter Web UI · future SPA · SSE · Single VPS · Docker Compose · adapter (planned) Web UI future SPA · SSE adapter (planned) Nginx + certbot · TLS edge · reverse proxy · Single VPS · Docker Compose · edge layer Nginx + certbot TLS edge · reverse proxy edge layer API · FastAPI · /api/v1 · /admin · Single VPS · Docker Compose › core domain · contract_check.core · core · sole writer API FastAPI · /api/v1 · /admin core · sole writer Redis · rate limit · sessions · Single VPS · Docker Compose › infra · stateful · future Redis rate limit · sessions future RabbitMQ · contracts.x · quorum · DLQ · Single VPS · Docker Compose › infra · stateful · direct exchange RabbitMQ contracts.x · quorum · DLQ direct exchange worker-extract · pymupdf · mammoth · tesseract · Single VPS · Docker Compose › core domain · contract_check.core · CPU image worker-extract pymupdf · mammoth · tesseract CPU image worker-prescreen · heuristic → LLM fallback · router · Single VPS · Docker Compose › core domain · contract_check.core · CPU image worker-prescreen heuristic → LLM fallback · router CPU image worker-analyze · LLM provider · repair loop · Single VPS · Docker Compose › core domain · contract_check.core · I/O image worker-analyze LLM provider · repair loop I/O image worker-billing · renewals · expiry · reconcile · Single VPS · Docker Compose › core domain · contract_check.core · scheduler · 60s tick worker-billing renewals · expiry · reconcile scheduler · 60s tick worker-notify · aiosmtplib · password reset · Single VPS · Docker Compose › core domain · contract_check.core · email worker-notify aiosmtplib · password reset email LLM Provider · Ollama Cloud · YandexGPT · Architecture component · provider port LLM Provider Ollama Cloud · YandexGPT provider port PostgreSQL · source of truth · WAL archive · Single VPS · Docker Compose › infra · stateful · replication-ready PostgreSQL source of truth · WAL archive replication-ready MinIO · raw docs + extracted text · TTL · Single VPS · Docker Compose › infra · stateful · S3 API MinIO raw docs + extracted text · TTL S3 API ЮKassa · payments · webhooks · Architecture component · billing port ЮKassa payments · webhooks billing port SMTP · email delivery · Architecture component · notify transport SMTP email delivery notify transport Telegram updates HTTPS X-API-Key admin cookie HTTP → :443 HTTPS → :443 proxy :443 → :8000 publish DocumentUploaded rate limit · sessions users · documents · invoices upload raw doc extract.q · prefetch=1 prescreen.q · prefetch=1 analyze.q · prefetch=3 notify.q PrescreenRequested AnalyzeRequested prescreen_results save Report · status=done read extracted text analyze(text, checklist) LLM fallback renewals · quota · ledger payment · refund · reconcile raw + .txt blobs send email webhook payment.succeeded create_payment · refund Single VPS · Docker Compose core domain · contract_check.core infra · stateful Legend Frontend Backend Database Security Message bus External

Hexagonal boundary

  • • Telegram bot and web UI are thin HTTP adapters — they never import core.db / s3 / llm / mq
  • • Nginx is a separate TLS edge layer: all adapter traffic flows through it to the API
  • • API is the sole writer for user mutations; workers own their stage rows only
  • • Enforced by tests/unit/test_bot_boundary.py (static AST)

Screening pipeline

  • • PDF/DOCX/RTF/CSV/images → text → prescreen (hybrid heuristic + LLM fallback) → LLM analysis → markdown report
  • • Quorum queues with TTL retry, exponential backoff, and DLQ; refund_credit on terminal failure
  • • Fine-grained status: queued → extracting → prescreening → ocr → analyzing → done | failed

Billing & credits

  • • Reserve-on-enqueue invariant: credit moves on POST /documents, never in a worker
  • • ЮKassa webhook-driven invoice state machine; worker-billing handles renewals, expiry, reconciliation
  • • Quota (subscription) consumed before Credits; refund policy D10 with clawback and billing_hold

Auth surfaces

  • • User JWT for bot/web/Mini App; service token for adapter-level; X-API-Key for B2B
  • • Passwordless: passkeys (WebAuthn) + magic links; email/password JWT pair with refresh in Redis
  • • /admin panel uses HttpOnly cookie + users.role = admin