ZBrain/docs/ROADMAP.md

ZBrain Roadmap

Документ для Claude Code: пошаговый план реализации с критериями готовности каждого спринта. Подходит как для последовательной разработки, так и для параллельной (некоторые спринты независимы).

Принципы

• Каждый спринт заканчивается рабочей фичей, которую можно показать
• Каждый спринт мерж в develop, в main идут тегированные релизы
• Любой Claude Code инстанс может прочитать этот файл и понять, что делать дальше
• ADR (Architecture Decision Records) пишутся в docs/DECISIONS/ для нестандартных решений

---

Sprint 0: Инфраструктура VM (1 вечер)

Цель: Готовая VM, на которой работает Postgres и установлен gbrain.

Задачи:

• Создать VM: 4 vCPU / 8 GB RAM / 80 GB SSD / Ubuntu 22.04 LTS
• Назначить статический IP в сети ZETIT
• Добавить DNS: brain.zetit.local (внутренний) и brain.zetit.ru (внешний)
• Запустить scripts/bootstrap-vm.sh
• Создать Postgres пользователя brainhub с паролем
• Сгенерировать секреты для .env (SESSION_SECRET, JWT_SECRET, TOKEN_ENCRYPTION_KEY)
• Получить API ключи: OPENAI_API_KEY, ANTHROPIC_API_KEY

Критерии готовности:

• systemctl status postgresql показывает active
• sudo -u postgres psql -d brainhub -c 'SELECT * FROM pg_extension' возвращает vector, pg_trgm, pgcrypto
• sudo -u zbrain bash -c 'PATH=$HOME/.bun/bin:$PATH bun --version' работает
• /etc/zbrain/.env существует, заполнен, права 600

Документировать: реальные параметры VM (IP, hostname, дата создания) в docs/INFRASTRUCTURE.md

---

Sprint 1: Первый gbrain instance (1 день)

Цель: Один работающий gbrain instance с импортированными тестовыми данными.

Задачи:

• Создать gbrain mirror в git.zetit.ru/zuevav/gbrain-mirror
• Запустить scripts/create-brain.sh zetit "ZETIT MSP" 3001
• Импортировать тестовый корпус (например, какие-то существующие markdown файлы)
• Проверить curl http://localhost:3001/health или эквивалент
• Прицепить локальный Claude Code напрямую к этому gbrain (без brainhub-прокси)
• Выполнить пару query и убедиться что работает

Критерии готовности:

• systemctl status zbrain-gbrain-zetit показывает active
• В БД есть страницы и эмбеддинги: SELECT count(*) FROM pages, count(*) FROM content_chunks WHERE embedding IS NOT NULL
• Claude Code успешно делает MCP запросы

Известные риски:

• gbrain v0.26 переехал на новый OAuth - возможно поломались CLI флаги. Зафиксировать рабочую версию тегом.
• FNA-прокси может блокировать какие-то OpenAI/Anthropic эндпоинты - проверить curl --proxy ... до запуска import.

---

Sprint 2: Brainhub каркас + локальный auth (3-4 дня)

Цель: Работающий веб-интерфейс с login/logout, без функционала брейнов.

Задачи:

apps/api (backend)

• Express + TypeScript скелет
• Структура: routes/, services/, middleware/, db/, lib/
• ORM выбрать: Drizzle (рекомендую за TS-first) или Prisma
• Миграции: создать таблицы users, sessions
• POST /api/auth/register (только для owner-команды, остальные через UI)
• POST /api/auth/login (email + password, bcrypt)
• POST /api/auth/logout
• GET /api/auth/me (current user)
• Session middleware (cookie + refresh token rotation)
• RBAC middleware: requireRole('admin'), requireRole('owner')

apps/web (frontend)

• React + Vite + TypeScript + Tailwind + shadcn/ui
• Layout: sidebar + header + content
• Страницы: /login, /dashboard (заглушка), /profile
• React Router v6
• React Query для API
• Auth context + protected routes

Критерии готовности:

