ZBrain/README.md

# ZBrain

Централизованная база знаний для AI-агентов ZETIT. Веб-админка + MCP-прокси поверх [gbrain](https://github.com/garrytan/gbrain).

## Зачем это

У нас много разных контекстов, и каждый Claude Code инстанс сейчас читает документацию с диска целиком при каждом запросе:

- **ZetitConnect MSP** — спецификации, спринты, архитектура
- **TeleraPharma** — runbook'и по Exchange, MikroTik, FortiGate, 1C
- **ZETIT клиенты** — конфигурации, инциденты, скрипты
- **Personal** — личные проекты, недвижимость, авто
- **Community (Смоленская 10)** — общедомовое, ЖКХ

ZBrain даёт единую точку доступа: гибридный семантический поиск по корпусу, MCP-интеграция с Claude Code/Cursor, разделение по доменам с изоляцией доступа.

## Архитектура

```
                          ИНТЕРНЕТ
                              │
                              ↓
              brain.zetit.ru (nginx, TLS, OAuth)
                              │
              ┌───────────────┴────────────────┐
              │     brainhub-public            │
              │   - OAuth 2.1 (PKCE)           │
              │   - токены с scope             │
              │   - rate limit                 │
              │   - audit log                  │
              └───────────────┬────────────────┘
                              │
══════════════════════════════╪═══════════════════════════════
                  VPN / внутренний контур
                              │
              ┌───────────────┴────────────────┐
              │     brainhub-internal          │
              │   - Web UI (React)             │
              │   - Admin API                  │
              │   - MCP proxy router           │
              │   - SSE event aggregator       │
              └───────┬────────────┬───────────┘
                      │            │
              ┌───────┴────────────┴──────────┐
              │   gbrain instances (HTTP)     │
              │   :3001 → gbrain_zetit        │
              │   :3002 → gbrain_telerapharma │
              │   :3003 → gbrain_personal     │
              │   :3004 → gbrain_community    │
              └───────┬───────────────────────┘
                      │
              ┌───────┴───────────────────────┐
              │  PostgreSQL 16 + pgvector     │
              │  - brainhub (admin/auth/audit)│
              │  - gbrain_zetit               │
              │  - gbrain_telerapharma        │
              │  - gbrain_personal            │
              │  - gbrain_community           │
              └───────────────────────────────┘
```

## Стек

- **Backend**: Node.js 22 LTS + TypeScript + Express
- **Frontend**: React 18 + TypeScript + Vite + Tailwind + shadcn/ui
- **DB**: PostgreSQL 16 + pgvector + pg_trgm
- **Auth**: Local email/password + Yandex OAuth + GitHub OAuth (passport.js)
- **Engine**: gbrain (vendored через git.zetit.ru/zuevav/gbrain-mirror)
- **Runtime**: Docker Compose в prod, native dev на разработке
- **Deploy**: VM Ubuntu 22.04 в сети ZETIT

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

```
ZBrain/
├── apps/
│   ├── api/                # Express + TS backend
│   └── web/                # React + Vite frontend
├── packages/
│   ├── shared/             # общие типы и утилиты
│   └── mcp-proxy/          # MCP-прокси (валидация токенов, rate limit, audit)
├── deploy/
│   ├── docker/             # Dockerfile'ы и docker-compose
│   ├── systemd/            # unit-файлы для нативного деплоя
│   ├── nginx/              # конфиги reverse proxy
│   └── postgres/           # init scripts, tuning
├── docs/
│   ├── ARCHITECTURE.md     # детальная архитектура
│   ├── DEPLOYMENT.md       # инструкция по деплою
│   ├── SECURITY.md         # модель безопасности
│   ├── API.md              # API reference
│   ├── ROADMAP.md          # план по спринтам
│   └── DECISIONS/          # ADR (Architecture Decision Records)
├── scripts/
│   ├── bootstrap-vm.sh     # первичная установка на чистой Ubuntu 22.04
│   ├── create-brain.sh     # создание нового gbrain instance
│   ├── backup.sh           # бэкап всех БД
│   └── restore.sh          # восстановление
└── README.md               # этот файл
```

## Быстрый старт

### Развёртывание production VM

См. [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). Кратко:

```bash
# 1. Создать VM (4 vCPU / 8 GB RAM / 80 GB SSD / Ubuntu 22.04)
# 2. Склонировать репо
git clone git@git.zetit.ru:zuevav/ZBrain.git /opt/zbrain
cd /opt/zbrain

# 3. Запустить bootstrap (ставит Postgres, Node, Bun, gbrain, тюнит ОС)
sudo bash scripts/bootstrap-vm.sh

# 4. Создать первый брейн
sudo bash scripts/create-brain.sh zetit "ZETIT MSP" 3001

# 5. Сконфигурировать .env (см. .env.example)
sudo nano /etc/zbrain/.env

# 6. Запустить brainhub
cd /opt/zbrain
docker compose up -d
```

### Локальная разработка

```bash
# Зависимости
bun install

# Postgres в docker
docker compose -f deploy/docker/docker-compose.dev.yml up -d

# Миграции
bun run db:migrate

# Запуск API + Web
bun run dev
```

API на http://localhost:3000, Web на http://localhost:5173.

## Дорожная карта

Подробности — в [docs/ROADMAP.md](docs/ROADMAP.md). Кратко по спринтам:

- **S0** — Инфраструктура VM, Postgres, базовая gbrain установка
- **S1** — Первый рабочий gbrain через `gbrain serve --http`
- **S2** — Каркас brainhub + локальный auth + RBAC
- **S3** — MCP-прокси + токены с scope
- **S4** — CRUD брейнов + источники + sync
- **S5** — Dashboard + Projects + Connect страница
- **S6** — OAuth (Yandex + GitHub) + публичный контур
- **S7** — Audit, 2FA, backup, метрики, hardening

## Безопасность

- Каждый gbrain instance имеет **отдельного Postgres-пользователя** и **отдельную БД**
- MCP-токены имеют **scope** (`mcp:read:<brain>`, `mcp:write:<brain>`, `mcp:admin:<brain>`)
- Все MCP-запросы проходят через **brainhub-proxy**, не напрямую к gbrain
- Все действия пишутся в **audit log**
- Публичный контур принимает **только** `/mcp/*` и `/oauth/*`

Подробности — [docs/SECURITY.md](docs/SECURITY.md).

## Лицензия

Proprietary. © ZETIT, Зуев А.В.

gbrain используется по лицензии MIT, см. [гigit.zetit.ru/zuevav/gbrain-mirror](https://git.zetit.ru/zuevav/gbrain-mirror).