docs/CONCEPTS.md

Team Board — Концепции системы (Source of Truth)

Версия: 1.0
Дата: 2026-02-23
Статус: Единая точка правды по всем концепциям Team Board

---

1. Архитектура

1.1 Общая схема

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│  Web Client │────▶│     BFF      │────▶│   Tracker    │
│  (Next.js)  │     │  (FastAPI)   │     │  (FastAPI)   │
└─────────────┘     └──────────────┘     └──────┬───────┘
                                                │
       ┌────────────────────────────────────────┤
       │              │              │          │
  ┌────▼────┐   ┌────▼────┐   ┌────▼────┐  ┌──▼───┐
  │Picogent │   │Picogent │   │Telegram │  │  DB  │
  │ Кодер   │   │Архитект │   │ Bridge  │  │  Pg  │
  └─────────┘   └─────────┘   └─────────┘  └──────┘

1.2 Компоненты и порты

Компонент	Технологии	Порт	Доступность	Описание
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: канбан, чат, настройки
PostgreSQL	PostgreSQL 16	5433	Внутренняя	База данных
Redis	Redis 7	6380	Внутренняя	Кеш (пока не используется)
Picogent	Node.js, TypeScript	—	Внутренняя	AI-агент процесс

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

• Web Client ↔ BFF: HTTPS REST API + WebSocket (JWT auth)
• BFF ↔ Tracker: HTTP REST API + WebSocket (Token auth)
• Агенты ↔ Tracker: HTTP REST API + WebSocket (Token auth)
• База данных: PostgreSQL connection pool через SQLAlchemy

---

2. Модели данных

2.1 Member (Участники)

Ключевой принцип: Агенты и люди — единая модель. Различие только в type и методе авторизации.

Member:
    id: UUID (PK)
    name: str                    # Отображаемое имя
    slug: str (UNIQUE)           # Уникальный идентификатор (a-z, 0-9, -)
    type: str                    # "human" | "agent"
    role: str                    # "owner" | "member" | "observer" | "bridge"
    auth_method: str             # "password" | "oauth" | "token"
    password_hash: str?          # Для людей
    token: str? (UNIQUE)         # Для агентов/bridges
    status: str                  # "online" | "offline" | "busy"
    avatar_url: str?
    created_at: timestamp
    updated_at: timestamp

2.2 AgentConfig (Конфигурация агентов)

AgentConfig:
    id: UUID (PK)
    member_id: UUID (FK → Member, UNIQUE)
    capabilities: str[]          # ["coding", "review", "testing"]
    chat_listen: str             # "all" | "mentions"
    task_listen: str             # "all" | "mentions" 
    prompt: str?                 # Системный промпт
    model: str?                  # LLM модель

2.3 Project (Проекты)

Project:
    id: UUID (PK)
    name: str                    # Отображаемое название
    slug: str (UNIQUE)           # Уникальный ID (для URLs)
    description: str?            # Описание (markdown)
    repo_urls: str[]             # Массив Git репозиториев
    status: str                  # "active" | "archived"
    task_counter: int            # Счётчик для генерации номеров задач
    created_at: timestamp
    updated_at: timestamp

2.4 Task (Задачи)

Task:
    id: UUID (PK)
    project_id: UUID (FK → Project)
    parent_id: UUID? (FK → Task)  # Подзадача
    number: int                   # Порядковый номер в проекте (1, 2, 3...)
    title: str                    # Название задачи
    description: str?             # Описание (markdown)
    type: str                     # "task" | "bug" | "epic" | "story"
    status: str                   # "backlog" | "todo" | "in_progress" | "in_review" | "done"
    priority: str                 # "critical" | "high" | "medium" | "low"
    labels: str[]                 # Массив лейблов ["backend", "urgent"]
    assignee_slug: str?           # Кому назначена (Member.slug)
    reviewer_slug: str?           # Кто ревьюит (Member.slug)
    watchers: str[]               # Наблюдатели (массив Member.slug)
    depends_on: UUID[]            # Зависимости от других задач
    position: int                 # Позиция в колонке канбана
    time_spent: int               # Потраченное время (минуты)
    created_at: timestamp
    updated_at: timestamp

Связи:

• Task.project → Project (многие к одному)
• Task.parent → Task (самоссылка для подзадач)
• Task.subtasks ← Task (обратная связь)

