docs/ARCHITECTURE-REVIEW.md

Architecture Review — Team Board

Дата: 2026-02-23

1. Соответствие PRD

4.1 Управление проектами ✅ ХОРОШО

• Архитектура: Полностью покрывает, модель Project с multi-repo поддержкой
• Код: Реализовано 100%, все API endpoints работают, UI компоненты созданы
• Расхождения: Нет

4.2 Управление задачами (Kanban) ⚠️ ЧАСТИЧНО

• Архитектура: Покрывает полностью, модель Task с подзадачами, зависимостями, watchers
• Код: Базовые CRUD есть, но отсутствуют специальные операции
• Расхождения:
  • ❌ POST /api/v1/tasks/{id}/take — не реализован (БФФ проксирует, но в трекере нет)
  • ❌ POST /api/v1/tasks/{id}/reject — не реализован
  • ❌ POST /api/v1/tasks/{id}/assign — не реализован
  • ❌ POST /api/v1/tasks/{id}/watch — не реализован
  • ✅ Базовые CRUD работают

4.3 Чат и коммуникация ✅ ХОРОШО

• Архитектура: Unified Message модель реализована корректно
• Код: Message с chat_id/task_id работает, WS chat.send функционирует
• Расхождения:
  • ⚠️ Голосовые сообщения (voice_url) — поле есть в модели, но API загрузки нет

4.4 AI агенты ⚠️ ПРОБЛЕМЫ

• Архитектура: Модель Member unified, AgentConfig детализирован
• Код: Модели реализованы, но проблемы с функциональностью
• Расхождения:
  • ❌ Agent management UI — полностью отсутствует
  • ❌ MCP Tools — не реализованы
  • ❌ Фильтрация WS событий по capabilities — упрощена: humans получают ВСЁ
  • ❌ REST API token auth для агентов — не работает (только WS auth)

4.5 Файлы и вложения ❌ НЕ РЕАЛИЗОВАНО

• Архитектура: Модель Attachment есть
• Код: Полностью отсутствует
• Расхождения:
  • ❌ POST /api/v1/messages/{id}/attachments — не реализован
  • ❌ GET /api/v1/attachments/{id} — не реализован
  • ❌ Хранение файлов — не реализовано

4.6 Аутентификация и авторизация ⚠️ ЧАСТИЧНО

• Архитектура: JWT + Token auth описаны корректно
• Код: JWT через BFF работает, agent WS auth работает
• Расхождения:
  • ❌ Token auth для REST API агентов — проверка не реализована
  • ✅ BFF JWT auth работает
  • ✅ WS token auth для агентов работает

4.7 WebSocket и реал-тайм ⚠️ ПРОБЛЕМЫ

• Архитектура: Подробно описан протокол, фильтрация событий
• Код: Базовые WS работают, но упрощённая архитектура
• Расхождения:
  • ❌ Task события (task.created/updated/assigned) — не транслируются
  • ⚠️ Упрощённая фильтрация: humans/bridges получают ВСЁ, agents — по подпискам
  • ✅ auth, heartbeat, chat.send, project.subscribe работают

4.8 Steps (этапы задач) ✅ ХОРОШО

• Архитектура: Корректно описаны как чеклист внутри задачи
• Код: Полная реализация: модель, API, UI в TaskModal
• Расхождения: Нет

2. Архитектурные проблемы

2.1 WebSocket: Один слот на slug — КРИТИЧЕСКАЯ ПРОБЛЕМА

Проблема: ConnectionManager.clients: dict[str, ConnectedClient] — один слот на slug.

# manager.py:15
self.clients: dict[str, ConnectedClient] = {}  # slug → client

Последствия:

• Множественные вкладки одного пользователя вытесняют друг друга
• Агент при переподключении теряет предыдущую сессию
• Race conditions при одновременных подключениях

Решение: dict[str, list[ConnectedClient]] или уникальные session_id.

2.2 Task Events не транслируются

Проблема: В коде есть broadcast_task_event, но никто её не вызывает.

# manager.py:47
async def broadcast_task_event(self, project_id: str, event_type: str, data: dict):

Последствия: Агенты не получают уведомления о создании/обновлении задач.

Решение: Интегрировать в REST API endpoints для задач.

2.3 REST API авторизация агентов не работает

Проблема: Токен проверяется только в WebSocket, REST API для агентов полностью открыт.

# BFF проксирует агентские операции, но агенты не могут ходить напрямую к Tracker

Последствия: Агенты не могут делать REST вызовы без BFF.

Решение: Добавить token auth middleware в Tracker REST API.

2.4 BFF on_behalf_of создаёт collision risk

Проблема: Bridge может зарегистрировать любой on_behalf_of slug, даже несуществующий.

# handler.py:88-95
if on_behalf_of and member.type == "bridge":
    # Если пользователь не найден, используется синтетический slug
    effective_slug = on_behalf_of

Последствия: Коллизии slug при подключении реального пользователя.

Решение: Строгая валидация on_behalf_of или префиксы для synthetic slugs.

2.5 Упрощённая фильтрация событий

Проблема: Humans/bridges получают ВСЕ события без фильтрации.

# manager.py:36
if client.member_type in ("human", "bridge"):
    await self.send_to(slug, {"type": "message.new", "data": message})
    continue

Последствия: Лишний трафик, невозможность настроить подписки для людей.

Решение: Единая логика фильтрации для всех типов участников.

3. Расхождения документация ↔ код

3.1 TRACKER-PROTOCOL.md vs реальный протокол

Документ описывает:

• task.created/updated/assigned события
• Детальную фильтрацию по listen_mode и capabilities
• REST API endpoints для task operations

