sdlc-hub/ARCHITECTURE.md

Архитектура

Хаб моста Jira: SQLite-зеркало задач AURORA/AWPCA, служебные заметки, очередь команд, HTTP API и MCP. Агент (jira-agent, виртуалка) опрашивает хаб, пишет в Jira и возвращает состояние; хаб Jira не вызывает.

Модули

Модуль	Ответственность	Зависит от
paths	каталог данных (JIRA_HUB_HOME), пути базы и backups/	stdlib
db	схема SQLite, миграции по schema_version (копия базы перед миграцией), connect	backup
settings	настройки (setting), токены, темп, перенос из config.example.json	db
mirror	зеркало задач и связей, apply_state, заметки, фильтры	db
commands	контракт типов команд, валидация, временные ключи, оценка, подтверждение по состоянию	mirror
queue	пакеты, выдача (claim), отчёты, отмена, повтор, автообновление	commands, mirror, settings, db
backup	копии файла базы, ротация	stdlib
api	HTTP-сервер, маршруты, авторизация по токенам, фоновый tick	queue, mirror, settings, backup, relay
relay	реле общей папки: поток в serve, файлы req/ → HTTP 127.0.0.1 → resp/; HTTP-обработчики о нём не знают	settings
client	HTTP-клиент хаба	db, paths, settings (только для from_home)
mcp_server	инструменты MCP по stdio	client
importer	разовый импорт CSV-пакета в заметки, сверка с зеркалом	mirror, settings
cli	init, serve, import, mcp, tokens	api, mcp_server, importer, settings, db, paths

Цепочки: api → queue → commands/mirror/settings → db; api → relay → settings; mcp_server → client → HTTP API; importer → mirror/settings.

Потоки данных

• Запись в Jira: клиент (mcp_server/интерфейс) → POST /batches → queue → агент claim → Jira → POST /agent/commands/{id}/result.
• Чтение Jira: команда refresh → агент → POST /agent/state → mirror.apply_state.
• Токены: агентский — только /agent/*, клиентский — остальное; MCP берёт клиентский токен из базы через HubClient.from_home.

Границы

• Зеркало пишет только mirror.apply_state по запросу агента (и заметки через PUT /issues/{key}/note); из очереди и API задач напрямую не правят.
• Хаб не знает пароль Jira и не обращается к Jira; init не переносит auth, base_url, verify_ssl, ca_bundle.
• queue не создаёт команд сам: повтор после failed — новый пакет. Выданная без отчёта команда довыдаётся при следующем claim (до 3 выдач, затем failed).
• mcp_server не импортирует queue/mirror/db напрямую и ходит только через client.
• commands, mirror, queue не знают про HTTP; HTTP живёт только в api, client и relay (реле — клиент своего же HTTP).

Открытые вопросы

• Просмотрщик на живых данных и правки из UI — отдельные change'и (viewer-live, viewer-edit).
• Автоподстройка темпа по фактам 429 не реализована: хаб только показывает их.
• Незакрытые SQLite-соединения и сокеты в ряде тестов (ResourceWarning при -W error::ResourceWarning).