CORTEX — Mapa do Ecossistema

Versão: 1.14.0 · Data: 2026-09-24 · Status: Em evolução · Owner: Plataforma Caminho canônico: cortex-docs/ECOSYSTEM.md Documentos irmãos: cortex-docs/standards/UNISCALE_ENGINEERING_STANDARDS.md (padrões técnicos e de nomenclatura) · cortex-docs/architecture/RAG_AND_INGESTION.md (RAG e ingestão vetorial)

Este documento é o mapa do ecossistema CORTEX: quais projetos existem, o que cada um faz, de quem é cada dado, e onde os projetos se conversam. Ele é a fonte da verdade sobre fronteiras e integrações. Não repete os padrões técnicos — esses vivem no documento irmão.

Os fluxos de negócio detalhados (caminho a caminho, com erros) vivem em documentos próprios de fluxo e são referenciados aqui, não embutidos.

1. Por que o CORTEX existe

Hoje a informação da instituição está dispersa entre plataformas terceiras que não se conversam (acadêmico no jacad, CRM no bitrix24, pagamento em gateway, tráfego em meta/google). Levantar um dado exige tocar em muitos lugares e pessoas. Isso trava a tomada de decisão.

O CORTEX existe para ser o dono da verdade consolidada do negócio — orquestrando essas plataformas, capturando o que acontece, e centralizando informação tratada num lugar só. Ele não substitui as plataformas homologadas/legadas onde isso não faz sentido (notadamente o jacad); ele as integra e consolida.

Princípio de propriedade (Obrigatório): o CORTEX é dono de tudo, com uma exceção — a verdade acadêmica formal (cadastro, contrato, notas, financeiro de mensalidade) pertence ao jacad, por ser plataforma homologada no MEC. Conhecer o lead/aluno e tudo ao redor é responsabilidade do CORTEX; a verdade do registro acadêmico é do jacad.

2. O conceito central: cadastrar → configurar → oferecer → vender → tratar

Todo o ecossistema gira em torno de um ciclo de vida da venda. Entender esse ciclo é entender o CORTEX.

• Cadastrar / Configurar — o institutional-service é onde os times definem produtos, preços, lotes, descontos, a tradução para IDs de terceiros (jacad), e a topologia do CRM. É a camada onde moram as regras que os terceiros não comportam.
• Oferecer — o ai-sales recebe essa configuração distribuída, resolve qual oferta vale para aquele lead/contexto, e conduz a conversa.
• Vender — o ai-sales negocia dentro de margens autorizadas e fecha o acordo.
• Tratar — payment-service cobra, order-service cumpre o que foi vendido (matrícula e entrega de acesso), connectors fazem a ponte com terceiros, e o cortex-service consolida tudo no core.

O padrão estrutural que se repete em todo o ecossistema: o institutional-service configura a regra; a configuração é distribuída para os executores; os executores agem sem conhecer a regra — apenas aplicam o que receberam. O tracking não decide qual raia do CRM, aplica o mapa do institutional. O sales não inventa preço, aplica o lote. O order-service não traduz, usa os IDs já prontos. Executor é "burro"; a regra mora no institutional. Esse princípio mantém o ecossistema governável e desacoplado dos terceiros.

3. Glossário de fronteira — de quem é cada coisa

Notas de fronteira:

• O bitrix24 não é dono da trilha do lead — ele é a janela de gestão/acompanhamento (CRM). A trilha real é capturada pelo CORTEX (gtag) e vive no tracking. O bitrix recebe um card por lead, alimentado por eventos do CORTEX.
• O jacad tem API de escrita — o CORTEX comanda matrícula por ela. Mas a verdade do contrato resultante continua sendo do jacad. O academic-connector é mão-dupla.
• O lead aparece por vários pontos (LP, IA, …), mas o lead_id é cunhado num lugar só — o tracking (berço único). O identity-service é a peça que costura "é a mesma pessoa" e "por onde passou".

4. Catálogo de serviços

Todos os serviços têm banco próprio. Os de IA têm banco vetorial (Qdrant) além do SQL. A fundação comum (chamada de LLM, RAG, publicação em fila, log, resolução de identidade) vive em cortex-shared para não repetir código.

Serviços de plataforma

