Code map

Estrutura principal

src/
  domain/
    shared/
    demand/
    modeling/
    forecasting/
  control/
    modeling/
    data_preparation/
  infra/
    dags/
    jobs/
    orchestration/
    data_preparation/
      spark/
      polars/
    http/
    persistence/
      clickhouse/
    ingestion/
    mlflow/
    observability/
    modeling/
      nixtla/

Onde fica cada responsabilidade

Responsabilidade	Módulo
Value objects, erros, tempo e UOM	`src/domain/shared/`
Identidade semântica da série, snapshots de treino e contextos de demanda	`src/domain/demand/`
Definição, versões e instâncias de modelo	`src/domain/modeling/`
Pontos de forecast e estruturas de avaliação	`src/domain/forecasting/`
Submissão de workflow, treino e promoção de campeãs	`src/control/modeling/`
Materialização de snapshot e boundaries de data-preparation	`src/control/data_preparation/`
DAGs Airflow	`src/infra/dags/`
Entry points executáveis pelas DAGs	`src/infra/jobs/`
Adapter HTTP para disparar DAG runs	`src/infra/orchestration/`
Type variables de payload de treino e forecast	`src/control/frame_types.py`
Schemas canônicos nomeados de frames	`src/control/data_preparation/frame_schemas.py`
Contratos e helpers comuns de feature engineering e perfil de série	`src/control/data_preparation/ports.py`, `src/control/data_preparation/feature_steps.py`
Materialização, leitura bruta, projeção por série, parquet e pipelines canônicos em Spark	`src/infra/data_preparation/spark/`
Execução de treino/predição em Polars, incluindo leitura de partições por série e forecast recursivo com features	`src/infra/data_preparation/polars/`
API HTTP e auth JWT	`src/infra/http/`
Schemas `msgspec` de payloads HTTP	`src/infra/http/schemas.py`
Schemas `msgspec` de manifests de configuração	`src/infra/config/manifest.py`
Normalização de JSON aberto para `ParamsMap` de domínio	`src/infra/payloads/json.py`
ClickHouse raw SQL, migrations, records persistidos e mapeadores	`src/infra/persistence/clickhouse/`
Stores locais/S3 de artefatos	`src/infra/persistence/file_store.py`, `src/infra/persistence/s3_store.py`
Manifest e storage de snapshots	`src/infra/ingestion/`
MLflow tracking, packaging e registry de campeões	`src/infra/mlflow/`
Logger, helper de logs e porta de telemetria operacional	`src/control/observability/`
Adapter OpenTelemetry, métricas Prometheus e exportação OTLP de traces	`src/infra/observability/`
Value objects de path/locator compartilhados	`src/domain/shared/value_objects.py`
Estratégias concretas Nixtla	`src/infra/modeling/nixtla/`

Arquivos de entrada úteis

