orquestrador/docs/adr/0002-split-product-and-admin-services.md

ADR 0002 - Separar o runtime de produto do serviço administrativo

Status

Accepted

Relacao com ADRs anteriores

Esta decisao complementa a ADR 0001. A ADR 0001 separa identidade de atendimento e identidade administrativa. A ADR 0002 amplia essa separacao para o nivel de servicos e runtime.

Contexto

O sistema atual nasceu como um unico runtime orientado ao atendimento. Hoje ele concentra no mesmo projeto e no mesmo ciclo operacional:

• atendimento conversacional
• orquestracao de tools
• integracao com Telegram
• estado conversacional
• regras operacionais de vendas, revisao e locacao
• administracao futura do sistema
• geracao futura de novas tools
• relatorios e configuracoes internas

A nova frente de evolucao exige um modulo administrativo mais robusto, com:

• login interno de funcionarios e administradores
• configuracao do sistema
• relatorios de vendas, arrecadacao e operacao
• cadastro, geracao, validacao e publicacao de novas tools
• auditoria de alteracoes e aprovacoes

Se tudo isso continuar no mesmo runtime do atendimento, teremos aumento de risco em quatro eixos:

1. Performance

   • jobs pesados de geracao e validacao podem concorrer com o atendimento.

2. Seguranca

   • login administrativo, aprovacoes e publicacao de codigo ficariam expostos no mesmo servico do produto.

3. Operacao

   • qualquer falha ou deploy administrativo pode impactar diretamente o atendimento.

4. Evolucao

   • o painel e a automacao interna possuem cadencia, dependencias e necessidades diferentes do runtime conversacional.

Decisao

Vamos separar a solucao em dois servicos distintos, inicialmente no mesmo repositorio.

1. Servico de produto

Nome conceitual: orquestrador-product

Responsabilidades:

• atendimento conversacional
• integracao com Telegram e futuros canais de atendimento
• orquestracao de tools em tempo de execucao
• fluxos operacionais de vendas, revisao e locacao
• leitura apenas de tools publicadas e configuracoes ativas

Esse servico continua sendo o runtime critico do produto. Ele deve permanecer leve, previsivel e protegido de cargas administrativas.

2. Servico administrativo

Nome conceitual: orquestrador-admin

Responsabilidades:

• autenticacao e autorizacao interna
• painel administrativo
• configuracoes do sistema
• relatorios de vendas, arrecadacao e operacao
• cadastro de drafts de tools
• geracao de implementacoes
• validacao automatica
• aprovacao humana
• publicacao controlada
• auditoria de mudancas

Esse servico nao participa do hot path do atendimento. Ele governa o sistema, mas nao executa atendimento em tempo real.

Decisao sobre repositorio

Neste primeiro momento, os dois servicos permanecem no mesmo repositorio.

Motivos:

• menor custo operacional inicial
• versionamento conjunto das fronteiras compartilhadas
• mais facilidade para evoluir contratos internos
• menos atrito no inicio da iniciativa

No futuro, se a operacao justificar, eles podem ser separados em repositorios diferentes. Essa separacao nao e obrigatoria agora.

Fronteira entre os servicos

O que pertence ao servico de produto

• LLM do atendimento
• orquestrador
• registry de tools ativas
• execucao de tools aprovadas
• fluxo de conversa
• integracoes com canais externos de atendimento
• persistencia operacional do usuario final

O que pertence ao servico administrativo

• StaffAccount
• permissao por papel
• painel interno
• configuracao administrativa
• relatorios e dashboards
• pipeline de geracao de tools
• versionamento de tools
• aprovacao/publicacao
• trilha de auditoria

Principio de integracao entre os servicos

A integracao entre product e admin deve ser preferencialmente assincrona ou orientada a publicacao de estado. O runtime de produto nao deve depender de uma chamada online ao servico administrativo para responder ao cliente.

Regra obrigatoria:

• o atendimento deve continuar funcionando mesmo se o servico administrativo estiver indisponivel.

Modelo de acoplamento permitido

Permitido

• leitura de tools publicadas
• leitura de configuracoes marcadas como ativas
• leitura de versoes aprovadas
• sincronizacao de metadados publicados
• consumo de eventos ou snapshots administrativos