• На свежей БД создаётся initial owner из ENV (INITIAL_OWNER_EMAIL/PASSWORD)
• Можно войти через UI на /login
• /dashboard защищён, без auth редиректит на /login
• Cookie с session token, при logout удаляется
• Refresh token rotation работает (логин не истекает через 15 минут активной сессии)

---

Sprint 3: MCP Proxy + Tokens (2-3 дня)

Цель: Claude Code на любом сервере подключается через brainhub, а не напрямую к gbrain.

Задачи:

packages/mcp-proxy

• Express router, маунтится на /mcp/:brain
• Извлечение Bearer token из заголовков
• Кэш токенов в памяти (30s TTL) - не ходить в БД на каждый запрос
• Проверка: revoked, expired, IP allowlist, scope
• Резолв :brain → localhost:PORT через таблицу brains
• Прокси через http-proxy-middleware или nativный stream
• In-memory очередь для audit log + batch insert (раз в секунду)
• Throttled update last_used_at (не чаще раза в минуту на токен)

apps/api: токены

• Таблица access_tokens (см. docs/SECURITY.md)
• POST /api/tokens (создание - возвращает plaintext token ОДИН РАЗ)
• GET /api/tokens (список с prefix, без full token)
• DELETE /api/tokens/:id (revoke - soft delete с revoked_at)
• GET /api/tokens/:id/usage (статистика)

apps/web: UI для токенов

• /tokens страница со списком
• Создание токена: имя + scope checkboxes + TTL + IP allowlist
• После создания - модалка с токеном и кнопкой copy (показывается один раз!)
• Revoke с подтверждением

Критерии готовности:

• Создал токен в UI с scope mcp:read:zetit
• Подключил Claude Code: mcpServers.zbrain.url = http://brain.zetit.local/mcp/zetit, header Authorization: Bearer brain_pat_...
• Запрос идёт через brainhub, в audit log записывается
• Revoke токена через UI → следующий запрос Claude Code получает 401
• При двух токенах одного scope работают оба

---

Sprint 4: CRUD брейнов + источники + sync (2-3 дня)

Цель: Создание новых брейнов через UI, добавление и синхронизация источников.

Задачи:

apps/api

• Таблицы brains, sources
• POST /api/brains - создание (внутренний вызов scripts/create-brain.sh или эквивалент на TS)
• GET /api/brains - список со статистикой (page_count, embed_coverage)
• GET /api/brains/:id - детали
• DELETE /api/brains/:id - удаление (с подтверждением, дамп перед удалением)
• POST /api/brains/:id/sources - добавление источника (git, local_dir)
• POST /api/brains/:id/sources/:sourceId/sync - запуск sync
• GET /api/brains/:id/sources/:sourceId/sync/stream - SSE с прогрессом
• Worker queue для sync (bullmq или нативный setInterval)
• Планировщик cron-based sync (node-cron)

apps/web

• /brains страница со списком
• /brains/new форма создания
• /brains/:id - tabs: Overview, Sources, Browse, Query, Activity
• Sources tab: список с status, кнопки Sync now / Edit / Delete
• Sync с realtime прогрессом через SSE
• Подсветка статусов: green/yellow/red

Критерии готовности:

• Создать брейн community через UI → автоматически создаётся БД, запускается gbrain, регистрируется systemd unit
• Добавить git source → запустить sync → видеть прогресс в реальном времени
• Расписание sync каждые 6 часов работает
• Удаление брейна делает дамп и убирает все артефакты

Важно: удаление брейна - irreversible операция, обязательно подтверждение через ввод имени брейна (как в GitHub).

---

Sprint 5: Dashboard + Projects + Connect (2-3 дня)

Цель: Полноценный UI с визуализацией проектов и copy-paste готовыми сниппетами.

Задачи:

apps/api

• Таблицы projects, project_connections
• CRUD endpoints для projects
• POST /api/projects/:id/connections - привязка проекта к брейну с указанием токена
• GET /api/connect/snippets/:brainId?client=claude-code|cursor|cli - генерация сниппетов

apps/web

