Visão geral

A forecast-engine sustenta o ciclo completo de inteligência da plataforma:

treino de candidatos;
avaliação e promoção de campeão;
inferência em produção;
fallback degradado quando há falha de execução;
rastreabilidade de decisões e versões de modelo.

Leitura rápida (5 minutos)

Se você está chegando agora, siga esta ordem:

Propósito: limites e compromissos da engine.
Quickstart: validação local do fluxo essencial.
Fluxos principais: entendimento de treino/promoção e fallback.
Arquitetura híbrida da plataforma: fronteira entre o ambiente do cliente, nossa AWS, ML e PostgreSQL.

Fluxo ponta a ponta

flowchart LR A["Histórico de demanda"] --> B["Treino de candidatos"] B --> C["Seleção e promoção de campeão"] C --> D["Inferência em produção"] D --> E{"Falha no ativo?"} E -- "Não" --> F["ForecastRun COMPLETED"] E -- "Sim" --> G["Fallback para versão anterior"] G --> H{"Fallback válido?"} H -- "Sim" --> I["COMPLETED (degraded=True)"] H -- "Não" --> J["ForecastRun FAILED"]

Princípios operacionais

Consistência de domínio: estados inválidos são bloqueados por invariantes explícitas.
Confiabilidade operacional: previsão tenta fallback controlado antes de falhar.
Governança de modelo: promoção e versionamento são auditáveis.
Integração segura: contratos msgspec rígidos evitam payload ambíguo.

Mapa da documentação por objetivo

Objetivo	Onde ler primeiro	Resultado esperado
Entender o papel da engine no produto	Propósito	Clareza de escopo e não-escopo
Rodar o ciclo mínimo local	Quickstart	Ambiente validado e fluxo essencial funcional
Entender a topologia cliente + plataforma	Arquitetura híbrida da plataforma	Clareza sobre fronteiras de dados, S3, ML e PostgreSQL
Operar casos de uso da aplicação	Guia do usuário	Execução segura de modelagem, treino e previsão
Revisar regras de negócio em profundidade	Domínio detalhado	Entendimento de invariantes por camada
Integrar com infraestrutura externa	Contratos e adapters	Fronteira de integração sem vazamento de domínio
Inspecionar APIs por módulo	Referência de API	Navegação rápida por classes e funções

Estrutura do pacote

src/
  domain/
    shared/
    demand/
    modeling/
    forecasting/
  application/
    engine/
    columnar/
  adapters/
    columnar/
    mlflow/
  contracts/

Próximo passo recomendado

Comece por Propósito e avance para Quickstart.