2.5 Step (Шаги задачи)

Step:
    id: UUID (PK)
    task_id: UUID (FK → Task)
    title: str                    # Описание шага
    done: bool                    # Выполнен ли
    position: int                 # Порядок в списке
    created_at: timestamp
    updated_at: timestamp

2.6 Chat (Чаты)

Chat:
    id: UUID (PK)
    project_id: UUID? (FK → Project)  # NULL для lobby
    kind: str                         # "lobby" | "project"
    created_at: timestamp
    updated_at: timestamp

Типы чатов:

• Lobby — глобальный чат (один на всю систему)
• Project — чат проекта (один на проект)

2.7 Message (Сообщения)

Unified Message: Одна модель для чат-сообщений И комментариев к задачам.

Message:
    id: UUID (PK)
    chat_id: UUID? (FK → Chat)    # Если сообщение в чате
    task_id: UUID? (FK → Task)    # Если комментарий к задаче
    parent_id: UUID? (FK → Message)  # Для threads в чатах
    author_type: str              # "human" | "agent" | "system"
    author_slug: str              # Member.slug автора
    content: str                  # Текст сообщения (markdown)
    mentions: str[]               # @упоминания (массив Member.slug)
    voice_url: str?               # URL голосового сообщения
    created_at: timestamp
    updated_at: timestamp

Ограничения: Ровно одно из chat_id или task_id должно быть заполнено.

2.8 Attachment (Вложения)

Attachment:
    id: UUID (PK)
    message_id: UUID (FK → Message)
    filename: str                 # Оригинальное имя файла
    mime_type: str?               # MIME тип
    size: int                     # Размер в байтах
    storage_path: str             # Путь к файлу на диске
    created_at: timestamp

---

3. Авторизация

3.1 Типы авторизации

Тип участника	Метод авторизации	Описание
human (Web UI)	JWT Token	Логин/пароль → JWT
human (MCP Client)	JWT Token	Логин/пароль → JWT (будущее)
agent	Bearer Token	Статический токен в agent.json
bridge	Bearer Token	Статический токен для мостов

3.2 JWT Tokens (для людей)

• Секрет: JWT_SECRET (environment variable)
• Алгоритм: HS256
• Payload: {"sub": member_id, "name": member_name, "exp": timestamp}
• Срок действия: 30 дней (настраивается)

3.3 Agent Tokens

• Формат: tb- + random string (32 символа)
• Хранение: Member.token (уникальное поле)
• Генерация: При создании агента через UI
• Отзыв: Через API POST /api/v1/members/{slug}/revoke-token

3.4 Роли и права

Роль	Описание	Права
owner	Владелец инстанса	Все права
member	Обычный участник	send_messages, create_tasks, update_tasks
observer	Наблюдатель	Только чтение
bridge	Мост в другую систему	send_messages

3.5 Процесс авторизации

Web Client:

1. POST /api/auth/login → JWT token
2. Сохранение в localStorage
3. Authorization: Bearer {jwt} в запросах
4. WebSocket: ?token={jwt} в query

Agent:

1. Статический токен из конфига
2. WS: {"type": "auth", "token": "tb-xxx"}
3. REST: Authorization: Bearer {token} (TODO: не реализовано)

---

4. WebSocket Protocol

4.1 Подключение

URL: ws://localhost:8100/ws (прямое) или wss://dev.team.uix.su/agent-ws (через nginx)

4.2 Сообщения: Клиент → Сервер

Тип	Формат	Описание
auth	{"type": "auth", "token": "..."}	Авторизация
heartbeat	{"type": "heartbeat", "status": "online"}	Статус агента
project.subscribe	{"type": "project.subscribe", "project_id": "uuid"}	Подписка на проект
project.unsubscribe	{"type": "project.unsubscribe", "project_id": "uuid"}	Отписка
chat.send	{"type": "chat.send", "chat_id": "uuid", "content": "text", "mentions": []}	Сообщение в чат
ack	{"type": "ack"}	Подтверждение получения

4.3 Сообщения: Сервер → Клиент