institutional-service — portal com front. A porta visual e ferramental entre os times/clientes e o CORTEX. Dono da regra comercial (produtos, lotes, preços, descontos, alçadas), da tradução para IDs de terceiros, da topologia do CRM (pipes, raias, mapa estado→raia), e cockpit de atendimento humano (alvo). Gerencia também produtos extras na fase inicial (sem pós-venda rico — ver §7). É também o registro de tenants do ecossistema, distribuído por fato (institutional.tenant.*) — quem amarra qual propriedade digital pertence a qual tenant. Regras detalhadas: cortex-docs/services/INSTITUTIONAL_SERVICE.md.

identity-service — dono de quem é a pessoa (lead → aluno, ao longo da jornada) e da trilha de presença (por onde passou: registra que passou pela wallet/sales, não o que fez lá). Cunha o person_id — mas só quando a identificação por PII chega (navegação anônima tem lead_id, não pessoa): o lead anônimo fica num registro à parte, sem person_id, e vira pessoa (nome, email, telefone, documento) quando um sinal identificador chega; um person_id amarra os N lead_id da mesma pessoa. Porta única de "quem é esse / por onde passou": consultado direto/síncrono para leitura; escrito só por fila (consome fatos — nunca escrita externa direta). Matching por confiança (≥90% = mesma pessoa; abaixo, trata como novo, enriquece em background, nunca interroga) e funde quando um sinal posterior revela alguém que já existia. Não fica exposto à internet pública. Não guarda comportamento (é do tracking) nem o contexto rico de cada serviço (fica na fonte). Regras detalhadas: cortex-docs/services/IDENTITY_SERVICE.md.

tracking-service — berço do lead e dono do comportamento. Ponto único de nascimento: na primeira ação monitorada (LP, formulário, click, read doc…), de qualquer origem e mesmo anônima, cunha o lead_id — identificador de origem de navegação, não de pessoa (o handle de pessoa é o person_id, cunhado pelo identity na identificação; fora do par tracking/identity os serviços falam person_id). Dono do comportamento (trilha de navegação, tráfego/gtag, alto volume) e do contexto por evento (sessão, ip, geo, device, utm), pseudônimo, chaveado por lead_id. Dispara o card no bitrix no nascimento. É também a borda de ingestão exposta — absorve a captura, não há capture-service à parte: recebe eventos e formulários, persiste antes de ackar e encaminha só a fatia de PII ao identity por fato (com retry, ver §5); não armazena PII. Fica exposto porque comportamento é pseudônimo (relaxe consciente do princípio de borda; a PII vai pro identity murado). Não diz quem a pessoa é (isso é do identity). Regras detalhadas: cortex-docs/services/TRACKING_SERVICE.md.

payment-service — dono da transação e da cobrança. Recebe do sales o valor e os campos a coletar já prontos — cobra sem saber o que é (em lógica). Hospeda o checkout (link stateful e idempotente) e o formulário pós-checkout. Opera síncrono (cartão) e assíncrono (PIX/webhook); a confirmação real é sempre o fato payment.transaction.confirmed. Usa um payment-connector por gateway. Regras detalhadas: cortex-docs/services/PAYMENT_SERVICE.md.

order-service — dono do pós-venda. Executor por receita, conforme o atributo do produto: matrícula no jacad ou entrega de acesso via connector de terceira (curso online/presencial). Dono do estado da saga e da retentativa/erro. Emissão fiscal (NF) está fora do escopo (§7). (Renomeado: enrollment → fulfillment-service → order-service.)

cortex-service — o core consolidado. Repositório único com duas responsabilidades internas: ingestão (consome a fila, grava no core com linhagem) e consulta (expõe rotas de leitura). Entrada do core é sempre por fila. As IAs internas dos times (ai-cortex) consultam o core através dele.

storage-service — dono do controle de objetos binários (arquivos), não do byte. Sobre um bucket alugado (S3/MinIO, buy), é a casca de governança (make): dono da object_key opaca, do metadado, da permissão de acesso e do fato de objeto guardado. Não faz proxy do byte — autoriza upload e leitura por URL assinada (PUT/GET direto no bucket) e registra; o byte nunca transita pelo serviço. Ciclo pending→committed (commit = única verdade de que o arquivo existe). Publica o fato de objeto guardado; o conteúdo é vetorizado por quem consome o fato (worker de ingestão do domínio → embedding-service), não por ele. Banco próprio de metadado, sem banco vetorial. Regras detalhadas: cortex-docs/services/STORAGE_SERVICE.md.

