# Plataforma de operações com IA

Do acompanhamento comercial a uma assistência com acesso controlado.

Pipeline, tarefas e indicadores em uma aplicação demonstrável. No backend, uma assistência com LLMs consulta ferramentas autorizadas; seus controles foram exercitados em 23 testes locais. A demo usa dados sintéticos e simula os serviços externos.

LLMs · OpenRouter · Tool calling · Fastify · React · PostgreSQL

Demo online · backend validado localmente

## Contexto: acompanhar uma operação comercial

Equipes precisam acompanhar contatos, etapas do pipeline, tarefas e propostas sem perder a relação entre as informações. O estudo de caso reúne uma aplicação de operações e seu módulo de assistência por IA. A apresentação pública foi desvinculada da identidade do cliente e utiliza apenas exemplos sintéticos.

## Problema: transformar informação em próxima ação

Uma pergunta como “o que precisa de acompanhamento?” depende do acesso correto aos dados e de regras de negócio. Um modelo pode interpretar a pergunta, mas não deve escolher sozinho as permissões nem executar consultas livres. O desafio foi conectar a experiência do produto a uma assistência com fronteiras verificáveis.

## Objetivo e escopo da solução

Organizar o fluxo de trabalho em um produto navegável e construir uma integração de LLM que use ferramentas delimitadas. A demonstração permite examinar a interface; os testes de backend verificam autorização, comportamento do provedor e tratamento de contexto. São evidências complementares, com alcances diferentes.

## Arquitetura: interface, API, ferramentas e dados

A interface React se comunica com uma API TypeScript sobre Node.js e Fastify. O módulo de IA integra OpenRouter por um contrato compatível com a API de chat da OpenAI. O servidor compõe contexto, controla as ferramentas e interpreta respostas do provedor. PostgreSQL aparece nas consultas e migrations de persistência.

O caminho implementado é: pergunta → rota autenticada → contexto autorizado → modelo → solicitação de ferramenta → validação e consulta → resposta. A integração de banco está presente no código; sua execução em PostgreSQL real não foi certificada neste recorte.

## Módulos e experiência navegável

A demo apresenta dashboard, contatos, pipeline, tarefas, propostas, automações e indicadores. Suas alterações são temporárias e as integrações externas são simuladas. Ela mostra organização de produto e interface, sem acessar contas ou operações reais.

No backend auditado, o recorte inclui rotas de assistência, serviço de chat, ferramentas semânticas, preparação de contexto, contabilização de tokens e estados de custo. Não confundo uma tela da demo com prova de execução desse backend.

Há componentes complementares de contratos de métricas e coleta consentida, com 9 e 3 testes locais respectivamente. Eles diferenciam indisponibilidade de valor zero e minimizam dados de coleta. A execução integrada com o CRM não foi certificada; os detalhes permanecem no aprofundamento técnico de dados.

## Integrações: contrato de LLM e API

O serviço usa uma interface HTTP compatível com chat e tool calling. Há tratamento de respostas inesperadas, indisponibilidade e erros recuperáveis. Nos testes, o transporte do provedor é substituído por respostas controladas: isso verifica o contrato sem depender de chamadas pagas ou dados privados.

## Tecnologias e função no sistema

TypeScript e Node.js sustentam os contratos e a execução do backend; Fastify expõe as rotas; Zod valida entradas. OpenRouter é o conector de modelos. React sustenta a interface. SQL e PostgreSQL aparecem na modelagem de memória e recuperação textual.

A prova mais forte desta auditoria é a execução local das regras de IA e API. Interface, migrations e banco possuem evidência de implementação, mas não receberam certificação integrada de produção nesta etapa.

## Decisões técnicas e compromissos

Escolhi ferramentas semânticas em vez de deixar o modelo escrever SQL livre. O servidor mantém a decisão sobre o acesso, enquanto o modelo interpreta uma intenção dentro das operações oferecidas. Essa separação permite testar permissões sem depender da variação de uma resposta generativa.

A recuperação de contexto implementada é textual e lexical. Essa escolha não equivale a embeddings ou busca vetorial. A informação pública descreve o mecanismo existente, sem atribuir ao projeto frameworks ou estratégias que não foram demonstrados.

## LLMs, tool calling e automações

O loop de assistência recebe solicitações de ferramentas e impõe limites de execução. Os resultados retornam ao contexto após controles de acesso e sanitização. Os testes exercitam esse comportamento com respostas simuladas de modelo.

As telas de automação da demo representam uma experiência de produto. Este estudo não apresenta esses fluxos como automações externas ativadas. A realização comprovada é o controle local da assistência e das ferramentas no recorte auditado.