Тип	Описание	Данные
auth.ok	Успешная авторизация	{slug, lobby_chat_id, projects[], online[]}
auth.error	Ошибка авторизации	{message}
message.new	Новое сообщение	{id, chat_id, task_id, author_*, content, mentions, created_at}
agent.status	Изменение статуса агента	{slug, status}
task.created	Создана задача	{...TaskData} (TODO: не реализовано)
task.updated	Обновлена задача	{...TaskData} (TODO: не реализовано)
task.assigned	Задача назначена	{...TaskData} (TODO: не реализовано)

4.4 Фильтрация событий

События фильтруются на сервере по настройкам агента:

message.new:

• chat_listen: "all" — все сообщения в подписанных проектах
• chat_listen: "mentions" — только сообщения с @упоминанием

task. (будущее):*

• task_listen: "all" — все события задач в подписанных проектах
• task_listen: "mentions" — только задачи где агент assignee/reviewer/watcher

4.5 Auth Flow

1. WebSocket Connect
2. Client → {"type": "auth", "token": "tb-xxx"}
3. Server validates token & creates session
4. Server → {"type": "auth.ok", "data": {...}}
5. Client → {"type": "project.subscribe", "project_id": "uuid"} (для каждого проекта)
6. Start heartbeat loop (каждые 30 секунд)

4.6 Heartbeat

• Интервал: Каждые 30 секунд
• Timeout: 90 секунд без heartbeat → status=offline
• Формат: {"type": "heartbeat", "status": "online|busy|idle"}
• Реакция сервера: Обновление Member.status, уведомление agent.status

---

5. REST API

Base URL: http://localhost:8100/api/v1 (прямой) или https://dev.team.uix.su/agent-api/api/v1 (через nginx)

5.1 Projects

Метод	Путь	Описание	Параметры
GET	/projects	Список проектов	—
GET	/projects/{slug}	Проект по slug	—
POST	/projects	Создать проект	{name, slug, description?, repo_urls?}
PATCH	/projects/{slug}	Обновить проект	{name?, description?, repo_urls?, status?}
DELETE	/projects/{slug}	Удалить проект	—

5.2 Tasks

Метод	Путь	Описание	Параметры
GET	/tasks	Список задач	?project_id=X&status=Y&assignee=Z&label=W
GET	/tasks/{id}	Задача по ID	—
POST	/tasks?project_slug=X	Создать задачу	{title, description?, type?, status?, priority?, labels?, parent_id?, assignee_slug?, depends_on?}
PATCH	/tasks/{id}	Обновить задачу	{title?, description?, type?, status?, priority?, labels?, assignee_slug?, reviewer_slug?, position?}
DELETE	/tasks/{id}	Удалить задачу	—

Специальные операции с задачами:

Метод	Путь	Описание	Параметры
POST	/tasks/{id}/take?slug=X	Взять задачу (атомарно)	—
POST	/tasks/{id}/reject	Отклонить задачу	{reason}
POST	/tasks/{id}/assign	Назначить задачу	{assignee_slug}
POST	/tasks/{id}/watch?slug=X	Подписаться на задачу	—
DELETE	/tasks/{id}/watch?slug=X	Отписаться от задачи	—

5.3 Steps

Метод	Путь	Описание	Параметры
GET	/tasks/{id}/steps	Список шагов	—
POST	/tasks/{id}/steps	Создать шаг	{title}
PATCH	/tasks/{tid}/steps/{sid}	Обновить шаг	{title?, done?}
DELETE	/tasks/{tid}/steps/{sid}	Удалить шаг	—

5.4 Messages (Unified)

Метод	Путь	Описание	Параметры
GET	/messages	Список сообщений	?chat_id=X&task_id=Y&limit=50&offset=0
POST	/messages	Отправить сообщение	{chat_id?, task_id?, content, author_type?, author_slug?, mentions?}
GET	/messages/{id}/replies	Треды сообщения	—

5.5 Members

Метод	Путь	Описание	Параметры
GET	/members	Список участников	—
GET	/members/{slug}	Участник по slug	—
POST	/members	Создать участника	{name, slug, type?, agent_config?}
PATCH	/members/{slug}	Обновить участника	{name?, role?, status?, agent_config?}
POST	/members/{slug}/regenerate-token	Перегенерировать токен	—
POST	/members/{slug}/revoke-token	Отозвать токен	—

5.6 Attachments (TODO)