messaging-service — (Recomendado — opcional; não adotado na fundação atual.) Gerenciador da entrega, não dono do conteúdo: cuidaria de como/quando/onde/se a mensagem chega ao canal e do estado de entrega (quem recebeu o quê e quando, status, opt-out, ritmo por número, janela de 24h, template, demux de 1 webhook → N IAs, roteamento privado→oficial) — não o diálogo (esse é da orquestradora, ver §5). Centralizaria a mecânica de entrega por trás dos *-connectors de canal. Por decisão de arquitetura atual (diretor técnico), essas responsabilidades de canal ficam no(s) *-connector(s) de canal, e o CORTEX não centraliza números/dados/status de canal. O messaging-service permanece documentado como recomendação para concentrar esses concerns numa fronteira só — ver a nota de recomendação logo abaixo (valor e risco de não tê-lo).

Nota de recomendação — messaging-service. Centralizar a entrega num serviço próprio protege contra problemas que, distribuídos nos connectors/IAs, tendem a reaparecer: opt-out num lugar só (sem ele, uma IA pode mandar para quem pediu para parar → multa LGPD + risco de ban do número pela Meta); ritmo por número (várias IAs no mesmo número sem sequenciamento → ban → venda parada); demux de um webhook para N IAs (sem ele, um número por IA → mais custo e cliente confuso); dedup de evento reenviado; proibir fallback de privado → não-oficial (vazamento de PII). Na decisão atual, esses controles passam a ser responsabilidade de cada connector de canal — e, se não forem implementados lá, viram risco operacional e legal. Registrado como recomendação para constar.

Serviços de IA

ai-orchestrator — IA orquestradora de conversa. Toda conversa entra por ela: recebe a mensagem do usuário (via messaging-service, ver §5), entende a intenção e decide qual IA especializada deve atuar (ai-sales, ai-secretary, ai-wallet, …), roteando o turno e mantendo a costura entre especializadas quando uma conversa atravessa domínios. É dona do diálogo completo com o usuário — o transcript inteiro da conversa, atravessando todas as especializadas, vive no orchestrator_db (contexto geral). Suas únicas responsabilidades são essas duas: rotear e manter a conversa. É executor de roteamento, não de regra: não vende, não consulta contrato, não qualifica — delega. Não tem banco vetorial (não faz RAG — quem busca conhecimento é a especializada, via embedding-service). A especializada produz a resposta e devolve à orquestradora (não ao canal); a orquestradora atualiza o diálogo e entrega ao messaging-service para a saída.

ai-sales — IA comercial. Recebe o lead (com identidade resolvida), resolve a oferta/lote vigente da config local distribuída pelo institutional, conduz a conversa, negocia dentro de margem com limitador, e fecha o acordo. Tem fallbacks (PIX expirado, form abandonado) e escala para humano quando esgota.

ai-wallet — IA de qualificação. Via opcional (não está no caminho obrigatório do funil): oferece conteúdo gratuito e comunidade, o lead pontua e se qualifica. Quem passa por ela chega mais quente ao sales. O sales puxa esse contexto da fonte, com moderação (usa de bastidor, não escancara).

ai-secretary — IA para alunos: dados do próprio contrato (notas, boletos, faltas). Servirá também o futuro APP LMS da instituição.

ai-cortex — não é uma IA única, e sim o nome agregador das IAs internas dos times (financeira, marketing, comercial interna e a consulta de diretoria — dashboards/relatórios dinâmicos sobre o core). São várias IAs especialistas que atendem colaboradores, não o cliente final, e leem o negócio via cortex-service. (Escopo de cada uma a definir.)

ai-teacher — IA para alunos e professores. Escopo a definir.

Infraestrutura de IA

