📋 Os 5 Principios em Resumo
🔌 Principio 1: API-first sempre
O primeiro principio estabelece que toda capacidade do sistema deve ser exposta via API. Nao existem funcionalidades "escondidas" ou acessiveis apenas pela interface.
✓ O que significa API-first
- • Toda funcionalidade e um endpoint
- • UI e apenas um consumidor da API
- • Integracao com outros sistemas e nativa
- • Automacao via scripts ou workflows e possivel
✗ Violacoes comuns
- • Funcoes acessiveis apenas pela UI
- • Logica de negocio no frontend
- • Chamadas diretas ao LLM do browser
- • Endpoints "especiais" sem documentacao
💡 Por que isso importa
API-first garante que voce pode auditar, testar e escalar qualquer funcionalidade. Se algo so funciona pela UI, voce perdeu o controle sobre isso.
🎛️ Principio 2: Backend orquestra, IA executa
Este principio define a separacao fundamental de responsabilidades: o backend determina o que fazer, a IA fornece capacidade cognitiva para executar tarefas especificas.
🔀 Fluxo de Responsabilidades
Backend
Decide QUANDO e COMO chamar IA
IA
Executa tarefa especifica
Backend
Valida e processa resultado
🖥️ Backend faz:
- • Valida permissoes e acesso
- • Coleta contexto necessario
- • Injeta personas e preferencias
- • Decide qual modelo usar
- • Valida output da IA
- • Persiste resultados
🤖 IA faz:
- • Analisa dados fornecidos
- • Estrutura informacoes
- • Sintetiza conteudo
- • Gera outputs estruturados
- • Responde perguntas especificas
- • NUNCA controla fluxo
📦 Principio 3: IA gera estrutura, sistema gera artefatos
A Regra das Duas Fases estabelece que a IA produz dados estruturados (JSON, outlines), e o sistema transforma isso em artefatos finais (documentos, videos, imagens).
Fase 1: IA
{ "titulo": "...", "slides": [...] }
Gera estrutura JSON
Fase 2: Sistema
Materializa artefato
✓ Exemplos corretos
- • IA gera JSON do roteiro → Sistema gera video
- • IA gera estrutura do doc → Sistema gera .docx
- • IA gera dados do chart → Sistema gera imagem
- • IA gera outline → Sistema gera PDF
✗ Violacoes
- • IA gerando arquivo .pptx diretamente
- • IA retornando base64 de imagem
- • IA escrevendo HTML diretamente
- • IA fazendo upload de arquivos
💡 Por que duas fases
Separar estrutura de materializacao permite: reusar o JSON para multiplos formatos, versionar a estrutura separadamente, e validar o conteudo antes de gerar o artefato final.
💾 Principio 4: Persistencia total
Tudo e armazenado: cada input, cada output, cada custo. Nao existe operacao "volatil" ou dado perdido. O sistema mantem audit trail completo.
📊 O que persistir
Inputs
Prompt original e contexto
Outputs
Resposta completa da IA
Custos
Tokens, tempo, valor
Metadados
Modelo, persona, config
🗃️ Estrutura de Registro
{
"id": "exec_abc123",
"timestamp": "2026-01-16T10:30:00Z",
"user_id": "usr_456",
"endpoint": "/api/v1/generate",
"input": {
"prompt": "Crie um resumo...",
"context": { ... }
},
"output": {
"content": "...",
"tokens_used": 1250
},
"cost": {
"input_tokens": 500,
"output_tokens": 750,
"total_usd": 0.0125
},
"metadata": {
"model": "gpt-4",
"persona": "critical_reviewer",
"duration_ms": 2340
}
}
🔍 Beneficios da Persistencia
Auditoria
Responda "por que a IA disse isso?" a qualquer momento
Aprendizado
Analise padroes para melhorar prompts e personas
Custos
Saiba exatamente quanto cada feature custa
🔄 Principio 5: Modularidade e anti-lock-in
O sistema deve ser modular e substituivel. Nenhum componente pode ser tao acoplado que sua troca comprometa o sistema. Isso inclui o proprio modelo de IA.
🧩 Componentes Substituiveis
Modelo LLM
GPT → Claude → Gemini
Banco de Dados
Postgres → MySQL → Mongo
Storage
S3 → GCS → Azure
Materializador
ffmpeg → outro encoder
✓ Praticas anti-lock-in
- • Interfaces abstratas para cada componente
- • Configuracoes por ambiente
- • Dados em formatos padrao (JSON, CSV)
- • Exportacao completa de dados
- • Documentacao de dependencias
✗ Sinais de lock-in
- • Chamadas diretas a SDK proprietario
- • Dados em formato proprietario
- • Features que so funcionam com um provider
- • Impossibilidade de migrar dados
- • Dependencia de servicos especificos
💡 Teste do Anti-Lock-in
Pergunte: "Se amanha o provider X triplicar o preco ou sair do ar, em quanto tempo eu migro?". Se a resposta for "meses" ou "impossivel", voce tem um problema de lock-in.
🔒 Por que sao inalteraveis
Estes principios nao sao "boas praticas" ou "recomendacoes" - sao requisitos fundamentais. Violar qualquer um deles compromete a governanca do sistema.
⚠️ Consequencias de Violacao
✓ Checklist de Conformidade
🎯 Resumo Final
"Os 5 principios nao sao opcoes de design - sao pre-requisitos para chamar um projeto de 'GIPM-compliant'. Se um deles for violado, voce pode ter um bom sistema, mas nao tem governanca real sobre IA."
📝 Resumo do Modulo
Proximo modulo:
1.4 - Arquitetura de Tres Camadas - Entenda como as responsabilidades sao divididas entre humano, sistema e IA.