Tema
4. Visão de Containers
Esta seção apresenta o diagrama de containers do CRP.AI, detalhando cada unidade implantável do sistema, suas responsabilidades, tecnologias, APIs, armazenamento e dependências.
4.1 Diagrama de Containers
4.2 Detalhamento dos Containers
4.2.1 AI Gateway — LiteLLM Proxy
| Propriedade | Valor |
|---|---|
| Responsabilidade | Gateway de IA: ponto de comunicação com provedores de modelo. Recebe requisições dos colaboradores por virtual key e do Olimpo API por credencial de serviço para operações de gestão. Autentica, aplica limites, roteia ao provedor e registra dados operacionais. |
| Tecnologia | Python, LiteLLM, Docker |
| APIs e protocolos | API REST compatível com OpenAI API para consumo de modelos; API administrativa REST para gestão de chaves, times e logs |
| Armazenamento | PostgreSQL dedicado: virtual keys (hash), teams, budgets, spend logs |
| Dependências | PostgreSQL (LiteLLM), Prometheus, provedores de IA e integração de tracing quando configurada |
O LiteLLM Proxy opera em rede interna. Colaboradores o acessam diretamente para consumo de IA com virtual keys. O Olimpo API o acessa para operações administrativas. Credenciais dos provedores residem exclusivamente no LiteLLM Proxy.
4.2.2 Olimpo API
| Propriedade | Valor |
|---|---|
| Responsabilidade | Integração de governança do módulo CRP.AI. Aplica política corporativa de acesso, persiste times, permissões, budgets, metadados de chaves e auditoria; solicita operações à API administrativa do AI Gateway. Sincroniza colaboradores e times com o Controle de Projetos. |
| Tecnologia | Java, Spring Boot |
| APIs e protocolos | API REST. Endpoints de gestão de times, chaves, modelos, acesso IA, instalação e auditoria. Autenticação JWT via Keycloak. |
| Armazenamento | PostgreSQL (Olimpo): times, membros, permissões, configurações de acesso IA, budgets, logs de auditoria |
| Dependências | Keycloak SSO (validação JWT), AI Gateway por integração administrativa (LiteLLM Proxy na implantação atual), PostgreSQL (Olimpo), Controle de Projetos (sincronização) |
A autorização é delegada ao Keycloak, que emite tokens JWT com os papéis necessários para operações de gestão e administração do CRP.AI.
4.2.3 Olimpo Frontend
| Propriedade | Valor |
|---|---|
| Responsabilidade | Interface web do CRP.AI: portal administrativo (gestão de times, modelos, budgets) e portal de autoatendimento do colaborador (Minha Chave, consumo, regeneração) |
| Tecnologia | React, nginx |
| APIs e protocolos | Consome Olimpo API via REST/HTTPS com JWT. Autenticação via Keycloak. |
| Armazenamento | Stateless — estado reside no Olimpo API |
| Dependências | Olimpo API, Keycloak SSO |
4.2.4 CRP.AI Installer
| Propriedade | Valor |
|---|---|
| Responsabilidade | CLI de configuração do ambiente local do colaborador. Verifica o ambiente, autentica o colaborador, obtém a configuração de IA e configura o OpenCode. Pode oferecer a instalação da CRP.AI Skill do catálogo corporativo e a configuração opcional do MCP Azure DevOps. |
| Tecnologia | Node.js, distribuído via npm (@crp/crp-ai) |
| APIs e protocolos | Keycloak (OAuth2 Device Authorization), Olimpo API (REST/JWT) |
| Armazenamento | Persiste configuração local: opencode.json, manifesto de skills e, quando o MCP é confirmado, arquivo de ambiente do Azure DevOps |
| Dependências | Keycloak SSO, Olimpo API, OpenCode CLI, npm registry |
Fluxo de execução:
- Verificação do ambiente: detecta se o OpenCode está instalado e oferece instalação automática
- Autenticação: inicia fluxo de autenticação via Keycloak — exibe um código no terminal para validação no navegador
- Obtenção de configuração: consulta autenticada ao Olimpo API e recebe virtual keys, Base URLs e modelos disponíveis
- Skills (opcional): oferece a instalação da skill disponível no catálogo corporativo pelo Nexus
- Configuração do OpenCode: escreve o arquivo de configuração com provedores, modelos e chaves
- Azure DevOps MCP (opcional): se houver PAT provisionado, configura a integração após confirmação do colaborador
4.2.5 PostgreSQL — LiteLLM
| Propriedade | Valor |
|---|---|
| Responsabilidade | Banco de dados operacional do gateway. Armazena virtual keys (hash), teams, budgets, rate limits, configurações de modelos e spend logs |
| Tecnologia | PostgreSQL |
| Dependências | Nenhuma |
O Olimpo API nunca acessa diretamente este banco — toda interação ocorre pela API REST administrativa do AI Gateway, implementada atualmente pelo LiteLLM Proxy.
4.2.6 PostgreSQL — Olimpo
| Propriedade | Valor |
|---|---|
| Responsabilidade | Banco de dados de aplicação do Olimpo. Armazena times, membros, permissões, configurações de acesso IA, budgets, metadados de chaves e logs de auditoria |
| Tecnologia | PostgreSQL |
| Dependências | Nenhuma |
O banco mantém metadados da virtual key, como key_id, alias e parâmetros. O valor da chave é provisionado pelo gateway no arquivo de configuração local necessário ao colaborador; ele não é persistido no banco do Olimpo.
4.3 Fluxos de Comunicação entre Containers
4.3.1 Consumo de Modelo de IA (runtime)
Colaborador → Ferramenta (OpenCode/CLI) → AI Gateway → Provedor IA
│
└─ Valida virtual key
Aplica rate limit
Aplica budget
Registra spend log
Emite tracing quando configuradoNa implantação atual, o AI Gateway desse fluxo é o LiteLLM Proxy.
Sequência detalhada:
- O colaborador, já configurado pelo CRP.AI Installer, faz uma requisição via ferramenta (OpenCode, Continue, Cursor)
- A ferramenta envia a requisição diretamente ao AI Gateway
- O AI Gateway valida a virtual key, verifica rate limits e budget restante
- O AI Gateway roteia a requisição ao provedor configurado usando a credencial do provedor (armazenada apenas no AI Gateway)
- O AI Gateway registra a chamada nos spend logs e pode emitir tracing quando a integração estiver configurada
- A resposta do provedor é retornada diretamente à ferramenta do colaborador
4.3.2 Gestão Administrativa
Administrador → Olimpo Frontend → Olimpo API (módulo CRP.AI) ─┬─ PostgreSQL Olimpo (dados de aplicação)
└─ API administrativa do AI Gateway (LiteLLM Proxy)Gerenciar time com acesso a IA:
- Administrador autentica-se no Olimpo Frontend (Keycloak SSO)
- Frontend envia requisição ao Olimpo API com JWT do admin
- Olimpo API valida permissão, persiste a política no PostgreSQL e solicita a criação ou atualização do time na API administrativa do AI Gateway
Gerar chave para colaborador:
- Administrador define parâmetros (budget, modelos, limites)
- Olimpo API solicita ao AI Gateway a geração da virtual key
- AI Gateway gera a virtual key e mantém seu estado técnico; Olimpo API armazena apenas metadados — a chave nunca é persistida no banco do Olimpo
4.3.3 Instalação e Configuração do Colaborador
O fluxo completo de execução do CRP.AI Installer está detalhado na seção 4.2.4, incluindo o diagrama de sequência com as etapas de verificação de ambiente, autenticação, obtenção de credenciais, instalação de skills e configuração do OpenCode.
4.3.4 Monitoramento
O LiteLLM e o Olimpo API expõem métricas no formato Prometheus. A integração de tracing depende da topologia aprovada e da política de retenção aplicável.
4.4 Tabela-Resumo de Containers
| Container | Tecnologia | Banco de Dados |
|---|---|---|
| AI Gateway (LiteLLM Proxy) | Python, LiteLLM, Docker | PostgreSQL (LiteLLM) |
| Olimpo API | Java, Spring Boot | PostgreSQL (Olimpo) |
| Olimpo Frontend | React, nginx | Nenhum (stateless) |
| CRP.AI Installer | Node.js | Nenhum (stateless) |
| PostgreSQL (LiteLLM) | PostgreSQL | — |
| PostgreSQL (Olimpo) | PostgreSQL | — |
4.5 Decisões de Design Relevantes
Virtual Keys por colaborador: cada colaborador recebe uma virtual key individual com escopo limitado (modelos, budget, rate limits). Isso permite rastreabilidade individual e revogação independente.
AI Gateway acessível na rede interna: colaboradores consomem IA diretamente via AI Gateway, sem latência adicional de camada intermediária.
Separação de bancos de dados: PostgreSQL do LiteLLM e do Olimpo são instâncias independentes. Nenhum componente acessa diretamente o banco do outro — toda comunicação é via API REST.
Abstração do gateway: o Olimpo API utiliza uma camada de abstração que concentra a integração administrativa com a API específica do gateway. Uma troca de gateway reduz alterações na lógica de governança, mas consumidores continuam dependentes do endpoint exposto pelo AI Gateway selecionado.