You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
150 lines
4.0 KiB
Markdown
150 lines
4.0 KiB
Markdown
# 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.
|
|
|
|
|
|
|