Tema
6. Decisões de Arquitetura (ADRs)
Esta seção registra as decisões que fundamentam o CRP.AI. Cada ADR apresenta contexto, decisão, alternativas e consequências, incluindo benefícios e compromissos aceitos.
ADR-001: LiteLLM como AI Gateway
Contexto:
A CRP Tecnologia não possuía uma definição formal de uso de IA. O CRP.AI foi concebido para estabelecer um ponto único de acesso a modelos de IA, com governança, rastreabilidade e controle de custos — evitando um cenário onde cada squad contrataria seus próprios provedores sem visibilidade organizacional.
O ambiente é integralmente on-premises, o que eliminava soluções SaaS como gateways gerenciados. O gateway precisava oferecer compatibilidade com múltiplos provedores por meio de um protocolo unificado, aplicando autenticação, autorização, rate limiting e registro de uso.
Decisão:
Utilizar o LiteLLM Proxy auto-hospedado como implementação atual do AI Gateway corporativo. O AI Gateway é implantado em rede interna, acessível diretamente pelos colaboradores para consumo de IA por virtual keys e pelo Olimpo para operações de gestão por uma credencial de serviço. No fluxo suportado, o AI Gateway autentica cada requisição, aplica limites de uso e orçamento e encaminha chamadas aos provedores configurados.
Alternativas consideradas:
API Management próprio: construir um proxy customizado para roteamento de requisições. Descartado por exigir desenvolvimento e manutenção de tradução de protocolos proprietários, rate limiting, budget e spend logging — funcionalidades que o LiteLLM oferece nativamente.
Kong API Gateway com plugin de IA: utilizar Kong como proxy com plugins customizados. Descartado por não oferecer suporte nativo ao ecossistema de LLMs (streaming, tradução de protocolos proprietários, métricas de tokens).
Nginx como proxy reverso simples: insuficiente para múltiplos provedores com protocolos diferentes, sem controle de chaves individuais, budgets ou rastreabilidade por colaborador.
Portkey Gateway: funcionalidades similares ao LiteLLM, mas descartado por menor maturidade e dependência maior de componentes SaaS.
Consequências:
Positivas:
- Suporte nativo a dezenas de provedores com tradução de protocolos para o formato OpenAI API
- Virtual keys com controle granular por colaborador (budget, rate limits, modelos)
- Spend logging, tracing e métricas integrados
- Open-source, auto-hospedado, sem dependência de SaaS externo
Trade-offs:
- Componente adicional no stack operacional (container, banco de dados dedicado)
- Ponto único de falha no acesso a IA — exige monitoramento e estratégia de recuperação
ADR-002: Olimpo como camada de abstração do gateway
Contexto:
O LiteLLM Proxy foi escolhido como implementação atual do AI Gateway (ADR-001), mas acoplar diretamente a lógica de negócio do CRP.AI à sua API administrativa criaria um risco de dependência tecnológica: uma eventual substituição do gateway exigiria alterar a lógica de governança junto com a integração técnica.
O Olimpo é um sistema com seus próprios modelos de domínio (times, membros, permissões, budgets). A questão era como integrar o módulo CRP.AI ao AI Gateway sem tornar a governança dependente da API específica do LiteLLM Proxy.
Decisão:
Criar uma camada de abstração entre a lógica de negócio do CRP.AI e o AI Gateway. Esta camada define contratos (interfaces) agnósticos ao gateway — operações de gestão de times, chaves, modelos e consulta de uso — e uma implementação concreta para LiteLLM que traduz esses contratos para a API administrativa do gateway.
A lógica de governança do Olimpo consome contratos administrativos, sem depender da implementação concreta diretamente. Uma troca de gateway exige uma nova implementação dos contratos e a validação do endpoint exposto aos consumidores, mas reduz alterações na política e nas regras de negócio do módulo CRP.AI. O acoplamento é controlado por configuração, permitindo testes com implementações simuladas.
Alternativas consideradas:
Acesso direto ao LiteLLM sem abstração: cada serviço consumiria diretamente a API administrativa do LiteLLM. Descartado por acoplar permanentemente o Olimpo à API do LiteLLM — qualquer mudança de gateway exigiria alterações em toda a base de código.
Olimpo como proxy de tráfego de IA: o Olimpo atuaria como intermediário das chamadas de IA, repassando requisições ao gateway. Descartado por adicionar latência e complexidade desnecessárias ao fluxo de consumo, além de tornar o Olimpo um ponto único de falha para todo o tráfego de IA.
Abstração sem separação física: implementar contratos e adaptadores no mesmo módulo da aplicação, sem isolamento. Descartado por não garantir enforcement — permitiria consumo acidental da implementação concreta, quebrando o isolamento.
Consequências:
Positivas:
- Redução de acoplamento administrativo: substituir o LiteLLM concentra a mudança na integração de gateway e reduz impacto na lógica de governança
- Testabilidade: lógica de negócio testável sem dependência de instância real do gateway
- Proteção contra mudanças: isola o domínio da aplicação de alterações na API administrativa do LiteLLM
Trade-offs:
- Camada adicional de indireção com transformação de modelos entre domínios
- Manutenção dupla: alterações em contratos exigem atualização da implementação concreta
- Overhead inicial de design que se paga na primeira troca de gateway ou breaking change
ADR-003: Padrão OpenAI API como interface de consumo
Contexto:
Cada provedor de IA expõe sua própria API nativa com convenções diferentes. Se o CRP.AI exigisse que os colaboradores se adaptassem à API nativa de cada provedor, o ecossistema de ferramentas compatíveis seria severamente limitado: cada ferramenta (OpenCode, Continue, Cursor) precisaria implementar suporte a múltiplos protocolos. Além disso, a troca de provedor implicaria alterações no código do consumidor.
O padrão OpenAI API consolidou-se como formato amplamente adotado pela indústria: a maioria dos provedores oferece compatibilidade total ou parcial, e muitas ferramentas do ecossistema de IA consomem o formato OpenAI.
Decisão:
Adotar o padrão OpenAI API como interface de consumo de modelos no CRP.AI. Colaboradores e suas ferramentas comunicam-se com o AI Gateway pelo formato exposto pelo gateway. Quando necessário e suportado, o AI Gateway traduz a requisição para o protocolo nativo do provedor de destino.
A seleção do modelo é feita por um identificador que o gateway interpreta para rotear ao provedor correto.
O CRP.AI Installer configura as ferramentas do colaborador apontando para o AI Gateway como endpoint OpenAI-compatible. A ferramenta comunica-se com o gateway corporativo, que aplica governança e então roteia ao provedor.
Alternativas consideradas:
APIs nativas de cada provedor: expor aos colaboradores a API nativa de cada provedor. Descartado porque cada ferramenta teria de suportar múltiplos protocolos e a troca de provedor poderia exigir alterações no consumidor.
Protocolo próprio do CRP.AI: definir um formato proprietário de requisição/resposta e exigir que ferramentas se adaptem a ele. Descartado por eliminar a compatibilidade imediata com o ecossistema de ferramentas existente — o CRP.AI se tornaria uma ilha que exigiria adaptadores para cada ferramenta.
Suporte dual (OpenAI API + APIs nativas): oferecer tanto o formato OpenAI quanto as APIs nativas. Descartado por introduzir complexidade desnecessária de manutenção, documentação e suporte, além de abrir brechas de governança (um colaborador usando API nativa poderia contornar restrições aplicadas apenas no formato OpenAI).
Consequências:
Positivas:
- Menor acoplamento ao provedor: a troca de provedor de um modelo pode preservar a configuração do consumidor quando o modelo ou alias e os recursos necessários forem mantidos pelo gateway.
- Compatibilidade ampliada: ferramentas compatíveis com a interface exposta pelo gateway podem ser configuradas sem integração direta com cada provedor.
- Menos variações de protocolo: colaboradores familiarizados com OpenAI API usam um formato já conhecido, embora continuem sujeitos às configurações e limites do gateway.
- Streaming quando suportado: recursos de streaming dependem da compatibilidade entre a ferramenta, o gateway e o provedor selecionado.
- Isolamento parcial de mudanças: alterações em APIs nativas tendem a ser tratadas no gateway, mas podem exigir validação de modelos, parâmetros e ferramentas consumidoras.
Trade-offs:
- Menor denominador comum: o formato OpenAI API não expõe funcionalidades exclusivas de provedores específicos (ex: computer use da Anthropic, grounding do Google Gemini, features experimentais do Bedrock). Para acessar essas funcionalidades, seria necessário suporte adicional no CRP.AI
- Dependência da tradução do LiteLLM: se o LiteLLM não oferecer tradução para um provedor ou modelo específico, o CRP.AI não conseguirá expô-lo pela interface adotada.
- Latência adicional: a camada de tradução introduz processamento extra que deve ser considerado na avaliação de desempenho.
- Funcionalidades não mapeáveis: parâmetros muito específicos de um provedor podem não ter equivalente no formato OpenAI e, portanto, não serem acessíveis através do CRP.AI
ADR-004: Virtual keys como mecanismo de controle de acesso
Contexto:
O CRP.AI precisava de um mecanismo que permitisse:
- Cada colaborador ter sua própria chave de acesso, com identidade rastreável
- Limites configuráveis por chave (orçamento, taxa de uso, modelos permitidos)
- Revogação individual sem afetar outros colaboradores do mesmo time
- As credenciais reais dos provedores nunca serem expostas fora do AI Gateway
O ambiente corporativo já utilizava Keycloak para SSO — o mecanismo deveria integrar-se com essa identidade federada.
Decisão:
Utilizar o modelo de virtual keys do AI Gateway: chaves individuais por colaborador, vinculadas ao seu time, com escopo limitado. Cada chave é configurada com parâmetros de limite de consumo, período de validade, modelos permitidos e limites de taxa de uso.
O módulo CRP.AI no Olimpo autoriza e solicita operações do ciclo de vida dessas chaves pela API administrativa do gateway. A chave real é gerada, mantida e validada pelo AI Gateway; o Olimpo mantém apenas metadados de aplicação e auditoria.
A identidade do colaborador é vinculada à chave através do identificador corporativo, permitindo rastreabilidade completa: cada chamada de IA é associada ao colaborador que a originou.
Alternativas consideradas:
Credenciais próprias de usuário no Olimpo: o Olimpo emitiria credenciais e faria a tradução para chaves de provedor. Descartado por duplicar funcionalidades nativas do AI Gateway e por exigir o armazenamento de credenciais de provedores na plataforma.
OAuth2 Client Credentials como chave de acesso: usar tokens OAuth2 de curta duração. Descartado por não ser suportado nativamente pelo ecossistema de ferramentas de IA (que esperam uma API key simples) e por adicionar latência de renovação de token.
Chave única compartilhada por time: uma chave para todos os colaboradores. Descartado por impossibilitar rastreabilidade individual e revogação seletiva.
Consequências:
Positivas:
- Rastreabilidade individual: cada chamada é vinculada ao colaborador
- Controle granular: limite de consumo, limites de taxa e modelos por chave
- Revogação independente sem afetar o time
- Credenciais de provedores isoladas no gateway
- Regeneração segura com preservação de histórico
- Compatível com ferramentas que atendam à interface exposta pelo gateway
Trade-offs:
- Dependência do gateway para geração e validação de chaves
- Sincronização de estado entre Olimpo e gateway necessária em cenários de falha