Локальна розробка — налаштування середовища

Вимоги

Швидкий старт

git clone [email protected]:SerhiiInUa/citadel-v2.git
cd citadel-v2
cp .env.example .env
# Edit .env — add bot tokens

# One-time: activate the pre-push doc-coverage hook (Phase 49.1)
bash scripts/setup-hooks.sh

Навіщо hook: блокує git push, коли ти змінюєш код без оновлення документації. Обхід: git push --no-verify. Деталі — розділ "Documentation Law" у CLAUDE.md.

Фронтенд

cd frontend
npm install
npm run dev          # → http://localhost:5173

Vite автоматично проксіює:

• /api/crm/* → http://localhost:19210 (Master Bot)
• /api/* → http://localhost:19200 (MCP Server)
• /ws/* → WebSocket через http://localhost:19200

Команди збірки

• npm run dev — dev-сервер з hot reload
• npm run build — продакшн-збірка → dist/
• npm run i18n:extract — витягти нові рядки перекладу
• npm run i18n:compile — скомпілювати переклади (обов'язково перед збіркою)

Бекенд

Master Bot (CRM API)

cd master-bot
bun install
bun run bot.ts       # → http://localhost:19210

Це основний API-сервер з 68+ ендпоінтами. Потребує MASTER_BOT_TOKEN у .env.

Child Bot (AI-проксі)

cd child-bot
bun install
bun run bot.ts       # → http://localhost:19211

Проксі Telegram ↔ Claude CLI для кожного проєкту. Потребує CITADEL_BOT_TOKEN у .env.

MCP State Bridge

cd mcp-server
bun install
bun run server.ts    # → http://localhost:19200

Менеджер стану, SSE, WebSocket.

Порти

Env-змінні (.env)

Обов'язкові

MASTER_BOT_TOKEN=...           # Telegram @BotFather
CRM_ALLOWED_ORIGINS=http://localhost:5173

Для повної функціональності

CITADEL_BOT_TOKEN=...          # Child bot token
GITHUB_CLIENT_ID=...           # GitHub OAuth
GITHUB_CLIENT_SECRET=...
GOOGLE_CLIENT_ID=...           # Google OAuth
GOOGLE_CLIENT_SECRET=...

Опціональні

HEALTH_PORT=19210
CITADEL_DIR=/path/to/citadel-v2
EMAIL_PROVIDER=console          # 'console' for dev (prints to terminal)
[email protected]

Docker (опціонально)

# Full stack
docker compose -f docker/docker-compose.yml up -d --build

# Frontend only
docker compose -f docker/docker-compose.yml up -d frontend

Структура проєкту

citadel-v2/
├── master-bot/          # Telegram orchestrator + CRM API (:19210)
├── child-bot/           # Per-project AI proxy (:19211)
├── mcp-server/          # State bridge (:19200)
├── shared/              # Shared code (db, auth, routes, migrations)
├── frontend/            # React CRM + Phaser (Vite)
├── clients/             # ARC CLI
├── services/            # archived Phase 36 NotebookLM Bridge (decommissioned 2026-06-05; RAG moved into shared/rag.ts in Phase 71)
├── config/              # Registry, vault, workers
├── skills/              # Skill definitions + evals
├── docker/              # Compose + Dockerfiles + Nginx
├── infra/nginx/         # VPS Nginx config
├── scripts/             # Deploy, build scripts
├── docs/                # Documentation
└── data/                # SQLite DB (auto-created)

Типовий робочий процес розробки

1. Запусти фронтенд: cd frontend && npm run dev
2. Запусти Master Bot: cd master-bot && bun run bot.ts
3. Відкрий http://localhost:5173
4. Зареєструйся через email (email_provider=console → код з'являється в терміналі)
5. Створи проєкт через UI
6. Працюй з воркерами через робочий простір

Швидка перевірка типів

cd master-bot && bun build --no-bundle bot.ts    # Type-check backend
cd frontend && npx vite build                     # Type-check + build frontend

Усунення проблем