# 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`

```yaml
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 настройки:
```python
allow_origins=[
    "https://team.uix.su", 
    "https://dev.team.uix.su", 
    "http://localhost:3100"
]
```

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

### Environment Variables (Tracker):
```bash
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/` на дату создания спецификации.