embedding-service — provedor de embeddings do ecossistema (hoje modelo BGE-M3, 1024d). É o único lugar que conhece o modelo de embedding: faz só texto → vetor, tanto na consulta (a IA especializada manda texto, recebe o vetor e ela mesma busca no seu Qdrant) quanto na ingestão (devolve o vetor do que o institutional-service configura para as especializadas). É enforcer do invariante (query e índice no mesmo espaço), não roteador de destino: não escreve no Qdrant e não busca — quem grava os vetores é o worker de ingestão de cada domínio (<domain>-ingestion-worker), via outbox transacional. É um gateway sem dono de dado (mesma filosofia dos connectors): não tem banco; o mapa collection → modelo → dim é configuração de plataforma (hoje hardcoded em BGE-M3). As collections Qdrant seguem pertencendo a cada domínio de IA (UNISCALE §26). Trocar BGE-M3 por outro modelo é mudança em um lugar só — e, por collection ser amarrada ao modelo (UNISCALE §26.1), implica nova collection, nunca sobrescrita. Encapsula o modelo como o payment-service encapsula o gateway: o consumidor pede embedding sem saber qual modelo o produziu. Desenho detalhado (RAG, ingestão, consistência): cortex-docs/architecture/RAG_AND_INGESTION.md.

Connectors

Connectors são mão-dupla por construção e sem banco (são tradutores, não donos de dado; estado de negócio vive nos serviços). Consomem fila (para empurrar fatos a terceiros) e expõem chamada direta (para responder consultas na hora). Regras detalhadas: cortex-docs/services/CONNECTORS.md.

• academic-connector — mão-dupla real com o jacad. Lê (cadastro, contrato) e escreve (matrícula). jacad é autoridade.
• crm-connector — empurra eventos do CORTEX que nascem e movem cards no CRM (hoje bitrix24). Nome por domínio, não por fornecedor — troca de CRM é troca do connector, não rebranding do contrato.
• payment-connector — um por gateway. Gateway é substituível; o payment-service orquestra.
• marketing-connector — unifica meta e google. Puxa dados de campanha e recebe eventos de conversão de volta (compra, etc.) para otimização. Tráfego pago tratado por domínio, não por fornecedor.
• whatsapp-connector — mão-dupla com a API do WhatsApp (Meta). Por decisão atual absorve a governança de canal (entrega, opt-out, ritmo por número, status, demux) — o messaging-service que a centralizaria é recomendado, não adotado (§4/§7). É o único connector de canal real hoje. Forma exata em definição (ver §7).
• telegram-connector / discord-connector / teams-connector — connectors de canal futuros. Entram pela camada de entrega de canal (o connector hoje; o messaging-service se/quando adotado), mesmo padrão do whatsapp-connector e do payment-connector por gateway.

5. Comunicação — três canais independentes

A escolha do canal é por necessidade da ação, não por um destino fixo.

1. Core — sempre por fila. O cortex-service só recebe registro via fila (RabbitMQ), sem negociação. É a única entrada do core.
2. Filas internas de serviço — por necessidade. Um serviço pode ter filas próprias quando a ação exige orquestração temporal, fallback ou etapas dependentes (não tem relação com o core).
3. Chamadas diretas serviço ↔ serviço/connector — assíncronas por padrão. Síncronas só quando há dependência de resultado (ex.: paid antes de refund). É como o sales pergunta ao identity "quem é esse", ou consulta um connector.

Publish/subscribe é a espinha do desacoplamento. Um serviço publica um fato genérico uma vez no exchange (topic). Cada interessado tem sua própria fila e consome independentemente — core (consolida), meta/google (conversão), bitrix (move card) podem consumir o mesmo fato. O serviço publicador não sabe quem ouve. Trocar de CRM, adicionar um destino, plugar o marketplace futuro — tudo é mexer no lado dos consumidores, nunca no publicador. Connector novo = fila nova no exchange.

Contexto rico é puxado na fonte (não consolidado para servir ao vivo). Quando o sales quer o contexto do lead que passou pela wallet, ele resolve o ID no identity e puxa o contexto direto da wallet. O core consolida para análise/decisão (diretoria), não para servir contexto em tempo real.

Configuração é distribuída e versionada, consumida localmente. O institutional não é consultado em tempo real pelo sales. A config (produtos, lotes, prompts base, IDs jacad, mapa de CRM) é distribuída e versionada; o sales mantém cópia local e opera sobre ela. Se o institutional cair, as vendas seguem. (Mecanismo exato de distribuição: a definir.)

