Visão de camadas

Objetivo arquitetural

A forecast-engine foi desenhada para manter regra de negócio no núcleo e infraestrutura nas bordas. O objetivo é permitir evolução de estratégia sem quebrar invariantes de domínio.

Para a topologia híbrida entre ambiente do cliente e infraestrutura da plataforma, veja Arquitetura híbrida da plataforma.

Diagrama de referência

flowchart LR D["domain"] --> P["application"] P --> A["adapters"] C["contracts"] --> A P -. "ports" .-> X["infra externa"] A -. "implementa ports" .-> X

Responsabilidades por camada (quem faz o quê)

`domain`

define entidades, value objects e invariantes;
falha cedo quando estado ou transição é inválido;
não conhece I/O, framework ou contratos externos.

`application`

orquestra casos de uso (train_candidates_and_promote_champion, activate_model_instance, run_forecast_with_fallback);
consome ports, nunca implementações concretas;
aplica política de promoção de campeão, sincronização com registry e fallback.

`adapters`

traduz formatos externos para linguagem de domínio;
implementa ports com persistência durável, Polars, Parquet, MLflow e contratos;
mantém detalhes técnicos fora de domain e application.

`contracts`

formaliza payloads com tipagem e validação rígida (msgspec);
evita ambiguidades na integração entre serviços.

Regra de dependência (não negociável)

domain não depende de application, adapters nem contracts.
application depende de domain e abstrações (ports).
adapters implementa ports e depende de domain/application/contracts.

Sinais de violação arquitetural

Sinal	Risco	Correção
Entidade de domínio lendo banco/API	acoplamento e regressão em cascata	mover I/O para `adapters` e expor por `ports`
Caso de uso importando implementação concreta	perda de testabilidade	injetar dependência por interface/porta
Contrato externo vazando para `domain`	regra de negócio dependente de formato externo	mapear contrato para entidades no adapter

Mapa de módulos

src/domain/shared        -> erros, IDs, granularidade, UOM e helpers de tempo
src/domain/demand        -> séries e observações de demanda
src/domain/modeling      -> definição, versões, instâncias e promoção
src/domain/forecasting   -> execução de previsão e fallback degradado
src/application/engine   -> casos de uso de treino e inferência
src/application/columnar -> contratos para frames e storage
src/adapters             -> mapeamentos e integrações externas
src/contracts            -> contratos de serialização para integração

Resultado prático dessa arquitetura

evolução de estratégia com baixo risco de regressão de negócio;
melhor auditabilidade de decisões de modelo;
inferência mais resiliente sob falhas parciais;
promoção e observabilidade mais operacionais sem mover lógica de negócio para infraestrutura.