Portal Grupo Studio: inteligência comercial com dados e IA

Visão geral

O Portal Grupo Studio é uma plataforma interna de dados e inteligência comercial criada para reunir, em um único produto, informações de CRM, campanhas de mídia, metas, atividades e conhecimento operacional.

A aplicação combina dashboards para acompanhamento da operação com um Assistente Comercial de IA, capaz de consultar dados autorizados do Pipedrive, informações de campanhas da Meta e uma base de conhecimento comercial antes de responder.

• Aplicação: portal-grupostudio.lovable.app
• Repositório: peixotojeff/portal-grupostudio
• Stack principal: TypeScript, React, TanStack Start, Supabase, Pipedrive API, Meta Graph API e AI SDK.

O repositório original é privado e utiliza dados corporativos. Os links acima representam a aplicação e o código de origem; uma publicação pública do código deve utilizar dados fictícios e configuração sanitizada.

Problema

A operação comercial dependia de informações distribuídas em diferentes fontes. Para responder perguntas simples — como desempenho de SDRs, origem de leads, situação do funil ou próximos negócios a retomar — era necessário alternar entre CRM, plataformas de anúncios, relatórios e materiais internos.

Esse cenário criava alguns problemas:

• dificuldade para acompanhar o funil em diferentes níveis de detalhe;
• pouca padronização na interpretação de atividades comerciais;
• tempo gasto procurando informações em várias ferramentas;
• risco de misturar dados de usuários ou apresentar métricas inconsistentes;
• conhecimento comercial disperso em apresentações e playbooks.

Solução

O portal organiza a experiência em duas camadas complementares:

1. Analytics operacional e executivo, com dashboards de qualificação, metas, origens, campanhas, atividades e desempenho;
2. Assistente Comercial de IA, com acesso controlado a ferramentas de dados e à base de conhecimento.

Pipedrive ───────┐
                 ├── Supabase/PostgreSQL ── Dashboards
Meta Ads ────────┘                         └── Assistente IA
                                                  ↓
                                      Ferramentas + Base de conhecimento

Principais funcionalidades

Dashboards comerciais

O portal possui visões para diferentes necessidades da operação:

• dashboard executivo;
• qualificação de leads;
• metas e resultados;
• origens de oportunidades;
• campanhas e mídia;
• atividades comerciais;
• desempenho de SDRs;
• visualização para TV;
• análise de funil e resultados.

Os filtros de período, bandeira e equipe permitem que a mesma base seja usada para acompanhamento operacional e análise gerencial.

Integração com Pipedrive

A integração com o Pipedrive alimenta o portal com informações de negócios, pessoas, atividades, usuários, etapas e origem dos leads.

O código também trata paginação, sincronização e normalização dos dados para que as telas não dependam diretamente do formato original da API.

Integração com Meta Ads

A integração com a Meta Graph API permite consultar dados de contas, campanhas, anúncios e criativos.

O módulo inclui cuidados para lidar com limites da API, como:

• throttling preventivo entre chamadas;
• retry com backoff para rate limits;
• registro de falha por conta;
• sinalização de contas que precisam de sincronização manual;
• cache temporário de previews e fontes de vídeo.

Assistente Comercial de IA

O assistente pode responder perguntas sobre leads, negócios, desempenho e recomendações comerciais. Ele utiliza o AI SDK e um gateway compatível com modelos de linguagem.

A resposta não depende apenas de texto gerado pelo modelo. O assistente usa ferramentas específicas para consultar os dados disponíveis:

Usuário autenticado
        ↓
Validação de identidade e função
        ↓
System prompt com regras de negócio
        ↓
Tools de CRM, métricas e conhecimento
        ↓
Modelo de IA
        ↓
Resposta com contexto, diagnóstico e próximos passos

As regras do assistente incluem:

• não inventar números, IDs, campanhas, nomes ou datas;
• consultar uma ferramenta antes de afirmar dados do negócio;
• consultar a base de conhecimento antes de recomendar um argumento ou próximo passo;
• respeitar o escopo de acesso do usuário;
• informar honestamente quando uma ferramenta não retornar dados;
• responder em um formato operacional com contexto, diagnóstico, próximos passos e fontes.

Base de conhecimento comercial

A pasta knowledge/ contém documentos em Markdown usados como fonte do assistente, incluindo playbooks, apresentações e materiais por bandeira comercial.