Status do messaging-service nesta seção (decisão atual). O messaging-service é recomendado, não adotado (§4). Na fundação atual, a camada de entrega é o *-connector de canal: onde os parágrafos abaixo dizem messaging-service, leia "a camada de entrega — o connector de canal hoje; o messaging-service se/quando adotado". Os concerns de centralização (demux, opt-out, ritmo, status) ficam, por decisão, no connector — com as ressalvas da nota de recomendação (§4).

Mensageria de saída é encapsulada (Opção A). As IAs (ai-sales, ai-secretary, ai-wallet) decidem o que dizer e a quem dizer, e entregam ao messaging-service. Como a mensagem chega ao usuário (API do canal, token, janela de 24h, template, fila do connector) é responsabilidade do messaging-service e dos *-connectors de canal — a IA não sabe e não precisa saber. Toda a volatilidade dos canais (mudanças da Meta no WhatsApp, entrada de Telegram/Discord/Teams) fica isolada de quem produz a conversa. Mesma lógica do payment-service cobrando sem saber o que vendeu.

Entrada de conversa é simétrica à saída, e o diálogo tem três donos distintos. O inbound do usuário chega pelo canal → connector → messaging-service (que gerencia a entrega, indiferente ao conteúdo) → ai-orchestrator. A orquestradora entende a intenção e decide qual IA especializada atua; a especializada trata o turno e devolve a resposta à orquestradora — não ao canal. A orquestradora atualiza o diálogo e manda o messaging-service entregar. O loop é messaging → orchestrator → especializada → orchestrator → messaging. Os três planos:

• messaging-service — gerência de entrega (como/quando/onde/se), indiferente ao texto.
• ai-orchestrator — dono do diálogo completo (transcript com o usuário, atravessando domínios). Roteia e mantém a conversa; sem regra de negócio.
• IA especializada — dona da sua fatia do diálogo (o que a orquestradora lhe entregou + o que respondeu) e do estado de negócio da sua tarefa (vendeu/não, oferta, objeção, quando, para quem), além do RAG. A regra continua no institutional, distribuída às especializadas.

Busca semântica passa pelo embedding-service. Quando uma IA especializada precisa de conhecimento (RAG), ela manda o texto ao embedding-service, recebe o vetor e busca na sua collection Qdrant; o embedding-service é o único que conhece o modelo (BGE-M3). A configuração do institutional destinada às especializadas também é vetorizada por ele na ingestão. O ai-orchestrator não faz RAG — não tem banco vetorial; quem busca conhecimento é a especializada.

Nascimento e captura do lead. A primeira ação monitorada (qualquer origem, mesmo anônima) faz o tracking cunhar o lead_id e publicar o fato de nascimento (chave de matching + sinais permitidos) → o identity consome e registra o lead anônimo — sem person_id, que só é cunhado na identificação por PII. Cada serviço escreve o seu banco: o identity se popula consumindo fatos, nunca por escrita externa. À medida que dados identificadores chegam (formulário, telefone do WhatsApp via messaging/orquestradora, pagamento, connector), quem capturou publica o fato → o identity resolve/funde o "quem é". A leitura "quem é esse lead_id?" é síncrona. A regra anti-redundância: PII e matching no identity; comportamento e contexto-por-evento no tracking — não se duplica o contexto cru de evento no identity.

Captura durável (formulário de terceiro). O formulário da LP é de terceiro — o CORTEX não controla seu aceite/retry, então o instante do recebimento é a única chance. Regra: persistir-antes-de-ackar — o tracking grava a fatia de PII num inbox cifrado e só então confirma; um worker em background (dentro do próprio tracking, sem pod novo) drena pro identity com retry + backoff. Nunca "n tentativas e dropa pro log" (isso perde o lead): o registro durável fica até entregar; pior caso vai pra DLQ retido para inspeção, nunca descartado. É o outbox do RAG_AND_INGESTION §5 aplicado na borda. Consequência aceita e forçada pelo form de terceiro: a PII fica em repouso cifrada por segundos na borda — mitigada por TTL curto + apagar após a confirmação.

