docs: update README to include information about the EvoBGP web interface, linking to quickstart and access documentation for setup and configuration.

2026-04-05 17:10:21 +07:00
parent 6a55f72ab3
commit 5d21f013cf
8 changed files with 602 additions and 0 deletions
@@ -0,0 +1,108 @@
+# Архитектура EvoBGP
+
+Высокоуровневое описание компонентов и потоков. Детальный продуктовый и инфраструктурный чертёж также зафиксирован во внутреннем плане репозитория: `.cursor/plans/evobgp_архитектура_0e73ef02.plan.md` (удобно для истории решений; пользовательская навигация — через этот раздел и [overview.md](overview.md)).
+
+## Назначение слоёв
+
+- **Control plane** — HTTP API, хранилище состояния (PostgreSQL), фоновые задачи (jobs), подпись артефактов (бандлы), observability.
+- **Data plane** — демон BIRD, локальные конфиги в `/etc/bird`, сокет управления `birdc`, агент `evobgp-agent` для наблюдения/сопутствующих действий.
+- **Edge интеграция** — CLI `evobgp-node` на машине спикера: получение бандла по API, проверка подписи, применение конфигурации.
+
+## Компоненты (бинарники `cmd/`)
+
+| Бинарник | Роль |
+|----------|------|
+| `evobgp-api` | Только HTTP API и связанная логика в одном процессе. |
+| `evobgp-all` | Режим одной VPS: тот же API + in-process запуск заглушек scheduler, ingest, render, deploy. |
+| `evobgp-scheduler` | Планировщик cron/интервалов модулей (в коде сейчас **stub**). |
+| `evobgp-ingest` | Воркеры загрузки внешних источников (CDN и т.д.) (**stub**). |
+| `evobgp-render` | Генерация артефактов BIRD из ревизий (**stub**). |
+| `evobgp-deploy` | Выкладка на спикеры / взаимодействие с BIRD на стороне деплоя (**stub**). |
+| `evobgp-node` | CLI реплики: `pull-bundle`, `verify-bundle`, `apply-bundle`. |
+| `evobgp-agent` | Локальный агент рядом с BIRD (например `watch` по сокету). |
+
+В Docker Compose профиль **reference** запускает отдельные контейнеры под `evobgp-api` и четыре воркера; профиль **microvps** использует один контейнер `evobgp-all`.
+
+## Пакеты `internal/` (сжатая карта)
+
+| Пакет | Назначение |
+|-------|------------|
+| `httpapi` | Маршруты REST, аутентификация, CORS, привязка к store и jobs. |
+| `store` | Абстракция бэкенда данных; реализации в памяти и через репозиторий. |
+| `repository` | Доступ к PostgreSQL, сущности и миграции на уровне приложения. |
+| `db` | Подключение к БД и применение миграций. |
+| `jobs` | Реестр и выполнение асинхронных задач, связанных с API. |
+| `bundle` | Упаковка и проверка бандлов для нод. |
+| `signing` | Криптографическая проверка подписей. |
+| `birdfmt` | Форматирование и фрагменты конфигурации BIRD, вызовы `birdc`. |
+| `birddeploy` | Логика применения конфигурации к BIRD (используется в цепочке деплоя). |
+| `config` | Переменные окружения `EVOBGP_*`. |
+| `observability` | Метрики Prometheus, HTTP middleware. |
+| `broker` | Заготовка под NATS/Redis (логирование подключения в воркерах). |
+
+## Диаграмма: эталонный Compose (reference)
+
+```mermaid
+flowchart LR
+  subgraph clients [Clients]
+    WebUI[Web_UI]
+    Operator[Operator_API_client]
+    NodeCLI[evobgp_node]
+  end
+  subgraph control [Control_plane]
+    API[evobgp_api]
+    Sched[evobgp_scheduler_stub]
+    Ingest[evobgp_ingest_stub]
+    Render[evobgp_render_stub]
+    Deploy[evobgp_deploy_stub]
+    PG[(PostgreSQL)]
+    NATS[NATS_JetStream]
+  end
+  subgraph data [Data_plane]
+    BIRD[BIRD2]
+    Agent[evobgp_agent]
+  end
+  WebUI --> API
+  Operator --> API
+  NodeCLI --> API
+  API --> PG
+  Sched --> NATS
+  Ingest --> NATS
+  Render --> NATS
+  Deploy --> NATS
+  Sched --> PG
+  Ingest --> PG
+  Render --> PG
+  Deploy --> PG
+  Agent --> BIRD
+```
+
+На практике воркеры **пока не выполняют** полноценную работу с очередью — они резервируют место в топологии и пишут в лог. API и БД уже обеспечивают основной сценарий разработки и тестов.
+
+## Диаграмма: microvps (`evobgp-all`)
+
+```mermaid
+flowchart LR
+  Client[HTTP_clients]
+  All[evobgp_all_process]
+  PG[(PostgreSQL)]
+  BIRD[BIRD2]
+  Client --> All
+  All --> PG
+  All --> BIRD
+```
+
+Внутри процесса `evobgp-all` горутины scheduler/ingest/render/deploy — те же **stub**, что и отдельные бинарники.
+
+## Поток: ревизия и бандл для ноды
+
+1. Оператор (роль `operator` или выше по политике) изменяет модули и запускает цепочку, приводящую к новой **ревизии** (часть шагов может быть асинхронной через jobs — см. OpenAPI).
+2. Control plane формирует **подписанный бандл** для пары спикер + ревизия.
+3. `evobgp-node pull-bundle` с ключом роли `node` запрашивает `GET /v1/speakers/{id}/revisions/latest` и затем `GET /v1/speakers/{id}/bundle/{revision_id}`.
+4. Локально выполняется проверка подписи (публичный ключ выдаётся при старте API) и применение к BIRD (`apply-bundle`).
+
+## Связанные документы
+
+- [quickstart.md](quickstart.md) — как поднять стек.
+- [api.md](api.md) — точки входа HTTP.
+- [access.md](access.md) — ключи и роли.