## Infraestrutura e publicação

O produto separa apresentação, API e persistência. A demonstração pública é um ambiente independente, com dados sintéticos. O código auditado do cliente e suas credenciais não são publicados neste site.

A prova de infraestrutura apresentada aqui é o acesso público ao ambiente demonstrativo. A arquitetura privada possui dependências de API e banco cuja execução integrada permanece fora do recorte certificado.

## Tokens, custo e diagnóstico

O serviço distingue dados completos, parciais e indisponíveis de uso e custo. Um custo desconhecido não é convertido silenciosamente em zero. Esse contrato ajuda a interpretar limites e falhas do provedor.

A evidência local não demonstra tracing distribuído completo, dashboards de produção nem avaliação sistemática de qualidade generativa. Esses itens exigem provas próprias, além dos testes do contrato.

## Segurança e privacidade

O usuário e o escopo da organização são derivados no servidor. As ferramentas operam dentro do contexto autorizado e os resultados passam por sanitização antes de compor o contexto do modelo. Há verificações negativas para evitar que uma entrada escolha arbitrariamente o acesso.

Os controles exercitados não constituem auditoria legal integral nem prova de isolamento uniforme de todas as tabelas. Nenhum dado de cliente, log original, credencial ou identificador privado aparece nos materiais públicos.

## Como experimentar e avaliar

Comece pelo dashboard da demonstração, explore pipeline e tarefas e observe como responsáveis e próximas ações são representados. Depois, examine as configurações e os indicadores. Todos os exemplos são sintéticos.

Para avaliar a engenharia, leia as fronteiras de autorização e o relatório de evidências. A demo serve para testar a experiência; o relatório informa quais comportamentos foram exercitados localmente e quais dependências foram simuladas.

## Minha participação

Atuei na estruturação da solução, na implementação de interface e backend e na definição dos controles de assistência e acesso a dados. Também organizei os cenários de teste e a demonstração independente. Apresento as decisões e os componentes que conduzi, sem expor a operação do cliente.

O resultado técnico apresentado é o software e seu recorte verificável. Não atribuo ao projeto percentuais de ganho comercial ou produtividade que não tenham sido medidos.

## O que está concluído no recorte

O serviço de chat, o contrato de tool calling, os controles de contexto e a autorização das rotas foram exercitados em uma suíte isolada de 23 testes aprovados. O teste usa a API real com dependências de dados e provedor substituídas. A demo é acessível publicamente.

## O que tem comprovação parcial ou depende de validação

Memória persistente, recuperação textual SQL e migrations estão implementadas, mas não foram testadas contra PostgreSQL real nesta auditoria. A execução integrada entre interface, banco e provedor real não está certificada aqui.

Melhorias de recuperação vetorial, avaliação de respostas ou novas automações não são apresentadas como realizadas. Planejamento e validação pendente permanecem separados das entregas comprovadas.

## Resultados comprováveis

O resultado funcional é uma experiência de produto navegável e um backend com 23 cenários locais aprovados de IA, API e controles. Os testes verificam regras concretas com entradas controladas; não medem aumento de receita nem disponibilidade operacional do cliente.

## Evidências disponíveis e limites de reprodução

Estão disponíveis a demo, este briefing em página e Markdown e um relatório público sanitizado com escopo, contagens e hashes de evidências. As fontes e os registros originais foram conferidos novamente por hash em 04/10/2026.

O relatório é uma publicação derivada dos testes, não uma certificação independente. O código privado e os logs originais não são disponibilizados; a execução integral da suíte depende de acesso autorizado às fontes.

## Competências demonstradas

Arquitetura de aplicações com LLMs, tool calling, contratos de API, TypeScript, Fastify, autorização no backend, sanitização e tratamento de falhas são demonstrados no recorte local. A demo acrescenta uma evidência de organização de interface e produto. SQL e persistência são descritos como implementação com validação integrada pendente.

## Correspondência com requisitos do mercado

O caso oferece evidências para requisitos encontrados nas vagas pesquisadas: aplicações com LLMs, agentes com ferramentas, APIs, arquitetura, segurança e tradução de processos de negócio em software. A demonstração facilita a leitura não técnica, e os controles permitem uma avaliação técnica.

Experiência com IA operando em produção é um requisito importante da pesquisa, mas esta suíte local não o certifica. Python, RAG vetorial e frameworks de agentes não são adicionados a este caso apenas porque aparecem nas vagas.

---
César Machado · https://cesarmachado.com