• /dashboard - сводка: количество брейнов, total pages, active sync jobs, recent activity
• /dashboard карточки брейнов с цифрами
• /projects - таблица проектов с привязкой к брейнам
• /projects/:id - детали + кнопка "Connect new brain"
• /brains/:id/connect - страница с готовыми сниппетами:
  • Claude Code JSON (для ~/.claude/mcp.json или .claude/mcp.json в проекте)
  • Cursor конфиг
  • Bash one-liner для CLI
  • QR код с готовой строкой подключения
• Copy-to-clipboard на каждом блоке
• Глобальный поиск по всем брейнам (с уважением scope)

Критерии готовности:

• Dashboard загружается за <500ms
• В Projects вижу таблицу: ZetitConnect → [zetit (write), personal (read)]
• На странице Connect - готовая JSON структура с реальным URL и токеном, копируется одним кликом
• QR-код корректно сканируется и содержит JSON

---

Sprint 6: OAuth + публичный контур (2-3 дня)

Цель: Авторизация через Yandex/GitHub OAuth, публичный endpoint для MCP.

Задачи:

apps/api

• Зарегистрировать OAuth приложения у Yandex и GitHub
• passport.js + passport-yandex + passport-github2
• OAuth flow: /oauth/yandex, /oauth/yandex/callback (аналогично GitHub)
• Привязка к existing user по email match (с подтверждением)
• Поддержка регистрации нового пользователя через OAuth (опционально, по INVITE_ONLY флагу)
• Отдельный Express app на 3010 порту, монтирует только /mcp и /oauth

deploy

• Получить TLS сертификат от Let's Encrypt для brain.zetit.ru
• Включить nginx public server-блок
• Проверить, что внутренний и публичный API не пересекаются (нет утечки UI на публичный)

Критерии готовности:

• Залогиниться через "Sign in with Yandex" - работает
• На публичном endpoint https://brain.zetit.ru/api/brains → 404
• На публичном endpoint https://brain.zetit.ru/mcp/zetit → работает с токеном
• TLS A+ rating на SSL Labs

---

Sprint 7: Hardening (2-3 дня)

Цель: Production-ready: бэкапы, мониторинг, 2FA, документация.

Задачи:

• /audit страница в UI с фильтрами (actor, action, resource, date range)
• CSV export audit log
• 2FA (TOTP) опционально для каждого пользователя
• Проверить и настроить scripts/backup.sh, добавить в cron
• Тестовое восстановление из бэкапа на отдельной VM
• Prometheus endpoint /metrics: request rate, error rate, db connections, queue depth
• Health endpoint с глубокой проверкой (DB connectivity, gbrain instances)
• Alerts на падение sync, на error rate > N
• Documentation: docs/API.md, docs/SECURITY.md, docs/OPERATIONS.md
• Load test: 100 RPS на /mcp, что выдерживает

Критерии готовности:

• Восстановление из бэкапа прошло успешно
• Включил 2FA на owner аккаунте, работает
• /metrics возвращает prometheus formatted text
• Audit log имеет все важные события: brain.create, brain.delete, token.create, token.revoke, user.login, user.logout, mcp.call

---

После Sprint 7: миграция данных

Цель: Перенести всё что нужно в соответствующие брейны.

• Создать брейны: zetit, telerapharma, personal, community (если ещё не созданы)
• Источники для zetit: ZetitConnect docs repo, ZETIT internal wiki
• Источники для telerapharma: runbook'и Exchange/MikroTik/1C
• Источники для personal: личный markdown garden, "Хлеб и молоко" docs
• Источники для community: документы Смоленская 10
• Переключить Claude Code на всех серверах с локального чтения на gbrain через brainhub
• Удалить дублированную документацию из локальных копий (оставить только в источниках)

---

Дальнейшее развитие

• Импорт из Notion, Obsidian, Confluence через gbrain skills
• Webhook'и: уведомления в Slack/Telegram при критичных событиях
• API для интеграций с другими системами (1С, FortiGate logs)
• Mobile-friendly UI (адаптив или отдельная PWA)
• Multi-user collaboration на одном брейне (комментарии, suggestions)
• Версионирование промптов и skills через gbrain