src/control/modeling/config/use_cases.py: atualização da configuração das definições de modelo.
src/control/modeling/config/models.py: comandos e views da configuração de modelo.
src/control/modeling/config/revision_use_cases.py: ativação e resolução de revisões tipadas por política de validação, projeção, features, política de modelagem e reaproveitamento de campeã.
src/control/modeling/shared/configuration.py: configuração resolvida por série, fingerprints e política congelada de promoção compartilhados por config, treino, promoção e predição.
src/control/modeling/shared/contracts.py: API entre orquestração de modeling e estratégias treináveis/preditivas.
src/control/modeling/shared/strategy_ports.py: contratos do catálogo e das estratégias de modelo usados por config, treino e predição.
src/control/modeling/shared/model_ports.py: porta do repositório do aggregate ModelDefinition, nomeada pelo aggregate e não por um workflow específico.
src/control/modeling/workflow_models.py: comandos que pertencem a composições entre slices, não ao treino ou à promoção isoladamente.
src/control/modeling/workflows.py: composições command-side entre slices, como treino seguido de promoção de campeã.
src/control/modeling/training/job_use_cases.py: cria snapshot e dispara workflow de treino no Airflow.
src/control/modeling/training/use_cases.py: entrypoint público do comando de treino.
src/control/modeling/training/preparation.py: carregamento, validação e projeção dos inputs do treino.
src/control/modeling/training/execution.py: execução dos work items planejados e geração de candidatas.
src/control/modeling/training/planner.py: resolução de estratégias candidatas, decisões por série e work items executáveis.
src/control/modeling/training/models.py: contexto de treino, decisões por série, work items e estado transitório de treino.
src/control/modeling/training/ports.py: portas específicas de treino, tracking, leitura/escrita de artefatos e workflow.
src/control/modeling/training/reporting.py: contrato typed do training_report.json e montagem do relatório pós-promoção a partir de perfis já extraídos pela porta de data-preparation.
src/control/modeling/promotion/use_cases.py: entrypoint público de promoção completa após treino.
src/control/modeling/promotion/planning.py: recarregamento de candidatas, seleção de campeãs e montagem de planos.
src/control/modeling/promotion/publishing.py: publicação de versões imutáveis no registry externo.
src/control/modeling/promotion/committing.py: commit local das campeãs e auditorias.
src/control/modeling/promotion/syncing.py: sincronização de aliases externos depois do commit local.
src/control/modeling/prediction/preparation.py: seleção de instâncias ativas e reconstrução do dataset projetado para forecast.
src/control/modeling/prediction/execution.py: execução de forecast por série selecionada.
src/control/modeling/promotion/models.py: resultados e estado transitório de promoção.
src/control/modeling/promotion/ports.py: porta de persistência usada pela promoção.
src/control/modeling/promotion/records.py: auditoria durável de promoções.
src/control/modeling/serving/models.py: contratos de publicação e packaging para o registry externo.
src/control/modeling/serving/ports.py: portas de registry externo e packaging.
src/control/modeling/training/records.py: registros de workflow e execução de treino.
src/control/observability/logging.py: emissão best-effort de logs de aplicação dos use cases.
src/control/observability/telemetry.py: porta de observabilidade operacional usada pelos use cases sem acoplar OpenTelemetry ao control layer.
src/infra/modeling/strategy_catalog.py: catálogo process-local de estratégias.
src/infra/dags/model_training.py: DAG Airflow model_training.
src/infra/dags/model_prediction.py: DAG Airflow model_prediction.
src/infra/jobs/materialize_snapshot.py: entrypoint da task de materialização.
src/infra/jobs/train_model_candidates.py: entrypoint da task de treino.
src/infra/jobs/execute_model_forecasts.py: entrypoint da task de forecast batch.
src/infra/jobs/publish_training_champions.py: publica versões imutáveis das campeãs selecionadas.
src/infra/jobs/commit_training_champion_promotions.py: grava promoções e auditorias em lote no ClickHouse.
src/infra/jobs/sync_training_champion_aliases.py: sincroniza aliases externos depois do commit local.
src/infra/jobs/bootstrap.py: composição de dependências para jobs Airflow.
src/infra/orchestration/airflow.py: adapter que chama a API do Airflow.
src/control/modeling/training/execution.py: entrypoint interno do treino; executa work items por série.
src/domain/demand/training.py: snapshot de demanda, contexto por série, dataset de treino, split semântico de holdout, contrato do perfil de série e classificação de séries de demanda a partir das estatísticas calculadas pelo runtime.
src/infra/data_preparation/spark/snapshot_frame_repository.py: leitura bruta e escrita Parquet pelo Spark.
src/infra/data_preparation/spark/training_series_projection.py: projeção Spark do frame canônico para series_projection_recipe, com escrita particionada por SeriesKey.series_id.
src/infra/data_preparation/polars/training_operations.py: execução de treino, split mecânico dos frames e leitura das partições de série projetadas.
src/control/data_preparation/holdout.py: split temporal de holdout no command side.
src/control/data_preparation/materialization.py: snapshot e convenção de keys da materialização canônica.
src/domain/shared/value_objects.py: locators compartilhados para storage genérico e locators de input de demanda com source_format explícito.
src/infra/http/app.py: composição da API.
src/infra/http/bootstrap.py: composição HTTP, JWT, ClickHouse e Airflow trigger.
src/infra/observability/otel.py: runtime OpenTelemetry/Prometheus injetado no HTTP adapter e nos jobs.

Como ler o código

Comece em control/* para entender o fluxo.
Vá para domain/* quando precisar validar invariantes.
Use infra/dags para o ordering do workflow.
Use infra/jobs para ver a composição concreta de cada task.
Use infra/orchestration quando a dúvida for o trigger HTTP -> Airflow.
Vá para infra/* apenas quando precisar do detalhe de infraestrutura.

Esse mapa substitui a referência manual por módulo. Para detalhes finos de tipos, campos e funções, prefira o código fonte e as rotas, DAGs e entrypoints atuais listados acima.