ZBrain/CLAUDE.md

# ZBrain — Claude Code Context

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

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

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

Полное описание — в [README.md](README.md), архитектура — в [docs/ARCHITECTURE.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

```typescript
// 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

### Стиль ошибок

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

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

```bash
# Установка
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
```

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

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

- [x] **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