# Arcádia Suite — Contexto para Claude

## Stack
- **Frontend:** React 18 + TypeScript + Tailwind + shadcn/ui
- **Backend:** Express.js + Socket.IO + Drizzle ORM
- **DB:** PostgreSQL 16 + pgvector
- **Microserviços Python:** FastAPI (portas 8001-8005)
- **Deploy:** Docker Compose + Coolify + PM2
- **Real-time:** Socket.IO

## Estrutura principal
```
server/
  manus/service.ts        # Agente principal (169KB, 30+ tools, ReAct pattern)
  autonomous/             # Pipeline multi-agente (Architect→CodeGen→Validator)
  blackboard/             # Coordenação de agentes
  python/                 # 8 microserviços Python (fisco, contabil, bi, etc.)
  learning/service.ts     # Knowledge management
  [modulo]/routes.ts      # 38 grupos de rotas (crm, erp, whatsapp, chat...)
client/                   # 66 páginas React
shared/schema.ts          # Schema do banco (7317 linhas, Drizzle ORM)
docker/
  litellm-config.yaml     # Roteamento de LLMs (TIER 1: LLMFit, TIER 2: Ollama, TIER 3: externos)
```

## Arquitetura de IA
```
Manus / Agents / Embeddings
        │  AI_INTEGRATIONS_OPENAI_BASE_URL
        ▼
   LiteLLM :4000  (gateway unificado, loga tudo no banco)
        ├──► LLMFit (TIER 1 — fine-tuned, soberano) [slot pronto, comentado]
        ├──► Ollama :11434 (TIER 2 — local, padrão)
        └──► OpenAI/Anthropic/Groq (TIER 3 — opt-in, só se API key configurada)
```

**Variáveis chave do Manus:**
```
AI_INTEGRATIONS_OPENAI_BASE_URL=http://litellm:4000/v1
AI_INTEGRATIONS_OPENAI_API_KEY=${LITELLM_API_KEY}
```

## Docs estratégicos
- `DOCUMENTATION.md` — docs técnicas completas
- `PLANO_EVOLUCAO_ARCADIA.md` — roadmap e evolução
- `MAPA_SISTEMA_ARCADIA.md` — mapa do sistema

## Git e Deploy

### Remote canônico
- **Remote principal:** `gitea` → `http://10.0.1.7:3000/arcadia-admin/arcadiasuite` (Gitea interno)
- **Branch de produção:** `main`
- **Push de deploy:** `git push gitea Servidor:main`

> O Coolify monitora o Gitea (`https://git.onboardbi.com.br/arcadia-admin/arcadiasuite`, branch `main`).
> Push para `gitea` → Coolify detecta → build automático → rolling deploy.
> O remote `origin` (GitHub) é backup secundário — push opcional para manter sincronizado.
> O desenvolvimento local ocorre na branch `Servidor` — fazer push para `main` no Gitea ao deployar.

### Deploy em produção
**Fluxo normal (CI/CD automático):**
```bash
cd /opt/arcadia_merged
git push gitea Servidor:main
```
O Coolify faz o build e deploy automaticamente (~3-5 min).

**Deploy manual (emergência):**
```bash
cd /opt/arcadia_merged
docker compose -f docker-compose.prod.yml build app
docker compose -f docker-compose.prod.yml up -d app
```
- Reconstrói só o container `app` (~3-5 min)
- Banco, Redis, MiroFlow, Python services **não são afetados**
- Downtime: ~30 segundos durante a troca do container

### Serviços em execução (não mexer sem necessidade)
```
arcadia-prod-app-1        porta 5000  → suite.onboardbi.com.br (Traefik)
arcadia-prod-db-1         PostgreSQL  (dados em volume Docker)
arcadia-prod-redis-1      Redis
arcadia-prod-miroflow-1   MiroFlow agente
arcadia-prod-litellm-1    LiteLLM gateway
arcadia-prod-superset-1   Superset BI
arcadia-prod-{contabil,bi,automation,fisco,embeddings}-1  Python services
```

## O que está implementado
- ✅ Manus (agente autônomo, 30+ ferramentas)
- ✅ Pipeline de agentes autônomos
- ✅ Embeddings semânticos (pgvector)
- ✅ CRM, WhatsApp, Email, Chat
- ✅ ERP/ERPNext, Fiscal (NF-e, SPED), Contábil (DRE, balanço)
- ✅ BI workspace, Retail/POS, RH, Produtividade
- ✅ Docker dev + prod, LiteLLM gateway

## O que ainda falta
- ❌ LLMFit: slot pronto em `litellm-config.yaml`, só habilitar quando disponível
- ❌ Testes automatizados / CI-CD
- ❌ Monitoramento (APM, Sentry, métricas)
- ❌ Multi-tenancy completo
- ❌ Rate limiting em todos os endpoints (parcial)

## Comandos úteis
```bash
# Dev
docker compose up -d
docker compose --profile ai up litellm ollama -d

# Prod (Coolify)
docker compose -f docker-compose.prod.yml up -d

# Migrations
npm run db:push

# Build
npm run build
```

## Variáveis de ambiente críticas (ver .env.example)
```
SESSION_SECRET, SSO_SECRET          # gerar strings seguras em prod
AI_INTEGRATIONS_OPENAI_BASE_URL     # aponta para LiteLLM
LLMFIT_BASE_URL                     # LLMFit quando disponível
OLLAMA_BASE_URL                     # Ollama host ou container
OPENAI_API_KEY                      # opcional (soberania: deixar vazio)
```