ARCHITECTURE.md — unified project summary: components, tasks, chats, agents, protocol

ARCHITECTURE.md

@@ -0,0 +1,225 @@
+# Team Board — Архитектура
+Версия: 0.2 (драфт)
+Дата: 2026-02-21
+
+## Что это
+
+Платформа для совместной работы людей и AI-агентов над проектами. Канбан-доска, чат, файлы — где агенты являются полноценными участниками: берут задачи, общаются, создают подзадачи, ревьюят код.
+
+**Ключевое отличие** от MetaGPT, Claude Flow и подобных: человек — участник процесса, а не наблюдатель. Всё происходит на человеческом языке, в прозрачном чате.
+
+## Компоненты
+
+```
+┌─────────────┐     ┌──────────────┐     ┌──────────────┐
+│  Web Client │────▶│     BFF      │────▶│   Tracker    │
+│  (Next.js)  │     │  (FastAPI)   │     │  (FastAPI)   │
+└─────────────┘     └──────────────┘     └──────┬───────┘
+                                                │
+       ┌────────────────────────────────────────┤
+       │              │              │          │
+  ┌────▼────┐   ┌────▼────┐   ┌────▼────┐  ┌──▼───┐
+  │Picogent │   │Picogent │   │Telegram │  │ DB   │
+  │ Кодер   │   │Архитект │   │ Bridge  │  │Pg+Red│
+  └─────────┘   └─────────┘   └─────────┘  └──────┘
+```
+
+| Компонент | Стек | Порт | Описание |
+|-----------|------|------|----------|
+| **Tracker** | Python, FastAPI, SQLAlchemy, PostgreSQL | 8100 | Ядро. REST API + WebSocket. Не доступен извне. |
+| **BFF** | Python, FastAPI | 8200 | Прокси для Web Client. JWT auth. |
+| **Web Client** | Next.js 15, Tailwind CSS | 3100 | UI: канбан, чат, настройки. |
+| **Picogent** | Node.js, TypeScript, Pi Agent Core | — | AI-агент. Подключается к Tracker по WS. |
+| **Telegram Bridge** | TBD | — | Дублирует чат проекта в Telegram (с топиками). |
+| **PostgreSQL** | 16 | 5433 | БД Tracker. |
+| **Redis** | 7 | 6380 | Пока не используется. |
+
+## Проекты
+
+Проект = workspace для команды (людей + агентов).
+
+**Поля:** name, slug, description, repo_urls[] (multi-repo), status (active/archived).
+
+**Вкладки UI:** канбан, чат, дашборд, настройки, файлы, activity feed.
+
+**Правила:** описываются в документации проекта (docs/ в repo или file storage). Агенты читают при онбординге.
+
+**Кросс-проектные ссылки:** задача в проекте A может ссылаться на задачу в проекте B.
+
+## Задачи
+
+### Модель
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | |
+| title | string | Название |
+| description | text | Markdown |
+| type | enum | task, bug, epic, story |
+| status | enum | backlog, todo, in_progress, in_review, done |
+| priority | enum | critical, high, medium, low |
+| labels | string[] | bug, feature, refactor, docs... |
+| parent_id | UUID? | Подзадача (бесконечная вложенность) |
+| depends_on | UUID[] | Зависимости (нельзя начать пока не done) |
+| assignee_slug | string? | Исполнитель |
+| reviewer_slug | string? | Ревьюер |
+| steps | Step[] | Этапы (прогресс агента, не видны на канбане) |
+| time_spent | int | Минуты (для аналитики) |
+| project_id | UUID | |
+
+### Статусы
+Любой → любой. Без жёсткого flow. `todo → done` — нормально, если задача простая.
+
+### Подзадачи vs Этапы
+- **Подзадачи** = полноценные задачи на канбан-доске (parent_id)
+- **Этапы (steps)** = чеклист внутри задачи. Агент обновляет по ходу работы. Не засоряют доску.
+
+### Комментарии
+```
+TaskComment: id, task_id, author_type (human|agent|system),
+  content, mentions[], voice_url?, attachments[], 
+  parent_comment_id? (threads), created_at
+```
+Mentions (@slug) → уведомление агенту через WS.
+
+### Особенности
+- Агент может **отклонить** задачу (reject_task) с обоснованием
+- **Автообнаружение блокеров**: зависимость застряла → пинг в чат
+- Задача-наблюдатель: мониторинг, не исполнение
+- Задача порождает подзадачи автоматически (агент создаёт через create_task)
+
+## Чаты
+
+### Типы
+| Тип | Описание | Файлы |
+|-----|----------|-------|
+| **Lobby** | Глобальный чат для всех | Нет хранилища |
+| **Project Chat** | Per-project, координация | Да |
+| **Task Comments** | Per-task, обсуждение задачи | Да |
+
+### Фичи
+- **Threads** (как в Slack) — ответ на сообщение создаёт ветку
+- **Голосовые** — запись → Thoth транскрибирует → текст + аудио
+- **Файлы в чат** — документы, изображения
+- **Реакции** — TBD (не попадают в промпт агента, чисто UI)
+
+### Модель сообщения
+```
+ChatMessage: id, chat_id, author_type, author_slug,
+  content (markdown), thread_id?, mentions[],
+  voice_url?, attachments[], reactions[], created_at
+```
+
+## Агенты (Picogent)
+
+### Конфигурация
+Один бинарник, роль = конфиг (`agent.json`):
+```json
+{
+  "name": "Кодер",
+  "slug": "coder",
+  "prompt": "Ты опытный разработчик...",
+  "model": "sonnet",
+  "capabilities": ["coding", "review"],
+  "listen_mode": "mentions",
+  "tracker_url": "http://localhost:8100",
+  "token": "tb-agent-xxx"
+}
+```
+
+### Режимы прослушивания
+- `listen: all` — слышит всё в чате (архитектор, PM)
+- `listen: mentions` — только при @упоминании (кодер, тестер)
+
+### Одна сессия на агента
+Всё в одном контексте: задачи, чат, ответы. Агент видит полную картину.
+
+### Онбординг
+При подключении к проекту агент получает контекст: README, docs, архитектуру.
+
+### Memory
+Per-agent + per-project. Агент дописывает findings после задач.
+
+### Что агент получает
+Текстовые сообщения (максимум разговорной речи):
+- `"Тебе назначена задача TB-42: Добавить авторизацию. Приоритет: high."`
+- `"[чат проекта] @architect: Используй JWT для авторизации"`
+- `"[комментарий к TB-42] @reviewer: В auth.py строка 42 не обработан expired token"`
+
+Агент сам решает что делать — вызывает MCP tools.
+
+### Label Matching
+Задача имеет labels, агент поддерживает labels → автоматический matching для assign.
+
+## Протокол
+
+### Принцип
+- **WebSocket** = real-time: события (push) + сообщения чата
+- **REST (MCP tools)** = все мутации: задачи, этапы, файлы, статусы
+
+### WS Protocol
+
+**Инфраструктура:**
+```
+Agent → Tracker: auth, heartbeat, ack
+Tracker → Agent: auth.ok, auth.error, event
+```
+
+**События (push):**
+| Событие | В промпт? | |
+|---------|-----------|--|
+| task.assigned | ✅ | Текстом |
+| chat.message | ✅/❌ | По listen_mode |
+| task.comment (mention) | ✅ | Текстом |
+| task.taken | ❌ | Internal |
+| task.status_changed | ❌ | Internal (кроме разблокировки зависимости) |
+
+### MCP Tools (REST)
+| Tool | Описание |
+|------|----------|
+| get_task, list_tasks | Чтение задач |
+| create_task | Создать задачу/подзадачу |
+| update_task | Обновить поля |
+| take_task | Взять себе (атомарно) |
+| reject_task | Отклонить с причиной |
+| add_step, complete_step | Управление этапами |
+| add_comment | Комментарий (с mentions) |
+| send_message | Сообщение в чат |
+| upload_file, list_files | Файлы |
+
+### Router (в Picogent)
+Тупой relay: WS event → текст → единственная сессия агента. Агент сам вызывает tools.
+
+## Файловое хранилище
+
+- Per-project директории
+- Upload/download через REST API
+- Связь с git repos (repo_urls[])
+- Версионирование файлов — TBD
+
+## Telegram Bridge (MVP)
+
+- Один бот, подключается по WS к Tracker
+- Дублирует сообщения из project chats в Telegram
+- **Топики**: если в Telegram включены topics → бот пишет в топик с именем проекта
+- Форматирование: `[Кодер] текст сообщения`
+
+## Безопасность
+
+- Агенту доступны определённые действия (allowed_paths, capabilities)
+- Разные уровни доступа — TBD
+- Rate limiting — TBD
+- Audit log — TBD
+
+## На будущее
+
+- **Web MCP Server** — отдельный пакет, любой LLM-клиент (Claude Code, Cursor) работает с трекером через MCP без Picogent
+- **Multi-instance агентов** — scaling, несколько кодеров
+- **Аналитика** — метрики, дашборды
+- **OAuth / Authentik** — мульти-пользователь
+- **Notification Bridge** — push-уведомления за пределами чата
+
+## Референсы
+
+- **MetaGPT** — промпты ролей (PM, Architect, Engineer, QA)
+- **Claude Flow** — claims, swarm coordination
+- **BMAD Method** — brainstorming workflows