EvoBGP/docs/architecture.md

Архитектура EvoBGP

Высокоуровневое описание компонентов и потоков. Детальный продуктовый и инфраструктурный чертёж также зафиксирован во внутреннем плане репозитория: .cursor/plans/evobgp_архитектура_0e73ef02.plan.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)

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)

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 — как поднять стек.
• api.md — точки входа HTTP.
• access.md — ключи и роли.