# Estrutura Alvo do Monorepo

Este documento define a estrutura alvo do monorepo apos a decisao de separar o runtime de produto do servico administrativo.

## Objetivo
Manter dois servicos distintos, mas ligados:

- `orquestrador-product`: atendimento e operacao do produto
- `orquestrador-admin`: autenticacao interna, configuracao, relatorios e governanca de tools

A prioridade desta fase e estrutural:
- preservar o runtime atual do produto
- introduzir o scaffold do servico administrativo
- criar um lugar claro para contratos compartilhados

## Decisao de transicao
Nesta etapa, o codigo atual do produto permanece em `app/`.
Nao vamos mover o runtime de produto agora para evitar churn desnecessario, quebra de import e risco operacional.

Portanto, a estrutura final de curto e medio prazo fica assim:

```text
app/                         # runtime atual do produto
admin_app/                   # novo runtime administrativo
shared/                      # contratos e artefatos compartilhados entre servicos

docs/
  adr/
  architecture/

deploy/
  systemd/
  # evoluira para suportar servicos distintos
```

## Estrutura do servico de produto
O servico de produto continua centralizado em `app/`.

Responsabilidades:
- atendimento conversacional
- integracoes com canais externos
- orquestracao em tempo de execucao
- leitura de tools publicadas
- regras operacionais de vendas, revisao e locacao

## Estrutura do servico administrativo
O servico administrativo passa a nascer em `admin_app/`.

Estrutura alvo inicial:

```text
admin_app/
  app_factory.py
  main.py
  __main__.py
  api/
    dependencies.py
    router.py
    routes/
      system.py
      # auth.py
      # staff_accounts.py
      # tool_drafts.py
      # reports.py
  core/
    settings.py
    security.py
  db/
    models/
      staff_account.py
      # tool_draft.py
      # tool_generation_job.py
      # tool_publication.py
      # audit_log.py
  repositories/
    # staff_account_repository.py
    # tool_draft_repository.py
  services/
    # auth_service.py
    # tool_draft_service.py
    # report_service.py
```

## Estrutura compartilhada
Tudo que for contrato entre servicos deve ficar em `shared/`.

Regras:
- `shared/` nao deve conter regra de negocio de atendimento
- `shared/` nao deve conter dependencias do hot path do Telegram
- `shared/` deve armazenar apenas contratos, DTOs, enums, nomes de eventos e utilitarios realmente compartilhados

Estrutura inicial:

```text
shared/
  contracts/
    access_control.py
    tool_publication.py
    # settings_snapshot.py
    # report_filters.py
```

## Regras de organizacao do monorepo

1. `app/` continua sendo o produto ate eventual migracao planejada.
2. `admin_app/` nasce isolado e nao deve importar modulos internos de atendimento por conveniencia.
3. `shared/` e o unico lugar recomendado para contratos reutilizados por ambos os servicos.
4. O servico administrativo nao deve depender do runtime do Telegram para inicializar.
5. O servico de produto nao deve depender do servico administrativo no hot path.
6. Hierarquia de acesso administrativa deve nascer em shared/contracts/access_control.py.

## Import boundaries

### Permitido
- `admin_app` importar `shared`
- `app` importar `shared`

### Nao permitido
- `admin_app` importar `app.services.orchestration` para executar atendimento
- `app` importar `admin_app.services` no fluxo de atendimento
- colocar metadados administrativos dentro de `app/services/orchestration`

## Estrategia de evolucao

### Fase atual
- criar scaffold do `admin_app`
- criar `shared/`
- documentar a topologia do monorepo

### Fase seguinte
- implementar `StaffAccount`
- criar auth administrativa
- subir primeiras rotas internas no `admin_app`

### Fase posterior
- publicar contratos compartilhados em `shared/`
- plugar pipeline de drafts, validacao e publicacao de tools

## Impacto em deploy
Por enquanto, o deploy atual do produto permanece como esta.
Quando o admin ganhar runtime real, o deploy vai evoluir para dois servicos distintos:

- `orquestrador-product`
- `orquestrador-admin`

Sem mover o runtime atual de `app/` nesta etapa.