# 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