Lokalne środowisko — Development Setup

Wymagania

Szybki start

git clone [email protected]:SerhiiInUa/citadel-v2.git
cd citadel-v2
cp .env.example .env
# Edytuj .env — dodaj tokeny botów

# Jednorazowo: aktywuj pre-push hook doc-coverage (Phase 49.1)
bash scripts/setup-hooks.sh

Dlaczego hook: blokuje git push, gdy zmieniasz kod bez aktualizacji dokumentów. Bypass: git push --no-verify. Szczegóły — sekcja „Documentation Law" w CLAUDE.md.

Frontend

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

Vite automatycznie proksuje:

• /api/crm/* → http://localhost:19210 (Master Bot)
• /api/* → http://localhost:19200 (MCP Server)
• /ws/* → WebSocket przez http://localhost:19200

Komendy budowania

• npm run dev — serwer dev z hot reload
• npm run build — build produkcyjny → dist/
• npm run i18n:extract — wyodrębnij nowe ciągi tłumaczeń
• npm run i18n:compile — skompiluj tłumaczenia (obowiązkowo przed build)

Backend

Master Bot (CRM API)

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

To jest główny serwer API z 68+ endpointami. Wymaga MASTER_BOT_TOKEN w .env.

Child Bot (AI Proxy)

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

Proxy Telegram ↔ Claude CLI dla każdego projektu. Wymaga CITADEL_BOT_TOKEN w .env.

MCP State Bridge

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

Menedżer stanu, SSE, WebSocket.

Porty

Zmienne środowiskowe (.env)

Wymagane

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

Dla pełnej funkcjonalności

CITADEL_BOT_TOKEN=...          # Token Child bota
GITHUB_CLIENT_ID=...           # GitHub OAuth
GITHUB_CLIENT_SECRET=...
GOOGLE_CLIENT_ID=...           # Google OAuth
GOOGLE_CLIENT_SECRET=...

Opcjonalne

HEALTH_PORT=19210
CITADEL_DIR=/path/to/citadel-v2
EMAIL_PROVIDER=console          # 'console' do dev (wypisuje w terminalu)
[email protected]

Docker (opcjonalnie)

# Pełny stos
docker compose -f docker/docker-compose.yml up -d --build

# Tylko frontend
docker compose -f docker/docker-compose.yml up -d frontend

Struktura projektu

citadel-v2/
├── master-bot/          # Orkiestrator Telegram + CRM API (:19210)
├── child-bot/           # Proxy AI dla każdego projektu (:19211)
├── mcp-server/          # State bridge (:19200)
├── shared/              # Wspólny kod (db, auth, routes, migrations)
├── frontend/            # React CRM + Phaser (Vite)
├── clients/             # ARC CLI
├── services/            # NotebookLM Bridge (Python)
├── config/              # Registry, vault, workerzy
├── skills/              # Definicje skillów + evals
├── docker/              # Compose + Dockerfiles + Nginx
├── infra/nginx/         # Konfiguracja Nginx VPS
├── scripts/             # Skrypty deploy i build
├── docs/                # Dokumentacja
└── data/                # SQLite DB (tworzona automatycznie)

Typowy workflow dewelopera

1. Uruchom frontend: cd frontend && npm run dev
2. Uruchom Master Bot: cd master-bot && bun run bot.ts
3. Otwórz http://localhost:5173
4. Zarejestruj się przez email (email_provider=console → kod w terminalu)
5. Utwórz projekt przez UI
6. Pracuj z workerami przez Workspace

Szybkie sprawdzanie typów

cd master-bot && bun build --no-bundle bot.ts    # Sprawdź typy backendu
cd frontend && npx vite build                     # Sprawdź typy + build frontendu

Troubleshooting