ZBrain — Claude Code Context

Этот файл читается Claude Code при работе в репозитории ZBrain. Описывает контекст проекта, конвенции, и где что искать.

Что это за проект

ZBrain — централизованная база знаний для AI-агентов ZETIT. Это:

Веб-админка для управления несколькими gbrain instance'ами
MCP-прокси между Claude Code и gbrain с auth, rate limit, audit
Многотенантная архитектура с изоляцией БД на каждый брейн

Полное описание — в README.md, архитектура — в docs/ARCHITECTURE.md.

Контекст пользователя

Этот проект разрабатывается Зуевым Алексеем (ZETIT, ИП). Окружение:

Продакшен серверы работают на Ubuntu 22.04
Сеть — за FNA-прокси (fna.zetit.ru:3128, логин client_001)
Git — на git.zetit.ru (внутренний). Этот репо: git@git.zetit.ru:zuevav/ZBrain.git
gbrain — vendored mirror на git@git.zetit.ru:zuevav/gbrain-mirror.git
Параллельные проекты — ZetitConnect (тоже Node/React/Postgres), TeleraPharma инфра, личные проекты
Стиль работы — детальные spec'и + поэтапная реализация через Claude Code

Технологический стек

Слой	Технология
Backend runtime	Node.js 22 LTS + TypeScript 5.6
Backend framework	Express 4
ORM	Drizzle ORM
Frontend	React 18 + Vite + TypeScript
Styling	Tailwind CSS + shadcn/ui
State	React Query + Zustand
Forms	React Hook Form + Zod
DB	PostgreSQL 16 + pgvector
Auth	passport.js (local + yandex + github)
Package manager	bun (workspaces)
Testing	Vitest
Deployment	Docker Compose + systemd для gbrain instances

Структура репозитория

ZBrain/
├── apps/
│   ├── api/                # Backend Express app
│   │   └── src/
│   │       ├── routes/     # HTTP routes
│   │       ├── services/   # бизнес-логика
│   │       ├── middleware/ # auth, RBAC, rate limit
│   │       ├── db/         # Drizzle schema и миграции
│   │       └── lib/        # утилиты
│   └── web/                # Frontend React app
│       └── src/
│           ├── pages/      # страницы (роуты)
│           ├── components/ # переиспользуемые компоненты
│           ├── hooks/      # React hooks
│           └── api/        # клиент к /api
├── packages/
│   ├── shared/             # типы и схемы общие для api+web
│   └── mcp-proxy/          # MCP proxy (валидация токенов, rate limit, audit)
├── deploy/                 # Docker, systemd, nginx конфиги
├── docs/                   # документация
└── scripts/                # bash скрипты для VM

Конвенции кода

TypeScript

strict: true, noUncheckedIndexedAccess: true
Все API ответы типизированы через @zbrain/shared types
Все request bodies валидируются через Zod schemas из @zbrain/shared
Никаких any без // FIXME комментария

Express routes

// apps/api/src/routes/brains.ts
import { Router } from 'express';
import { requireAuth, requireRole } from '../middleware/auth.js';
import { CreateBrainSchema } from '@zbrain/shared';

export const brainsRouter = Router();

brainsRouter.get('/', requireAuth, async (req, res) => {
  const brains = await brainService.list(req.user);
  res.json({ items: brains });
});

brainsRouter.post('/', requireAuth, requireRole(['owner', 'admin']), async (req, res) => {
  const body = CreateBrainSchema.parse(req.body);
  const brain = await brainService.create(body, req.user);
  res.status(201).json(brain);
});

React components

Functional components с hooks (без class components)
Props типизированы через interface
Используем shadcn/ui компоненты, не пишем свои базовые (Button, Input)
React Query для всех server-state, Zustand только для UI state

Стиль ошибок

// API возвращает структуру ApiError из @zbrain/shared
res.status(400).json({
  error: 'Validation failed',
  code: 'VALIDATION_ERROR',
  details: zodError.flatten(),
});

Что точно делать НЕ надо

НЕ обращаться к gbrain напрямую из Claude Code — только через brainhub-proxy
НЕ хранить токены в plain text — всегда хеш SHA-256
НЕ логировать секреты — пароли, токены, API ключи никогда не в logs
НЕ создавать прямые SQL запросы — только через Drizzle ORM
НЕ забывать про audit log для любых мутаций
НЕ забывать про RBAC — каждый mutate endpoint проверяет роль
НЕ выставлять admin API на публичный порт 3010 — только /mcp и /oauth

Что делать ВСЕГДА

Перед началом нового спринта читать docs/ROADMAP.md
Перед написанием нового API endpoint смотреть в packages/shared/src/types.ts — может тип уже есть
При изменении схемы БД — миграция через Drizzle, не вручную в Postgres
При добавлении нового permission/role — обновлять docs/SECURITY.md
При нестандартном архитектурном решении — создавать ADR в docs/DECISIONS/
Закоммитить миграции и schema файлы вместе с кодом, который их использует
Тесты для критичной логики (auth, MCP proxy, RBAC). UI можно без unit тестов в первой версии.

Полезные команды

# Установка
bun install

# Локальная разработка (запустить Postgres сначала)
docker compose -f deploy/docker/docker-compose.dev.yml up -d
bun run db:migrate
bun run dev

# Миграции
bun run --cwd apps/api drizzle-kit generate
bun run db:migrate

# Запуск API + Web в watch mode
bun run dev

# Production build
bun run build

# Тесты
bun run test

Текущее состояние

Обновляй этот раздел после каждого закрытого спринта.

S0: Инфраструктура VM (bootstrap скрипт готов)
S1: Первый gbrain instance (create-brain.sh готов, нужно тестирование)
S2: Brainhub каркас + локальный auth
S3: MCP Proxy + Tokens
S4: CRUD брейнов + источники + sync
S5: Dashboard + Projects + Connect
S6: OAuth + публичный контур
S7: Hardening

Связанные проекты

gbrain (vendored) — https://github.com/garrytan/gbrain (mirror в git.zetit.ru/zuevav/gbrain-mirror)
ZetitConnect — паттерны переиспользуем (Node/Express/React/Postgres стек)
ZetitClaude Code setup — FNA proxy конфигурация, tmux/zsh wrappers

8.0 KiB Raw Permalink Blame History Unescape Escape