orquestrador/docs/architecture/monorepo-target-structure.md

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:

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:

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:

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.