diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b416775..b92f3ee 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,8 +1,9 @@ # Архитектура — Академический помощник Каноничное описание системы. Обновляется вместе с кодом; при расхождении верить -коду, а не этому файлу. Смежные документы: [DR-HA.md](DR-HA.md) (отказоустойчивость), -[../README.md](../README.md) (быстрый старт и команды). +коду, а не этому файлу. Визуальная схема — [DIAGRAM.md](DIAGRAM.md). Смежные +документы: [DR-HA.md](DR-HA.md) (отказоустойчивость), [INGESTION.md](INGESTION.md) +(наполнение корпуса), [../README.md](../README.md) (быстрый старт и команды). ## 1. Назначение diff --git a/docs/DIAGRAM.md b/docs/DIAGRAM.md new file mode 100644 index 0000000..17af2e5 --- /dev/null +++ b/docs/DIAGRAM.md @@ -0,0 +1,108 @@ +# Схема системы + +Визуальная схема к [ARCHITECTURE.md](ARCHITECTURE.md) (там — полное текстовое описание). + +## Компоненты и потоки данных + +```mermaid +flowchart TB + subgraph client["Клиент"] + FE["Frontend (React SPA)
CT 102, nginx"] + end + + subgraph app["App-хост 1.32"] + API["API (FastAPI)
JWT · rate-limit · /metrics"] + MQ[("RabbitMQ .82
брокер Celery")] + + subgraph workers["Celery-воркеры"] + IDX["worker-indexer
L1 Winnowing · L2 MinHash
PDF/DOCX · парсеры"] + GPU["worker-gpu
L3 семантика · L4 LLM
эмбеддинги"] + GOST["worker-gost
ГОСТ 7.1 / 7.0.5"] + NOTIFY["worker-notifier
SMTP email"] + end + + ES[("Elasticsearch
BM25, local")] + VEC{{"Векторный бэкенд
VECTOR_BACKEND"}} + FAISS["FAISS
(файл, дефолт)"] + QDR["Qdrant
(опционально)"] + end + + subgraph shared["Общая инфраструктура"] + PG[("PostgreSQL 1.38
users/tasks/documents/
fingerprints/...")] + REDIS[("Redis 1.35
кэш · rate-limit · LSH-индекс")] + MINIO[("MinIO 1.21
документы · full-text · бэкапы")] + OLLAMA["Ollama .163
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`, по умолчанию выключены.