Метод	Путь	Описание	Статус
POST	/messages/{id}/attachments	Загрузить файл	TODO
GET	/attachments/{id}	Скачать файл	TODO
GET	/attachments?task_id=X	Файлы задачи	TODO

---

6. Агенты

6.1 Концепция

• Один процесс = один агент (picogent)
• Одна сессия на агента — видит всё: задачи, чат, ответы
• Роль = конфигурация в agent.json

6.2 Конфигурация агента (agent.json)

{
  "name": "Кодер",
  "slug": "coder", 
  "prompt": "Ты опытный разработчик...",
  "model": "sonnet",
  "capabilities": ["coding", "review"],
  "chat_listen": "mentions",
  "task_listen": "mentions", 
  "tracker_url": "http://localhost:8100",
  "token": "tb-agent-xxx"
}

6.3 Режимы прослушивания

Chat Listen:

• all — получает все сообщения в подписанных проектах
• mentions — только при @упоминании

Task Listen:

• all — получает все события задач в подписанных проектах
• mentions — только задачи где агент assignee/reviewer/watcher

6.4 Capabilities (способности)

Массив строк, описывающих что умеет агент:

• "coding" — написание кода
• "review" — ревью кода
• "testing" — тестирование
• "documentation" — документация
• "architecture" — архитектурные решения

6.5 Жизненный цикл агента

1. Запуск: Читает agent.json, подключается к Tracker
2. Auth: Отправляет токен, получает контекст
3. Subscribe: Подписывается на нужные проекты
4. Listen: Получает события по WebSocket
5. Action: Выполняет действия через REST API
6. Heartbeat: Каждые 30 секунд сообщает о статусе
7. Disconnect: При отключении статус → offline

6.6 Checkpoint Pattern

Проблема: LLM блокирующий — агент не может получать события во время обдумывания.

Решение:

• Короткие задачи (5-10 минут)
• Проверка входящих событий между шагами
• Уведомления о статусе busy во время работы

---

7. BFF (Backend for Frontend)

7.1 Роль BFF

• Прокси между Web Client и Tracker
• Авторизация пользователей (JWT)
• WebSocket прокси с токен-аутентификацией
• Трансформация данных (при необходимости)

7.2 Технологии

• Python, FastAPI
• JWT авторизация
• HTTP Client (httpx)
• WebSocket прокси

7.3 Конфигурация (environment)

# Tracker
TRACKER_URL=http://localhost:8100
TRACKER_WS_URL=ws://localhost:8100/ws
TRACKER_TOKEN=tb-admin-xxx

# Auth
JWT_SECRET=secret-key
AUTH_USER=admin
AUTH_PASS=password

# Server
BFF_HOST=0.0.0.0
BFF_PORT=8200

7.4 WebSocket прокси

1. Client подключение: wss://dev.team.uix.su/ws?token={jwt}
2. Валидация JWT: Проверка токена, извлечение user
3. Tracker подключение: ws://localhost:8100/ws с TRACKER_TOKEN
4. Двусторонний relay: Client ↔ BFF ↔ Tracker

7.5 REST прокси

Все API запросы проксируются с добавлением:

• Авторизация: Проверка JWT
• Трансформация: Добавление author_slug в сообщения
• Логирование: Запросы и ответы
• CORS: Для фронтенда

---

8. Фронтенд (Web Client)

8.1 Технологии

• Framework: Next.js 15 (App Router)
• Styling: Tailwind CSS
• State: React hooks (useState, useEffect)
• HTTP: fetch API
• WebSocket: Native WebSocket API

8.2 Структура страниц

• /login — Авторизация
• / — Список проектов
• /projects/[slug] — Канбан доска проекта
• /projects/[slug]/settings — Настройки проекта (TODO)
• /agents — Управление агентами (TODO)

8.3 Компоненты

Компонент	Описание	Статус
KanbanBoard	Drag & drop доска + mobile tabs	✅ Реализован
TaskModal	Модалка задачи (title, description, assignee, delete)	✅ Базовая версия
ChatPanel	Чат (lobby)	✅ Базовая версия
CreateTaskModal	Создание задачи	✅ Реализован
CreateProjectModal	Создание проекта	✅ Реализован
AuthGuard	Проверка авторизации	✅ Реализован

8.4 API клиент (api.ts)