Nao permitido no hot path do atendimento

• gerar tool sob demanda durante o atendimento
• validar codigo em tempo real no runtime do produto
• depender de login administrativo para executar atendimento
• bloquear resposta ao usuario aguardando operacao do servico administrativo

Estrategia de dados

Banco do servico de produto

Responsavel por:

• usuarios de atendimento
• pedidos
• revisoes
• locacoes
• conversas
• estado operacional
• referencias de tools ativas necessarias ao runtime

Banco do servico administrativo

Responsavel por:

• contas internas (StaffAccount)
• sessoes e credenciais administrativas
• configuracoes do sistema
• relatorios consolidados
• drafts de tools
• jobs de geracao
• execucoes de validacao
• publicacoes
• auditoria

Conexao entre dados dos dois servicos

A conexao entre product e admin para relatorios e auditoria operacional segue a seguinte direcao inicial:

1. O product permanece como fonte operacional primaria.
2. Um etl_incremental fora do hot path exporta apenas datasets e campos aprovados em contrato compartilhado.
3. O admin persiste snapshot_table sanitizadas e expoe dedicated_view para APIs e dashboard.
4. Replica operacional pode aparecer depois apenas como fonte de extracao do ETL, nunca como backend direto do painel.

Decisao inicial recomendada:

• manter o produto como fonte operacional
• usar o servico administrativo para leitura consolidada, auditoria e governanca
• evitar escrita administrativa direta nas tabelas operacionais do atendimento, salvo casos explicitamente versionados e controlados

Estrutura tecnica sugerida no monorepo

Produto

• app/ permanece como nucleo do runtime de atendimento
• entrypoints de atendimento e integracoes continuam aqui

Administrativo

Criar uma nova arvore dedicada, por exemplo:

• admin_app/
  • api/
  • services/
  • repositories/
  • models/
  • main.py

Ou, se quisermos maximizar reaproveitamento de convencao atual:

• app_admin/

A escolha do nome pode ser definida na fase de scaffold. O importante nesta ADR e a separacao de runtime e responsabilidade.

Deploy esperado

No medio prazo, o deploy deve prever dois servicos distintos:

• orquestrador-product
• orquestrador-admin

Cada um com:

• variaveis de ambiente proprias
• processo/servico dedicado
• observabilidade propria
• escala independente

Implicacoes para modelo de IA

A geracao de tools e automacao administrativa podem usar um modelo diferente do atendimento. Essa escolha fica facilitada pela separacao de servicos, pois:

• evita disputa de recurso e custo com o chat principal
• permite tuning de latencia e qualidade por caso de uso
• reduz risco de sobrecarregar o atendimento

Regras obrigatorias decorrentes desta ADR

1. O runtime de produto nao executa pipeline de geracao de tools.
2. O servico administrativo nao participa do hot path de resposta ao cliente.
3. Toda tool nova nasce no servico administrativo e so chega ao produto depois de publicada.
4. Relatorios e configuracoes internas pertencem ao servico administrativo.
5. O produto so consome estado publicado e aprovado.
6. Deploys do servico administrativo nao devem exigir redeploy simultaneo do produto, salvo mudanca de contrato compartilhado.

Sequencia recomendada de implementacao

1. Formalizar esta arquitetura em documentacao.
2. Criar fundacao do servico administrativo no monorepo.
3. Implementar StaffAccount, auth e papeis.
4. Criar area de configuracao e relatorios basicos.
5. Criar entidades de draft/publicacao de tools.
6. Implementar pipeline isolado de geracao e validacao.
7. Integrar publicacao de tools com o runtime de produto.

Consequencias

Positivas

• isola o atendimento das cargas administrativas
• melhora seguranca
• facilita escalabilidade independente
• prepara o sistema para governanca e auditoria reais
• reduz risco operacional no produto

Custos

• aumenta a complexidade arquitetural
• exige contratos claros entre servicos
• traz mais trabalho de deploy, observabilidade e configuracao
• exige estrategia de compartilhamento de dados para relatorios

Fora do escopo desta ADR

• implementar o scaffold real do segundo servico
• escolher o modelo definitivo de geracao
• definir o formato final de sincronizacao de dados analiticos
• definir a UI final do painel administrativo