Relação entre os 5 Apps do C-Suite

📊 Para diagramas visuais detalhados, consulte ARQUITETURA.md
📈 Para diagramas de sequência detalhados, consulte DIAGRAMAS_SEQUENCIA.md
📖 Para definições de termos, consulte GLOSSARIO.md

Visão Geral

O ecossistema C-Suite é composto por 5 aplicações principais que trabalham em conjunto para formar um "organismo digital de gestão" com três capacidades centrais:

Percepção – Coletar sinais de clientes, vendas, estoque, financeiro e interações
Consciência – Interpretar ameaças e oportunidades usando modelos de IA + regras
Ação – Decidir e coordenar ações executivas

Os 5 Apps

1. 4c (`/4c`)

Tipo: Córtex Comercial (nível cliente)
Porta: 8080-8085 (dependendo do serviço)
Função: Decisões 1:1 com clientes (4 Certos: Cliente Certo, Oferta Certa, Jeito Certo, Hora Certa)

Componentes:
- Feature Service (/features/customer) - Agrega dados por cliente/SKU/contexto
- Scoring Service (/score/intent|offer|channel|timing) - Modelos de ML para scoring
- Decision API (/decide, /decide/auto, /send) - Orquestra decisões
- Executor - Executa ações (WhatsApp, E-mail, CRM)
- Feedback Worker - Processa feedback de campo

Bancos de Dados:
- MySQL: staging (ingestão bruta), core (modelo unificado)
- ClickHouse: telemetry.events (eventos e telemetria)
- Redis: Cache de features
- Kafka/Debezium: Eventos CDC

2. csuite-executive (`/csuite-executive`)

Tipo: Córtex Executivo (nível organização)
Porta: 8000 (padrão)
Domínio: csuite.internut.com.br
Função: Agentes executivos (CFO, CEO, COO, CMO, CAIO) que tomam decisões no nível organizacional

