FGOS

FAT Tech Growth Operacional System

---

FGOS é a plataforma modular da FAT Tech para operar uma agência de marketing de ponta a ponta: produtividade (estilo ClickUp/Monday), social/ads (Hootsuite), mensageria com IA (ManyChat), CRM com funil Kanban (Pipedrive) e BI consolidado (PowerBI) — tudo costurado por uma coluna vertebral orientada a eventos.

A decisão central, validada após várias iterações de arquitetura: n8n não é o barramento do sistema. O caminho quente usa FastAPI + Redis Streams + workers finos em Python. O n8n entra apenas como um consumidor, responsável pela cola de integrações que muda toda semana — fora da ingestão crítica.

Arquitetura em uma imagem

Webhooks (Meta/TikTok/LinkedIn)        Frontend SPA
            │                               │
            ▼                               ▼
        ┌──────────────────────────────────────┐
        │      Traefik / Caddy (TLS, proxy)     │
        └──────────────┬───────────────┬────────┘
                 /webhooks/*        /api/*
                       │               │
                       ▼               ▼
                  ingest          api backend        (FastAPI)
                       │               │ publica eventos
                       └───────┬───────┘
                               ▼
                  ┌─────────────────────────┐
                  │  Redis Streams (espinha) │
                  └───┬──────────┬───────────┘
            ┌─────────┘          │           └──────────┐
            ▼                    ▼                      ▼
     worker-router       worker-messaging         worker-social   ...  n8n (cola)
            │                    │                      │
            ▼                    ▼                      ▼
     ┌──────────────┐                          ┌──────────────┐
     │ PostgreSQL 16│  (OLTP / core)           │  ClickHouse  │  (OLAP / BI)
     └──────────────┘                          └──────────────┘

Regras inegociáveis do barramento (ver docs/ARCHITECTURE.md):

• Todo evento carrega um envelope canônico com event_id, agency_id, trace_id, hops.
• event_id é chave de idempotência (processed_events).
• Automações herdam o trace_id e incrementam hops; hops > 5 corta loops CRM↔Mensageria.
• Dinheiro é sempre bigint em centavos — nunca float.
• Multi-tenant: agency_id em toda tabela e todo evento.

Módulos

Módulo	Referência de mercado	Estado	Tabelas-núcleo
A — Produtividade	ClickUp / Monday	✅ API + eventos	workspaces, lists, items (JSONB + version)
D — CRM	Pipedrive	✅ API + Kanban move (409)	pipelines, stages, deals (value_cents)
B — Social/Ads	Hootsuite	✅ fila SKIP LOCKED + backoff por conta + OAuth (dry-run)	social_accounts, posts_queue
C — Mensageria/IA	ManyChat	✅ debounce + state machine + IA externa + handoff (dry-run)	contacts, chat_sessions, messages
E — BI	PowerBI	✅ micro-batch → ClickHouse + API de leitura + dashboard ECharts	events_log (MergeTree)
Acesso	Auth + Onboarding	✅ login JWT multi-tenant + signup self-service white-label	app_users, agencies (slug/branding)

MVP — espinha em 4 comandos

Valida a fase 1 do roadmap: um evento nasce no Workspace, atravessa a fila e cria um deal no CRM, com idempotência e anti-loop ativos, e espelhamento para o ClickHouse (BI).

copy .env.example .env

# 1. infra + migrations
docker compose --profile migrate up migrate-postgres migrate-clickhouse
docker compose up -d postgres redis clickhouse api worker-router worker-bi `
  worker-social worker-messaging worker-messaging-flusher

# 2. fixtures de dev (agency, pipeline, stages, workspace, list)
docker compose exec api fgos seed

# 3. smoke end-to-end: cria item -> ve deal aparecer -> confirma BI
python scripts/smoke_mvp.py

O que o smoke prova:

• POST /api/items com convert_to_deal=true publica workspace.item.created em stream:events.
• worker-router consome, cria o deal no Postgres, emite crm.deal.created como child() (preserva trace_id, hops+1) e espelha tudo em stream:bi.events.
• worker-bi faz micro-batch para events_log no ClickHouse.

Pular checagem do ClickHouse: python scripts/smoke_mvp.py --no-clickhouse.

Dashboard de BI: depois do smoke, abra http://localhost:8000/dashboard/ para ver KPIs, série temporal, breakdown de eventos e funil CRM (ECharts, lendo direto do ClickHouse).

Onboarding white-label: abra http://localhost:8000/onboarding/ para criar uma agência nova (signup self-service que provisiona pipeline + workspace + owner e já loga). Login de dev pronto após fgos seed: [email protected] / fgosdev. Tema por agência via /onboarding/?org=<slug>.

Web App (SPA operável)

React + Vite + TypeScript em web/ — 6 telas consumindo a API: Login, Dashboard (BI), CRM Kanban, Mensageria (inbox + chat), Social/Ads (contas + agendamento) e Workspace. Responsivo (drawer no mobile), tema cyber FAT Tech.

cd web
npm install
npm run dev          # http://localhost:5173  (proxy /api -> :8000)
npm run build        # type-check (tsc) + bundle de produção em web/dist/

Login de dev: [email protected] / fgosdev. Detalhes em docs/MODULE-WEB.md. A camada de dados (web/src/lib) é a base compartilhada para o app mobile (Expo) na sequência.

Desenvolvimento local (sem Docker)

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

fgos seed
fgos api
fgos worker router
fgos worker bi

Validação:

$env:PYTHONPATH='src'
python -m unittest discover -s tests
python -m compileall src

Documentação

Documento	O que é
docs/OVERVIEW.md	Comece aqui — visão consolidada: arquitetura, módulos, dados, eventos, operação
docs/API.md	Referência de todos os endpoints REST e os eventos que emitem
docs/EVENTS.md	Catálogo de eventos: produtor → consumidor → payload + idempotência/anti-loop
docs/MODULE-B-SOCIAL.md	Módulo Social/Ads (fase 2): cripto de token, API Hell, OAuth, dry-run vs live
docs/MODULE-C-MESSAGING.md	Módulo Mensageria (fase 3): debounce, state machine, IA externa, handoff
docs/MODULE-E-BI.md	Módulo BI (fase 4): CQRS, API de leitura ClickHouse, dashboard ECharts
docs/MODULE-AUTH-ONBOARDING.md	Auth (fase 5): login JWT multi-tenant, onboarding self-service, white-label
docs/MODULE-WEB.md	Web App (fase 6): SPA React+Vite+TS, telas, client tipado, base mobile
docs/ARCHITECTURE.md	Fonte da verdade — EDT completa: contrato de eventos, DDL, código crítico, CQRS, backups
docs/EXTRACTION-INTEGRATION-KB.md	Rota alternativa de escala: integrar OSS (Plane/Twenty/Postiz/Evolution/Superset)
docs/COMPETITOR-IMPULSE-CRM.md	Engenharia reversa do concorrente Impulse CRM + mapeamento → FGOS + oportunidades de roadmap
docs/CORE-ENGINE-ARCHITECTURE.md	Decisões condensadas do runtime
CHANGELOG.md	Histórico por fase do roadmap
neural-base/	Base de conhecimento para agentes de IA (knowledge graph, facts, ADRs, glossário)

Roadmap honesto

Fase	Entrega
0 ✅	Infra + contrato de evento + idempotência + espinha Redis Streams
1 ✅ (MVP)	Workspace + CRM trocando eventos reais pela fila, com BI espelhado
2 ✅	Social/Ads: OAuth (scaffolding), backoff por conta, SKIP LOCKED, cripto de token
3 ✅	Mensageria: debounce + state machine + IA por API externa + handoff (dry-run)
4 ✅	BI: API de leitura ClickHouse + dashboard ECharts (/dashboard)
5 ✅	Auth JWT multi-tenant + onboarding self-service + casca white-label (/onboarding)
6 ✅	Web App React completo (6 telas operáveis + responsivo + UI/UX), compila de verdade; base mobile pronta

Operação

docker compose ps
docker compose logs -f worker-router
docker compose exec redis redis-cli -a "$REDIS_PASSWORD" XLEN stream:events
docker stats --no-stream

Backups off-box não são opcionais numa VPS única: dump diário do Postgres, backup nativo do ClickHouse e cópia do AOF do Redis para OCI Object Storage. Ver docs/ARCHITECTURE.md §9.

Licença

MIT © Walfredo Figueiredo Neto / FAT Tech. O runtime event-driven e a identidade FGOS são trabalho original da FAT Tech. Ver LICENSE e FGOS.md.

---

_{Desenvolvido com IA pela FAT Tech · fattech.com.br · Januária, MG — Brasil}