O pipeline de conhecimento realiza:

1. leitura dos documentos Markdown;
2. interpretação de frontmatter, tags e bandeira;
3. divisão do conteúdo em chunks;
4. geração de embeddings;
5. armazenamento dos documentos e chunks no Supabase;
6. busca semântica para recuperar contexto relevante;
7. verificação de documentos sem chunks ou embeddings.

Os scripts de operação incluem:

bun run kb:ingest
bun run kb:generate
bun run kb:verify

Segurança e controle de acesso

O portal utiliza autenticação do Supabase e funções de acesso associadas aos papéis da aplicação, incluindo admin, marketing e comercial.

O assistente também aplica regras diferentes conforme o usuário autenticado. Usuários comerciais podem ter seu acesso limitado aos negócios em que são proprietários ou criadores, enquanto perfis autorizados podem consultar uma visão mais ampla da operação.

Essa separação é importante porque uma aplicação de IA conectada a dados comerciais precisa controlar não apenas quem entra no sistema, mas também quais dados cada pessoa pode consultar.

Qualidade das métricas comerciais

Uma parte importante do projeto foi transformar regras comerciais implícitas em lógica testável.

O módulo de classificação de atividades diferencia eventos como:

• qualificação realizada;
• agendamento de CC1;
• CC1 realizada;
• CC1 não realizada;
• no-show por imprevisto;
• no-show por desinteresse.

Os testes verificam, entre outros pontos:

• uso do tipo da atividade do Pipedrive em vez de apenas confiar no assunto;
• diferenciação entre uma CC1 realizada e um reagendamento;
• exigência de atividade concluída;
• uso da data em que a atividade foi marcada como feita;
• atribuição de crédito somente quando o criador pertence ao time de SDR;
• exclusão de atividades incompletas da visão analítica.

Essa abordagem reduz o risco de apresentar um KPI visualmente correto, mas baseado em uma regra de negócio equivocada.

Decisões técnicas

Supabase como camada de dados e autenticação

O Supabase concentra PostgreSQL, autenticação, funções SQL, políticas de acesso e operações de consulta. Essa escolha reduz a quantidade de infraestrutura necessária para uma aplicação interna e mantém os dados relacionais próximos das regras analíticas.

TanStack Start para frontend e backend

O TanStack Start permite manter rotas de interface e handlers server-side no mesmo projeto TypeScript. Isso simplifica a organização de endpoints, autenticação e funções de servidor sem separar prematuramente o produto em múltiplos repositórios.

Tools antes de geração livre

O assistente não recebe autorização para responder livremente sobre dados comerciais. As instruções do sistema direcionam o modelo para ferramentas específicas, reduzindo a dependência de memória paramétrica e tornando a origem dos dados mais rastreável.

Dados normalizados antes das telas

As integrações com Pipedrive e Meta Ads passam por uma camada de sincronização e normalização. Assim, os componentes de interface podem trabalhar com estruturas internas mais estáveis, sem espalhar detalhes de APIs externas por todo o frontend.

O que aprendi construindo este projeto

Este projeto conecta competências de Data & AI Engineering em um produto aplicado:

• transformar necessidades comerciais em métricas e regras explícitas;
• integrar APIs de CRM e mídia com paginação, retry e controle de rate limit;
• construir dashboards sobre uma camada de dados centralizada;
• aplicar autenticação e autorização a uma aplicação com IA;
• usar tool calling para conectar modelos de linguagem a dados operacionais;
• criar uma base de conhecimento com ingestão, embeddings e busca semântica;
• testar regras de classificação antes de utilizá-las nos KPIs;
• tratar custo, observabilidade, privacidade e qualidade como partes da arquitetura.

Estado atual e próximos passos

O portal já possui a aplicação publicada, dashboards operacionais, integrações de dados, assistente comercial, base de conhecimento e testes para regras centrais de classificação.

Próximas evoluções recomendadas para uma versão pública de portfólio:

• criar uma demo com dados fictícios;
• adicionar README técnico ao repositório do produto;
• remover o .env versionado e manter apenas um .env.example;
• ampliar a cobertura de testes para autorização, ferramentas e ingestão;
• adicionar pipeline de CI para lint, testes e build;
• publicar screenshots e um diagrama de arquitetura sem dados corporativos;
• documentar métricas de latência, custo e qualidade do assistente.

Publicado por Jefferson Peixoto em 23 de julho de 2026.