diff --git a/README.md b/README.md
index f80552d..880aaa0 100644
--- a/README.md
+++ b/README.md
@@ -7,13 +7,37 @@
 Разбирать спецификации договоров и допников (docx/pdf) в структурированный вид,
 отслеживать изменения между версиями, восстанавливать историю договора во времени.
 
-## Состав
+## Архитектура
+
+Подробное описание архитектуры (компоненты, БД, event sourcing, загрузка через
+ВМ-буфер, ZIP, конвейер сравнения) — см. **[`DOC/architecture-contracts-flask.md`](DOC/architecture-contracts-flask.md)**.
+
+Ключевые моменты:
+
+- **Основной сервис** — `contracts-flask/` (Flask + SQLite WAL, managed на Nubes).
+- **Загрузка** — браузер PUT файла в ВМ-буфер (WebDAV), бэк сам тянет с ВМ
+  (managed-gateway рвёт тела > 64 КБ, egress ВМ без лимита).
+- **ZIP** — раскрывается на клиенте (`expandZipClient` → `listZipFiles`).
+- **Event sourcing** — `spec_events` (журнал) + `spec_current` (текущее состояние).
+- **Сравнение** — `/process-v2` (SSE): LLM возвращает ops (ADD/UPDATE/DELETE/
+  UNRESOLVED), применяются через `apply_ops()`.
+- **LLM** — только своя модель `gpt-oss-120b` (api.aillm.ru).
+
+## Состав репозитория
 
 | Папка | Что |
 |---|---|
-| `contracts-app/` | Flask-сервис (основной код) |
+| `contracts-flask/` | Основной сервис (Flask + SQLite, managed на Nubes) |
+| `contractor-legacy/` | Старый Lucee/CFML-сервис (архив) |
+| `convert-service/` | Микросервис конвертации doc → docx |
+| `DOC/` | Документация: архитектура, тестирование |
+| `History/` | История решений, ревью, протоколы |
+| `FILES/` | Заметки, ключи LLM, ТЗ |
 | `dogovora/` | Примеры договоров и допников |
-| `FILES/` | Заметки, ключи LLM |
+| `loadtest/` | Нагрузочное тестирование |
+| `sim/` | Симуляция сценариев |
+| `testgen/` | Генерация тестовых кейсов |
+| `hz/` | Разные заметки |
 
 ## Конфиденциальность