docs: визуальная схема системы (Mermaid) — docs/DIAGRAM.md

Диаграмма компонентов и потоков данных (frontend/API/очереди/воркеры/общая инфра/опциональные Qdrant и Prometheus-Grafana) + sequence-диаграмма конвейера проверки плагиата L1-L4. Дополняет текстовое ARCHITECTURE.md, на который ссылается. ARCHITECTURE.md теперь ссылается на DIAGRAM.md и INGESTION.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-24 13:47:45 +05:00
parent 6099ef621f
commit ea5c3a962c
2 changed files with 111 additions and 2 deletions
--- a/docs/DIAGRAM.md
+++ b/docs/DIAGRAM.md
@@ -0,0 +1,108 @@
+# Схема системы
+
+Визуальная схема к [ARCHITECTURE.md](ARCHITECTURE.md) (там — полное текстовое описание).
+
+## Компоненты и потоки данных
+
+```mermaid
+flowchart TB
+    subgraph client["Клиент"]
+        FE["Frontend (React SPA)<br/>CT 102, nginx"]
+    end
+
+    subgraph app["App-хост 1.32"]
+        API["API (FastAPI)<br/>JWT · rate-limit · /metrics"]
+        MQ[("RabbitMQ .82<br/>брокер Celery")]
+
+        subgraph workers["Celery-воркеры"]
+            IDX["worker-indexer<br/>L1 Winnowing · L2 MinHash<br/>PDF/DOCX · парсеры"]
+            GPU["worker-gpu<br/>L3 семантика · L4 LLM<br/>эмбеддинги"]
+            GOST["worker-gost<br/>ГОСТ 7.1 / 7.0.5"]
+            NOTIFY["worker-notifier<br/>SMTP email"]
+        end
+
+        ES[("Elasticsearch<br/>BM25, local")]
+        VEC{{"Векторный бэкенд<br/>VECTOR_BACKEND"}}
+        FAISS["FAISS<br/>(файл, дефолт)"]
+        QDR["Qdrant<br/>(опционально)"]
+    end
+
+    subgraph shared["Общая инфраструктура"]
+        PG[("PostgreSQL 1.38<br/>users/tasks/documents/<br/>fingerprints/...")]
+        REDIS[("Redis 1.35<br/>кэш · rate-limit · LSH-индекс")]
+        MINIO[("MinIO 1.21<br/>документы · full-text · бэкапы")]
+        OLLAMA["Ollama .163<br/>qwen2.5:7b"]
+    end
+
+    subgraph obs["Опционально (профили compose)"]
+        PROM["Prometheus"]
+        GRAF["Grafana"]
+    end
+
+    FE -->|"HTTPS /api, /ws"| API
+    API -->|"send_task"| MQ
+    API <-->|"users/tasks"| PG
+    API <-->|"session/rate-limit"| REDIS
+
+    MQ -->|"queue.index"| IDX
+    MQ -->|"queue.gpu"| GPU
+    MQ -->|"queue.gost"| GOST
+    MQ -->|"queue.notify"| NOTIFY
+
+    IDX <-->|"documents/fingerprints"| PG
+    IDX <-->|"MinHash LSH (antiplag_lsh)"| REDIS
+    IDX <-->|"PDF/full-text"| MINIO
+    IDX --> ES
+    IDX -->|"gpu.embed_documents"| MQ
+
+    GPU <-->|"documents"| PG
+    GPU --> VEC
+    VEC --> FAISS
+    VEC -.->|"переключение флагом"| QDR
+    GPU -->|"L4 парафраз"| OLLAMA
+    GPU --> ES
+
+    GOST <-->|"documents"| PG
+    NOTIFY <-->|"tasks"| PG
+    NOTIFY -->|"email"| SMTP(["jze9mail.ru"])
+
+    API -->|"/metrics"| PROM
+    PROM --> GRAF
+
+    style VEC fill:#00000000,stroke-dasharray: 4 3
+    style obs fill:#00000000,stroke-dasharray: 4 3
+```
+
+## Конвейер проверки плагиата (4 уровня)
+
+```mermaid
+sequenceDiagram
+    participant U as Студент
+    participant API as API
+    participant IDX as worker-indexer
+    participant GPU as worker-gpu
+    participant LLM as Ollama
+
+    U->>API: upload файла
+    API->>API: сохранить в MinIO, создать Task, commit
+    API->>IDX: index.extract_and_check
+    IDX->>IDX: извлечь текст → фрагменты
+    IDX->>IDX: L1 Winnowing (fingerprints)
+    IDX->>IDX: L2 MinHash LSH (Redis)
+    IDX->>GPU: gpu.check_plagiarism (частичные совпадения)
+    loop по подозрительным фрагментам
+        GPU->>GPU: L3 семантический поиск (FAISS/Qdrant)
+        GPU->>LLM: L4 check_paraphrase
+        LLM-->>GPU: is_paraphrase, confidence
+    end
+    GPU->>GPU: app.scoring.aggregate_results (итоговый %)
+    GPU->>API: результат → Task.result
+    GPU-->>U: notify.send_task_done → email/WebSocket
+```
+
+## Легенда
+
+- Сплошные стрелки — прямые вызовы/запросы; пунктир у `VEC` — переключение бэкенда
+  по настройке `VECTOR_BACKEND`, не одновременная работа обоих.
+- `obs` (Prometheus/Grafana) и `Qdrant` — опциональны, поднимаются под
+  `docker compose --profile qdrant|observability`, по умолчанию выключены.