6. Plataformas externas

Dois fluxos de pagamento distintos e não sobrepostos: mensalidade acadêmica roda pelo gateway interno do jacad; todo o resto (extensão, futuros produtos) roda pelo gateway externo via payment-service.

7. Fronteiras adiadas conscientemente

Decisões deliberadamente não fechadas agora — registradas para entrarem como pacotes futuros, validando contra esta fundação.

• Governança de canal e forma do whatsapp-connector — por decisão de arquitetura atual, a governança de canal (entrega, opt-out, ritmo por número, status, demux) fica no(s) *-connector(s) de canal; o messaging-service que centralizaria esses concerns é recomendado, não adotado (§4, com nota de valor/risco). A forma exata do whatsapp-connector segue dependendo de definições da Meta sobre WhatsApp Business + tráfego pago (template, janela de 24h, disparo) e evolui conforme ela amadurece. Se/quando a centralização for adotada, o messaging-service entra como serviço de primeira classe sem alterar os connectors.
• Connector de plataforma de acesso — para entrega de login/senha/link de cursos online/presenciais (hoje netshow.me, instável; pode mudar). O CORTEX dispara e registra que foi entregue; não gerencia a entrega. Entra como connector quando estabilizar.
• marketplace-service + marketplace-db — para produtos físicos (estoque, comissão, entrega física). Fora do CORTEX na fase inicial — produto físico fica na loja e-commerce externa até o CORTEX amadurecer. Quando vier, plugará como mais um consumidor do fato de pagamento no exchange.
• Emissão fiscal (NF) — fora do escopo do CORTEX nesta fase. Quando uma venda exigir nota fiscal, a emissão é responsabilidade externa (ex.: motor fiscal do próprio jacad ou da contabilidade); o order-service não emite NF. Entra como fronteira quando/se for trazido para dentro.
• Forma de infra da borda de captura — resolvido em §4/§5 que o tracking é a borda exposta (recebe eventos/formulários, persiste-antes-de-ackar, encaminha PII ao identity). O princípio "dono de dado sensível nunca exposto" segue valendo para PII (vai pro identity murado); para comportamento pseudônimo ele é relaxado conscientemente (o tracking é o próprio exposto). A forma exata de infra na frente (ingress + WAF, rate-limit) fica no plano de infra.
• Schemas de tracking e identity — deixaram de estar adiados: ambos promovidos a docs dedicados (cortex-docs/services/TRACKING_SERVICE.md, cortex-docs/services/IDENTITY_SERVICE.md) — comportamento/eventos e captura no tracking; pessoa, matching, PII e presença no identity.
• Pacotes de fluxo futuros — refund/cancelamento, reengajamento de lead frio, tratamento de erro de regra de negócio do jacad (curso lotado, aluno já matriculado), alçadas de desconto detalhadas. Cada um entra como pacote que valida contra os fluxos existentes.

8. Inventário rápido

Serviços (13): institutional-service, identity-service, tracking-service, payment-service, order-service, cortex-service, storage-service, ai-orchestrator, ai-sales, ai-secretary, ai-wallet, ai-cortex (agregador das IAs internas dos times), ai-teacher (escopo a definir).

Recomendado (opcional, não adotado na fundação atual): messaging-service — governança de canal (entrega, opt-out, ritmo, status, demux). Por decisão atual, essas responsabilidades ficam no(s) *-connector(s) de canal; o serviço fica documentado como recomendação (§4, nota de recomendação; §7).

Connectors (5 atuais, mão-dupla, sem banco): academic-connector, crm-connector, payment-connector (por gateway), marketing-connector, whatsapp-connector. Futuros connectors de canal: telegram-connector, discord-connector, teams-connector (entram pela camada de entrega de canal — connector hoje; messaging-service se/quando adotado).

Infraestrutura de IA: embedding-service — provedor de embeddings (hoje BGE-M3), gateway sem dono de dado entre as especializadas/institucional e os bancos vetoriais.

Compartilhado / infra: cortex-shared (fundação comum), fila RabbitMQ (exchange topic, pub/sub), observabilidade MongoDB (logs).

Adiados: forma do whatsapp-connector, connector de plataforma de acesso, marketplace-service.

CHANGELOG