Реальный код:

• Task события не отправляются
• Упрощённая фильтрация (humans получают всё)
• Task API endpoints отсутствуют

3.2 ARCHITECTURE.md vs WS manager

Документ описывает:

• Фильтрацию по capabilities и listen modes
• Отдельные подписки для humans

Реальный код:

• Capabilities не используются в фильтрации
• Humans получают всё без подписок

3.3 CONCEPTS.md vs Agent REST auth

Документ описывает:

• REST API с token авторизацией для агентов
• MCP Tools полный набор

Реальный код:

• REST API открыт для всех
• MCP Tools отсутствуют

3.4 PRD vs отсутствующие features

PRD объявляет реализованными:

• Agent management UI
• Attachments API
• Task special operations

Реальный код:

• Эти features полностью отсутствуют

4. Рекомендации

P0: Блокеры

P0.1 Исправить WebSocket collision

# manager.py
class ConnectionManager:
    def __init__(self):
        self.clients: dict[str, list[ConnectedClient]] = {}  # slug → clients[]
        self.sessions: dict[str, ConnectedClient] = {}       # session_id → client

Без этого: Система не работает корректно при multiple connections.

P0.2 Добавить REST token auth для агентов

# tracker/api/middleware.py
async def verify_agent_token(request: Request):
    auth = request.headers.get("Authorization")
    if auth and auth.startswith("Bearer "):
        token = auth[7:]
        # Проверить в БД Member.token

Без этого: Агенты не могут использовать API напрямую.

P0.3 Реализовать task events

# tracker/api/tasks.py после create/update/delete
await broadcast_task_event(task.project_id, "task.created", task_data)

Без этого: Агенты не видят изменения задач.

P1: Важно

P1.1 Реализовать task special operations

• POST /api/v1/tasks/{id}/take — атомарное взятие задачи
• POST /api/v1/tasks/{id}/reject — отклонение с причиной
• POST /api/v1/tasks/{id}/assign — назначение
• POST /api/v1/tasks/{id}/watch — подписка на задачу

Почему: Это ключевые операции для работы агентов с задачами.

P1.2 Создать Agent Management UI

• Страница /agents с списком агентов
• Создание агентов с генерацией токенов
• Просмотр статусов и capabilities

Почему: Без UI управление агентами невозможно.

P1.3 Унифицировать фильтрацию событий

async def should_receive_event(client: ConnectedClient, event_type: str, data: dict) -> bool:
    # Единая логика для всех типов участников
    # Проверка подписок, listen_mode, capabilities

Почему: Текущая архитектура не масштабируется.

P1.4 Исправить on_behalf_of логику

• Валидировать существование пользователя
• Использовать префиксы для synthetic slugs: web-{slug}
• Логировать все proxy подключения

Почему: Предотвращает коллизии и security issues.

P2: Хорошо бы

P2.1 Реализовать Attachments API

• POST /api/v1/messages/{id}/attachments — загрузка
• GET /api/attachments/{id} — скачивание
• Хранение на диске по storage_path

Почему: Команды часто работают с файлами.

P2.2 Добавить MCP Tools для агентов

• create_task, take_task, update_task
• send_message, list_messages
• watch_task, unwatch_task

Почему: Агентам нужны инструменты для работы.

P2.3 Улучшить monitoring

• Health check endpoints /health
• Метрики WebSocket connections
• Логирование всех WS событий с timestamps

Почему: Проще дебажить и мониторить продакшен.

5. Обновлённая архитектурная диаграмма

Текущая архитектура (как есть)

Web Client ——HTTP/JWT——→ BFF ——HTTP/Token——→ Tracker
    ↓                     ↑                       ↑
    WS/JWT————————————————┘                       │
                                                  │ WS/Token
Picogent Agent ———————————————————————————————————┘
(REST auth не работает)

ConnectionManager: dict[slug → client] ← ПРОБЛЕМА
Фильтрация: humans=ALL, agents=subscription ← УПРОЩЕНО  
Task events: НЕ ОТПРАВЛЯЮТСЯ ← ПРОБЛЕМА

Целевая архитектура (как должно быть)

Web Client ——HTTP/JWT——→ BFF ——HTTP/Token——→ Tracker
    ↓                     ↑                    ↑  ↑
    WS/JWT————————————————┘                    │  │ WS/Token
                                               │  │
Picogent Agent ————HTTP/Token—————————————————┘  │
           ├————————WS/Token————————————————————────┘
           └————————MCP Tools———————┘

ConnectionManager: 
  dict[slug → clients[]]     ← ФИКС
  dict[session_id → client]  ← ФИКС
  
Фильтрация: unified для всех типов ← УЛУЧШЕНИЕ
Task events: все операции транслируются ← ФИКС
Agent REST: token auth работает ← ФИКС

Компоненты как должны быть

Компонент	Порт	Протоколы	Изменения
Tracker	8100	HTTP+WS (token auth)	+ Task events, + Agent REST auth
BFF	8200	HTTP+WS (JWT auth)	+ on_behalf_of validation
Web Client	3100	HTTP+WS через BFF	+ Agent Management UI
Picogent	—	HTTP+WS к Tracker	+ MCP Tools

Протоколы взаимодействия

• Web ↔ BFF: JWT auth, WS proxy с session management
• BFF ↔ Tracker: Token auth, on_behalf_of для web users
• Agent ↔ Tracker: Token auth для HTTP и WS, unified
• Events: Task+Message события через WS с единой фильтрацией

---

Итог: Архитектура в целом правильная, но много критических недоработок в реализации. Основная проблема — WebSocket connection management и отсутствие task events. После фиксов P0 система будет работать корректно.