• Base URL: process.env.NEXT_PUBLIC_API_URL
• Авторизация: JWT из localStorage
• Обработка ошибок: 401 → редирект на /login
• TypeScript типы для всех моделей

8.5 WebSocket клиент (ws.ts)

class WSClient {
  // Подключение через BFF с JWT токеном
  connect() // ws://bff/ws?token=jwt
  
  // Event handlers
  on(type: string, handler: Function)
  
  // Convenience methods  
  subscribeProject(projectId: string)
  sendChat(chatId: string, content: string)
  sendTaskComment(taskId: string, content: string)
  heartbeat(status: string)
}

8.6 Состояние приложения

• Авторизация: JWT в localStorage
• Проекты: Загружаются при входе в систему
• Задачи: Загружаются для каждого проекта
• WebSocket: Глобальный клиент, подписка по проектам
• Real-time: Обновления через WebSocket события

---

9. Деплой

9.1 Docker Compose (разработка)

services:
  tracker:
    build: ./tracker
    ports: ["8100:8100"]
    depends_on: [postgres, redis]
    
  postgres:
    image: postgres:16-alpine
    ports: ["5433:5432"]
    
  redis:
    image: redis:7-alpine  
    ports: ["6380:6379"]

9.2 Systemd сервисы (продакшен)

Tracker: Docker Compose + systemd unit BFF + Web Client: systemd сервисы на хосте
Picogent: systemd unit на агента

9.3 Nginx конфигурация

# Web Client
location / {
  proxy_pass http://localhost:3100;
}

# BFF API
location /api/ {
  proxy_pass http://localhost:8200/api/;
}

# BFF WebSocket  
location /ws {
  proxy_pass http://localhost:8200/ws;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}

# Agent API (через nginx → Tracker)
location /agent-api/ {
  proxy_pass http://localhost:8100/api/;
}

# Agent WebSocket
location /agent-ws {
  proxy_pass http://localhost:8100/ws;
  proxy_http_version 1.1; 
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}

9.4 SSL/HTTPS

• Dev: dev.team.uix.su (действующий)
• Prod: team.uix.su (placeholder)
• Cертификаты: Let's Encrypt через certbot

9.5 База данных

• Разработка: PostgreSQL в Docker
• Продакшен: PostgreSQL на хосте
• Миграции: Нет (recreate from scratch)
• Бэкапы: pg_dump (TODO)

9.6 Процесс деплоя

1. Git push → git.uix.su/team-board/docs
2. Manual deploy на сервере
3. Restart services: systemctl restart team-board-*
4. Health check: /health endpoints

CI/CD: Пока ручной деплой. В будущем — Gitea Actions.

---

10. Нереализованные части (TODO)

10.1 Backend TODO

• ❌ Attachments API — загрузка/скачивание файлов
• ❌ Task events через WebSocket — task.created/updated/assigned
• ❌ Agent token auth для REST API (только WS)
• ❌ Chat threads — parent_id поддержка в UI
• ❌ Task dependencies — визуализация и валидация
• ❌ БД миграции — пока только recreate

10.2 Frontend TODO

• ❌ Task comments в TaskModal
• ❌ Task steps (live progress) в TaskModal
• ❌ Task watchers — подписка/отписка
• ❌ Agent management — страница /agents
• ❌ Project dashboard — метрики и активность
• ❌ Mobile UI — адаптация под телефоны

10.3 Agent TODO

• ❌ MCP Tools — полный набор инструментов для picogent
• ❌ Session resume — восстановление контекста при переподключении
• ❌ Multi-instance — несколько экземпляров одного агента
• ❌ Agent home — workspace, memory, sessions

10.4 Infrastructure TODO

• ❌ Telegram Bridge — дублирование чата в Telegram
• ❌ OAuth/Authentik — мультипользовательский режим
• ❌ Redis integration — event bus и кеширование
• ❌ CI/CD pipeline — автоматический деплой
• ❌ Monitoring — метрики и логи
• ❌ Backup strategy — регулярные бэкапы БД

---

Заключение

Этот документ является единой точкой правды для всех концепций Team Board. Он основан на реальном коде и документации по состоянию на 2026-02-23.

Версионирование: При значимых изменениях в архитектуре или API обновляется версия документа и дата.

Обратная связь: Если код не соответствует документу — приоритет у кода (он правдивее), документ нужно обновить.