docs/specs/OVERVIEW.md

Team Board — Обзор проекта

Что такое Team Board

Team Board — система управления задачами для команд разработки с интеграцией ИИ-агентов. Основная идея: агенты могут автономно брать задачи, выполнять их и взаимодействовать с людьми через единое пространство.

Ключевые концепции:

• Unified workspace — люди и агенты работают в одной системе
• Task automation — агенты могут брать задачи из backlog, выполнять и отчитываться
• Real-time collaboration — WebSocket для мгновенных уведомлений
• Multi-channel access — Web UI, Telegram Bridge, REST API, WebSocket

Архитектура системы

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Web Client │    │   Bridge    │    │  AI Agents  │
│  (React)    │    │ (Telegram)  │    │ (Picogent)  │
└─────┬───────┘    └─────┬───────┘    └─────┬───────┘
      │ HTTP               │ WebSocket         │ REST API
      │                    │                   │
      ▼                    ▼                   ▼
┌─────────────────────────────────────────────────────────┐
│                     BFF                                 │
│              (Backend for Frontend)                     │
│            auth proxy + WebSocket hub                   │
└─────────────────────┬───────────────────────────────────┘
                      │ HTTP + WebSocket
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   Tracker                               │
│                (Core Backend)                           │
│          FastAPI + PostgreSQL + WebSocket               │
└─────────────────────────────────────────────────────────┘

Компоненты:

1. Tracker — основной бэкенд на FastAPI

   • REST API для всех операций
   • WebSocket для real-time events
   • PostgreSQL для данных
   • Аутентификация (JWT + токены для агентов)

2. Web Client — фронтенд на React + Vite

   • Канбан-доска задач
   • Чаты по проектам
   • Управление агентами
   • Real-time обновления через WebSocket

3. Bridge — Telegram интеграция

   • Получает уведомления из Tracker
   • Отправляет в личные чаты Telegram
   • Фильтрация по типу событий

4. Picogent — ИИ-агенты

   • MCP (Model Context Protocol) инструменты
   • Автономная работа с задачами
   • Memory система для контекста
   • Bootstrap конфигурация

Стек технологий

Backend (Tracker):

• FastAPI — веб-фреймворк
• SQLAlchemy — ORM с async поддержкой
• PostgreSQL — основная база данных
• WebSocket — real-time коммуникация
• Pydantic — валидация данных
• JWT — аутентификация пользователей
• Bearer tokens — аутентификация агентов

Frontend (Web Client):

• React 19 — UI библиотека
• TypeScript — типизация
• Vite — bundler и dev server
• Tailwind CSS 4 — стили
• React Router DOM — роутинг

Infrastructure:

• Docker — контейнеризация
• Docker Compose — локальная разработка
• Uvicorn — ASGI сервер

Деплой

Конфигурация портов:

• Tracker: 8100 (FastAPI backend)
• Web Client: 3100 (Vite dev server)
• PostgreSQL: 5432 (база данных)

Docker Compose

Основной файл: /root/projects/team-board/tracker/docker-compose.yml

services:
  tracker:
    build: .
    ports:
      - "8100:8100"
    env_file:
      - .env.dev
    volumes:
      - ./src:/app/src
      - ./data/uploads:/data/uploads
      - ./data/projects:/data/projects
    command: uvicorn tracker.app:app --host 0.0.0.0 --port 8100 --reload

Systemd (production)

Пока не реализовано — в планах на будущее

Nginx (reverse proxy)

Пока не реализовано — в планах на будущее

URL-ы и эндпоинты

Публичные URL-ы:

• https://team.uix.su — production web UI
• https://dev.team.uix.su — development web UI
• http://localhost:3100 — локальная разработка

API endpoints:

• Tracker API: http://localhost:8100/api/v1/
• WebSocket: ws://localhost:8100/ws
• API Docs: http://localhost:8100/docs (только в dev режиме)
• Health check: http://localhost:8100/health

CORS настройки:

allow_origins=[
    "https://team.uix.su", 
    "https://dev.team.uix.su", 
    "http://localhost:3100"
]

Конфигурация

Environment Variables (Tracker):

TRACKER_DATABASE_URL=postgresql+asyncpg://team_board:team_board@localhost:5432/team_board
TRACKER_HOST=0.0.0.0
TRACKER_PORT=8100
TRACKER_JWT_SECRET=change-me-in-production
TRACKER_AGENT_HEARTBEAT_INTERVAL=30
TRACKER_AGENT_HEARTBEAT_TIMEOUT=90
TRACKER_ENV=dev

Файловая система:

• /data/uploads — загруженные файлы (attachments)
• /data/projects — файлы проектов
• src/ — исходный код (dev mode с hot reload)

Особенности архитектуры

Аутентификация:

• JWT токены — для web пользователей
• Bearer токены (tb-xxxxx) — для агентов
• Middleware на всех API эндпоинтах (кроме /docs, /health, /ws)

WebSocket система:

• Heartbeat мониторинг (90 сек timeout)
• Автоматический offline статус при разрыве
• Фильтрация событий по подпискам проектов
• Поддержка множественных соединений одного пользователя

Database Seeding:

• Автоматическое создание таблиц в dev режиме
• Auto-seed данными если БД пуста
• Seeding скрипт: src/tracker/init_db.py

Логирование:

• Request/Response логи всех HTTP запросов
• WebSocket события
• Heartbeat таймауты
• Ошибки с полным traceback

Этот документ описывает текущее состояние проекта по коду в /root/projects/team-board/ на дату создания спецификации.