Componentes:
- CSuite API (/agents/{org_id}/*, /agents/{org_id}/runs, /alerts, /action-items)
- Agentes Executivos - CFO, CEO, COO, CMO, CAIO
- Scheduler - Execução automática de agentes
- Dashboard Web - Interface de visualização

Bancos de Dados:
- MySQL: csuite_staging (ingestão bruta), csuite (modelo executivo)
- Mesma instância RDS que o 4c: vallery.catmgckfixum.sa-east-1.rds.amazonaws.com

Tabelas Principais:
- csuite.organizations
- csuite.agents
- csuite.agent_runs
- csuite.alerts
- csuite.action_items
- csuite.metric_samples
- csuite.financial_transactions
- csuite.policy_rules

3. 4c-suite (`/4c-suite`)

Tipo: Orquestrador/Integrador
Porta: 8000 (padrão)
Função: Camada fina de orquestração que integra o app 4c (nível cliente) com o app csuite-executive (nível organização)

Componentes:
- API de Orquestração - Consolida visão do organismo
- Endpoint Principal: /organismo/{org_id}/status - Visão consolidada

Dependências:
- Requer 4c rodando (Decision API em http://localhost:8001)
- Requer csuite-executive rodando (CSuite API em http://localhost:8002)

Variáveis de Ambiente:
- FOURC_DECISION_API_URL (padrão: http://localhost:8001)
- CSUITE_API_URL (padrão: http://localhost:8002)

4. csuite-context (`/csuite-context`)

Tipo: API de Contexto
Porta: 8000 (padrão)
Domínio: csuite-context.internut.com.br
Função: Fornece contexto temporal (eventos, tendências, mudanças estruturais)

Endpoints Principais:
- /api/csuite/events - Eventos de curto prazo
- /api/csuite/trends - Tendências de médio prazo
- /api/csuite/shifts - Mudanças estruturais (context shifts)

Jobs Automatizados:
- Detecção de tendências (execução horária recomendada)
- Detecção de context shift (execução diária recomendada)
- Monitoramento de jobs

Bancos de Dados:
- MySQL: csuite (mesma instância RDS)
- Usa as mesmas tabelas do csuite-executive para análise de contexto

5. csuite-sales-manager (`/csuite-sales-manager`)

Tipo: Gerente Virtual de Vendas B2B
Porta: 8001 (Manager API), 8002 (Decision API)
Domínio: sales-manager.internut.com.br, sales-decision.internut.com.br
Função: Sistema de priorização e gestão de tasks para time de vendas B2B

Componentes:
- Manager API (/manager/today, /seller/{seller_id}/today, /tasks/{task_id}/complete) - API principal para gestão de tasks
- Decision API (/4c/decide) - API de decisões 4C Lite (oferta, canal, mensagem, horário)
- Context Jobs (job_refresh_radar.py) - Job que executa refresh do radar de revendas

Características:
- Time de 6 vendedores
- Carteira de ~1.500 revendas (250 por vendedor)
- Canal de revenda (não venda direta)
- Priorização diária de revendas para contato
- Integração com motor 4C Lite (Cliente / Oferta / Jeito / Hora)

Bancos de Dados:
- MySQL: csuite (mesma instância RDS)
- Schemas: csuite (tabelas principais), context_radar (features e tasks)

Tabelas Principais:
- csuite.core_sellers - Vendedores
- csuite.core_revendas - Revendas (carteira)
- core.core_orders - Pedidos por revenda (fonte de verdade)
- core.core_interactions - Contatos (WhatsApp, ligação, visita) (fonte de verdade)
- context_radar.features_revenda_rfr - Features calculadas (recency, frequência, receita, risco)
- context_radar.tasks_seller_day - Lista diária de tasks por vendedor

Nota: As tabelas csuite.core_orders e csuite.core_interactions foram removidas (estavam vazias). Use core.core_orders e core.core_interactions diretamente.

Procedure:
- context_radar.sp_refresh_revenda_radar(IN p_ref_date DATE) - Recalcula features e tasks

Fluxo de Dados e Relações

4C → C-Suite (csuite-executive)

Direção: Micro → Macro
Mecanismo: Sincronização via banco de dados

Dados Sincronizados:
- core.outbox_events → alimenta métricas em csuite.metric_samples
- core.core_feedback → feedback de clientes
- core.core_orders → transações financeiras em csuite.financial_transactions
- core.core_inventory → métricas de estoque

Script de Sincronização:
- Planejado: /scripts/sync_4c_to_csuite.py (execução a cada 5 minutos)

C-Suite → 4C

Direção: Macro → Micro
Mecanismo: Políticas aplicadas via Policy Engine

Dados Sincronizados:
- csuite.policy_rules → alimenta policy_engine do 4C
- Políticas aplicam constraints no /decide:
- Margem mínima
- Limites de contato
- SKUs foco
- Regras de negócio organizacionais

4c-suite (Orquestrador)

Função: Consolida visão de ambos os níveis

Endpoints:
- /organismo/{org_id}/status - Status consolidado:
- Decisões do 4C hoje
- Última decisão do 4C
- Última execução do C-Suite
- Alertas abertos
- Action items pendentes

Comunicação:
- Faz chamadas HTTP para ambos os apps
- GET {CSUITE_API_URL}/dashboard/summary/{org_id}
- GET {CSUITE_API_URL}/monitoring/summary/{org_id}
- GET {FOURC_DECISION_API_URL}/4c-suite/decisions/summary?org_id={org_id}

csuite-context

Função: Análise de contexto temporal

Fonte de Dados:
- Lê de csuite.metric_samples
- Lê de csuite.financial_transactions
- Lê de csuite.agent_runs
- Processa e detecta padrões, tendências e shifts

Consumidores:
- Pode ser consumido por csuite-executive para enriquecer decisões dos agentes
- Pode ser consumido por 4c-suite para contexto adicional

csuite-sales-manager

Função: Gestão de vendas B2B com priorização e decisões 4C Lite

Fonte de Dados:
- Lê de csuite.core_sellers, csuite.core_revendas, core.core_orders, core.core_interactions
- Calcula features em context_radar.features_revenda_rfr (recency, frequência, receita, risco)
- Gera tasks diárias em context_radar.tasks_seller_day

Fluxo:
1. Job refresh-radar executa procedure context_radar.sp_refresh_revenda_radar() diariamente
2. Procedure recalcula features RFR e gera tasks priorizadas por vendedor
3. Manager API expõe tasks para dashboards/front-end
4. Decision API pode enriquecer tasks com decisões 4C Lite (oferta, canal, mensagem)

Integração:
- Usa motor 4C Lite para gerar decisões de contato
- Pode integrar com csuite-executive para políticas de vendas
- Compartilha schema csuite com outros apps executivos

Arquitetura de Bancos de Dados

MySQL (RDS: `vallery.catmgckfixum.sa-east-1.rds.amazonaws.com`)

Schemas do 4C:
- staging - Ingestão bruta (views e staging tables dos sistemas operacionais)
- core - Modelo unificado de cliente/pedidos/inventário/feedback

Schemas do C-Suite:
- csuite_staging - Ingestão bruta de empresas (companies_raw, companies_ready)
- csuite - Modelo executivo (organizations, agents, financial_transactions, metrics, alerts, action_items, policy_rules, core_sellers, core_revendas, core_orders, core_interactions)
- context_radar - Features e tasks do sales manager (features_revenda_rfr, tasks_seller_day)

Conexão:
- Todos os apps usam a mesma instância RDS
- Usuário: core
- Porta: 3306

ClickHouse

telemetry.events - Eventos e telemetria usados pelo 4C e painéis de saúde

Redis

Cache de features por customer_id no Feature Service do 4C

Kafka/Debezium

Eventos CDC: core.core.core_signals, core.core.core_interactions
Usado para invalidar cache de features e alimentar o organismo

Portas e URLs

App	Porta Local	Domínio Produção	Endpoint Principal
4c	8080-8085	-	`/decide`, `/features`, `/score`
csuite-executive	8000	`csuite.internut.com.br`	`/agents/{org_id}/*`
4c-suite	8000	-	`/organismo/{org_id}/status`
csuite-context	8000	`csuite-context.internut.com.br`	`/api/csuite/events`
csuite-sales-manager	8001, 8002	`sales-manager.internut.com.br`, `sales-decision.internut.com.br`	`/manager/today`, `/4c/decide`

Dependências entre Apps

┌─────────────┐
│  4c-suite   │ ← Orquestrador (depende de ambos)
└──────┬──────┘
       │
       ├──────────────┐
       │              │
┌──────▼──────┐  ┌────▼──────────────┐
│     4c      │  │ csuite-executive  │
│ (nível      │  │ (nível            │
│  cliente)   │  │  organização)     │
└──────┬──────┘  └────┬──────────────┘
       │              │
       │              │
       └──────┬───────┘
              │
       ┌──────▼──────┐
       │   MySQL     │ ← Banco compartilhado
       │   (RDS)     │
       └─────────────┘
              │
       ┌──────▼──────┐
       │csuite-context│ ← Lê do mesmo banco
       └─────────────┘
              │
       ┌──────▼──────────────┐
       │csuite-sales-manager │ ← Gerente de vendas B2B
       └─────────────────────┘

Resumo das Relações

4c e csuite-executive são os dois "córtex" principais:
4c: decisões no nível cliente (micro)
csuite-executive: decisões no nível organização (macro)
4c-suite orquestra e consolida a visão de ambos
csuite-context fornece análise de contexto temporal baseada nos dados do C-Suite
csuite-sales-manager fornece gestão de vendas B2B com priorização de tasks e decisões 4C Lite
Todos compartilham o mesmo banco MySQL (RDS), mas usam schemas diferentes:
4c: staging, core
C-Suite: csuite_staging, csuite
A comunicação entre 4c e C-Suite é principalmente via banco de dados:
4C → C-Suite: métricas e eventos
C-Suite → 4C: políticas e regras

Relacao Entre Apps

Relação entre os 5 Apps do C-Suite

Visão Geral

Os 5 Apps

1. 4c (`/4c`)

2. csuite-executive (`/csuite-executive`)

3. 4c-suite (`/4c-suite`)

4. csuite-context (`/csuite-context`)

5. csuite-sales-manager (`/csuite-sales-manager`)

Fluxo de Dados e Relações

4C → C-Suite (csuite-executive)

C-Suite → 4C

4c-suite (Orquestrador)

csuite-context

csuite-sales-manager

Arquitetura de Bancos de Dados

MySQL (RDS: `vallery.catmgckfixum.sa-east-1.rds.amazonaws.com`)

ClickHouse

Redis

Kafka/Debezium

Portas e URLs

Dependências entre Apps

Resumo das Relações

🔊 Text-to-Speech

Relação entre os 5 Apps do C-Suite

Visão Geral

Os 5 Apps

1. 4c (/4c)

2. csuite-executive (/csuite-executive)

3. 4c-suite (/4c-suite)

4. csuite-context (/csuite-context)

5. csuite-sales-manager (/csuite-sales-manager)

Fluxo de Dados e Relações

4C → C-Suite (csuite-executive)

C-Suite → 4C

4c-suite (Orquestrador)

csuite-context

csuite-sales-manager

Arquitetura de Bancos de Dados

MySQL (RDS: vallery.catmgckfixum.sa-east-1.rds.amazonaws.com)

ClickHouse

Redis

Kafka/Debezium

Portas e URLs

Dependências entre Apps

Resumo das Relações

🔊 Text-to-Speech

1. 4c (`/4c`)

2. csuite-executive (`/csuite-executive`)

3. 4c-suite (`/4c-suite`)

4. csuite-context (`/csuite-context`)

5. csuite-sales-manager (`/csuite-sales-manager`)

MySQL (RDS: `vallery.catmgckfixum.sa-east-1.rds.amazonaws.com`)