🏗️ Arquitetura do C-Suite - Diagrama Completo

Este documento apresenta a arquitetura visual completa do ecossistema C-Suite, mostrando todos os 5 apps, suas relações, fluxos de dados e schemas de banco.

Diagrama de Arquitetura Geral

graph TB
    subgraph "Nível Cliente (Micro)"
        APP_4C[4c App<br/>Córtex Comercial<br/>Porta: 8080-8085]

        subgraph "Serviços 4C"
            FS["Feature Service<br/>/features/customer"]
            SS["Scoring Service<br/>/score/*"]
            DA["Decision API<br/>/decide"]
            EX["Executor<br/>WhatsApp/Email/CRM"]
            FW[Feedback Worker]
        end

        APP_4C --> FS
        FS --> SS
        SS --> DA
        DA --> EX
        EX --> FW
    end

    subgraph "Nível Organização (Macro)"
        APP_CSUITE[csuite-executive<br/>Córtex Executivo<br/>Porta: 8000<br/>csuite.internut.com.br]

        subgraph "Componentes C-Suite"
            CAPI["CSuite API<br/>/agents/*"]
            AGENTS["Agentes: CFO/CEO/COO/CMO/CAIO"]
            SCHED[Scheduler]
            DASH[Dashboard Web]
        end

        APP_CSUITE --> CAPI
        CAPI --> AGENTS
        AGENTS --> SCHED
        CAPI --> DASH
    end

    subgraph "Orquestração"
        APP_4CSUITE[4c-suite<br/>Orquestrador<br/>Porta: 8000<br/>/organismo/*]
    end

    subgraph "Contexto e Análise"
        APP_CONTEXT[csuite-context<br/>API de Contexto<br/>Porta: 8000<br/>csuite-context.internut.com.br]

        subgraph "Endpoints Context"
            EVENTS["/api/csuite/events"]
            TRENDS["/api/csuite/trends"]
            SHIFTS["/api/csuite/shifts"]
        end

        APP_CONTEXT --> EVENTS
        APP_CONTEXT --> TRENDS
        APP_CONTEXT --> SHIFTS
    end

    subgraph "Gestão de Vendas"
        APP_SALES[csuite-sales-manager<br/>Gerente de Vendas B2B<br/>Porta: 8001/8002]

        subgraph "Componentes Sales Manager"
            MAPI["Manager API<br/>/manager/today"]
            DAPI["Decision API<br/>/4c/decide"]
            JOB["Context Jobs<br/>refresh-radar"]
        end

        APP_SALES --> MAPI
        APP_SALES --> DAPI
        APP_SALES --> JOB
    end

    subgraph "Bancos de Dados"
        subgraph "MySQL RDS"
            DB_STAGING[(staging<br/>Ingestão bruta 4C)]
            DB_CORE[(core<br/>Modelo unificado 4C)]
            DB_CSUITE_STAGING[(csuite_staging<br/>Ingestão bruta)]
            DB_CSUITE[(csuite<br/>Modelo executivo)]
            DB_RADAR[(context_radar<br/>Features e tasks)]
        end

        DB_REDIS[(Redis<br/>Cache de features)]
        DB_CLICKHOUSE[(ClickHouse<br/>telemetry.events)]
        DB_KAFKA[(Kafka/Debezium<br/>Eventos CDC)]
    end

    %% Fluxos de dados 4C
    FS --> DB_REDIS
    FS --> DB_CORE
    SS --> DB_CORE
    DA --> DB_CORE
    EX --> DB_CORE
    FW --> DB_CLICKHOUSE
    FW --> DB_KAFKA

    %% Fluxos C-Suite
    CAPI --> DB_CSUITE
    AGENTS --> DB_CSUITE
    SCHED --> DB_CSUITE

    %% Fluxos Context
    APP_CONTEXT --> DB_CSUITE

    %% Fluxos Sales Manager
    MAPI --> DB_CSUITE
    MAPI --> DB_RADAR
    DAPI --> DB_CSUITE
    DAPI --> DB_RADAR
    JOB --> DB_CSUITE
    JOB --> DB_RADAR

    %% Orquestração
    APP_4CSUITE --> APP_4C
    APP_4CSUITE --> APP_CSUITE

    %% Sincronização 4C → C-Suite
    DB_CORE -.->|outbox_events| DB_CSUITE
    DB_CORE -.->|core_orders| DB_CSUITE
    DB_CORE -.->|core_feedback| DB_CSUITE

    %% Políticas C-Suite → 4C
    DB_CSUITE -.->|policy_rules| DA

    %% Estilo
    classDef appStyle fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
    classDef dbStyle fill:#50C878,stroke:#2D8659,stroke-width:2px,color:#fff
    classDef serviceStyle fill:#FFB84D,stroke:#CC8A3D,stroke-width:2px,color:#000

    class APP_4C,APP_CSUITE,APP_4CSUITE,APP_CONTEXT,APP_SALES appStyle
    class DB_STAGING,DB_CORE,DB_CSUITE_STAGING,DB_CSUITE,DB_RADAR,DB_REDIS,DB_CLICKHOUSE,DB_KAFKA dbStyle
    class FS,SS,DA,EX,FW,CAPI,AGENTS,MAPI,DAPI serviceStyle

Diagrama de Fluxo de Dados Detalhado

📊 Para diagramas de sequência mais detalhados, consulte DIAGRAMAS_SEQUENCIA.md

sequenceDiagram
    participant User as Usuário/Vendedor
    participant Sales as Sales Manager
    participant 4C as 4C Decision API
    participant Exec as Executor
    participant CSuite as C-Suite Executive
    participant Org as 4c-suite
    participant DB as MySQL RDS

    Note over Sales,DB: Fluxo: Geração de Task e Decisão

    Sales->>DB: Job refresh-radar executa<br/>sp_refresh_revenda_radar()
    DB-->>Sales: Features calculadas<br/>Tasks geradas

    User->>Sales: "GET /seller/{id}/today"
    Sales->>DB: Busca tasks do vendedor
    DB-->>Sales: Lista de tasks

    alt Task precisa de decisão 4C
        Sales->>4C: POST /4c/decide<br/>{revenda_id}
        4C->>DB: Busca features do cliente
        DB-->>4C: Features RFR
        4C->>4C: Calcula scores ML
        4C-->>Sales: Decisão (oferta, canal, mensagem)
        Sales->>DB: Atualiza task com decision_payload
    end

    Sales-->>User: Tasks com decisões

    Note over User,Exec: Fluxo: Execução de Ação

    User->>Exec: Executa ação (WhatsApp)
    Exec->>DB: Registra interação
    Exec->>DB: Cria evento outbox

    Note over DB,CSuite: Fluxo: Sincronização 4C → C-Suite

    DB->>CSuite: Script sync lê outbox_events
    CSuite->>DB: Insere em metric_samples
    CSuite->>DB: Insere em financial_transactions

    Note over CSuite,Org: Fluxo: Orquestração

    Org->>4C: "GET /4c-suite/decisions/summary"
    4C-->>Org: Métricas de decisões

    Org->>CSuite: "GET /dashboard/summary/{org_id}"
    CSuite-->>Org: Dashboard consolidado

    Org-->>User: Status do organismo

Diagrama de Schemas de Banco de Dados

erDiagram
    %% Schema: staging (4C)
    staging_customers ||--o{ staging_orders : "tem"
    staging_orders ||--o{ staging_order_items : "contém"

    %% Schema: core (4C)
    core_customers ||--o{ core_orders : "tem"
    core_orders ||--o{ core_order_items : "contém"
    core_customers ||--o{ core_interactions : "tem"
    core_customers ||--o{ core_feedback : "tem"
    core_customers ||--o{ core_signals : "gera"
    core_orders ||--o{ core_outbox_events : "gera"
    core_interactions ||--o{ core_outbox_events : "gera"

    %% Schema: csuite_staging
    csuite_staging_companies_raw ||--|| csuite_staging_companies_ready : "processa"

    %% Schema: csuite
    csuite_organizations ||--o{ csuite_agents : "tem"
    csuite_organizations ||--o{ csuite_metric_samples : "gera"
    csuite_organizations ||--o{ csuite_financial_transactions : "tem"
    csuite_organizations ||--o{ csuite_policy_rules : "define"
    csuite_agents ||--o{ csuite_agent_runs : "executa"
    csuite_agent_runs ||--o{ csuite_alerts : "gera"
    csuite_agent_runs ||--o{ csuite_action_items : "cria"

    %% Schema: csuite (Sales Manager)
    csuite_core_sellers ||--o{ csuite_core_revendas : "gerencia"
    csuite_core_revendas ||--o{ csuite_core_orders : "tem"
    csuite_core_revendas ||--o{ csuite_core_interactions : "tem"

    %% Schema: context_radar
    context_radar_features_revenda_rfr ||--o{ context_radar_tasks_seller_day : "gera"
    csuite_core_sellers ||--o{ context_radar_tasks_seller_day : "atribui"
    csuite_core_revendas ||--o{ context_radar_tasks_seller_day : "referencia"

    %% Relações entre schemas
    core_orders ||--|| csuite_financial_transactions : "sincroniza"
    core_outbox_events ||--|| csuite_metric_samples : "alimenta"
    csuite_policy_rules ||--|| core_customers : "aplica"

    %% Entidades principais
    core_customers {
        int customer_id PK
        string name
        string phone
        datetime created_at
    }

    core_orders {
        int order_id PK
        int customer_id FK
        decimal total_value
        datetime order_date
    }

    core_outbox_events {
        int event_id PK
        string event_type
        json payload_json
        datetime created_at
    }

    csuite_organizations {
        int org_id PK
        string name
        datetime created_at
    }

    csuite_agents {
        int agent_id PK
        int org_id FK
        string agent_type
        string name
    }

    csuite_metric_samples {
        int sample_id PK
        int org_id FK
        string metric_key
        decimal metric_value
        datetime sampled_at
    }

    csuite_policy_rules {
        int rule_id PK
        int org_id FK
        string rule_type
        string rule_key
        json rule_value
        boolean enabled
    }

    csuite_core_sellers {
        int seller_id PK
        string name
        string email
    }

    csuite_core_revendas {
        int revenda_id PK
        int seller_id FK
        string nome
        string cidade
        string estado
    }

    context_radar_features_revenda_rfr {
        int revenda_id PK
        int recency_days
        int freq_90d
        decimal revenue_90d
        decimal score_rfr
        string class_risco
        string class_valor
    }

    context_radar_tasks_seller_day {
        int task_id PK
        date ref_date
        int seller_id FK
        int revenda_id FK
        string prioridade
        string tipo_acao
        string motivo
        string status
        json decision_payload
    }

Diagrama de Comunicação entre Apps

graph LR
    subgraph "Apps Principais"
        A[4c]
        B[csuite-executive]
        C[4c-suite]
        D[csuite-context]
        E[csuite-sales-manager]
    end

    subgraph "Comunicação HTTP"
        C -->|"GET /4c-suite/decisions/summary"| A
        C -->|"GET /dashboard/summary"| B
        C -->|"GET /monitoring/summary"| B
        E -->|"POST /4c/decide"| A
    end

    subgraph "Comunicação via Banco"
        A -.->|outbox_events| B
        A -.->|core_orders| B
        B -.->|policy_rules| A
        A -.->|core_*| D
        B -.->|csuite.*| D
        E -.->|csuite.*| B
        E -.->|context_radar.*| B
    end

    subgraph "Comunicação via Eventos"
        A -->|Kafka events| B
        A -->|Kafka events| D
    end

    style A fill:#4A90E2
    style B fill:#50C878
    style C fill:#FFB84D
    style D fill:#9B59B6
    style E fill:#E74C3C

Diagrama de Portas e Domínios

graph TB
    subgraph "Desenvolvimento Local"
        L4C[4c<br/>localhost:8080-8085]
        LCS[csuite-executive<br/>localhost:8000]
        L4CS[4c-suite<br/>localhost:8000]
        LCTX[csuite-context<br/>localhost:8000]
        LSALES[csuite-sales-manager<br/>localhost:8001/8002]
    end

    subgraph "Produção (Traefik)"
        PCS[csuite.internut.com.br<br/>:443]
        PCTX[csuite-context.internut.com.br<br/>:443]
        PSALES1[sales-manager.internut.com.br<br/>:443]
        PSALES2[sales-decision.internut.com.br<br/>:443]
    end

    subgraph "Rede Interna Docker Swarm"
        DCS[csuite-api:8000]
        DCTX[csuite-context-api:8000]
        DSALES1[sales-manager-api:8000]
        DSALES2[sales-decision-api:8000]
    end

    PCS --> DCS
    PCTX --> DCTX
    PSALES1 --> DSALES1
    PSALES2 --> DSALES2

    style L4C fill:#E8F4F8
    style LCS fill:#E8F4F8
    style L4CS fill:#E8F4F8
    style LCTX fill:#E8F4F8
    style LSALES fill:#E8F4F8
    style PCS fill:#D4EDDA
    style PCTX fill:#D4EDDA
    style PSALES1 fill:#D4EDDA
    style PSALES2 fill:#D4EDDA

Legenda e Convenções

Cores dos Apps

🔵 Azul (4c): Córtex comercial, nível cliente
🟢 Verde (csuite-executive): Córtex executivo, nível organização
🟡 Amarelo (4c-suite): Orquestrador
🟣 Roxo (csuite-context): Análise de contexto
🔴 Vermelho (csuite-sales-manager): Gestão de vendas

Tipos de Comunicação

Linha sólida (→): Comunicação HTTP/REST síncrona
Linha tracejada (-.->): Comunicação via banco de dados
Linha pontilhada (-->>): Resposta/retorno

Schemas de Banco

staging/core: Dados do 4C (nível cliente)
csuite_staging/csuite: Dados executivos (nível organização)
context_radar: Features e tasks do sales manager

Notas de Arquitetura

Princípios de Design

Separação de Responsabilidades
4c: Decisões no nível cliente (micro)
csuite-executive: Decisões no nível organização (macro)
4c-suite: Orquestração e visão consolidada
Comunicação Assíncrona
Eventos via Kafka/Debezium para desacoplamento
Outbox pattern para garantia de entrega
Banco de Dados Compartilhado
Todos os apps usam a mesma instância RDS
Schemas separados por domínio
Sincronização via scripts/jobs
API Gateway (Traefik)
Roteamento baseado em host
SSL/TLS automático (Let's Encrypt)
Load balancing

Pontos de Atenção

⚠️ Sincronização 4C → C-Suite: Script sync_4c_to_csuite.py ainda não implementado

⚠️ Policy Engine: Políticas do C-Suite não estão sendo aplicadas no 4C

⚠️ Service Discovery: URLs hardcoded em alguns lugares

Última atualização: 2025-12-01