weatherreporter/docs/internal/app-orchestration.md

App Orchestration Internals

This document describes the implemented workflow coordinator in internal/app.

Purpose

internal/app coordinates top-level use cases: generating one report through the shared report-generation path, running morning or evening batches, building inspectable briefing artifacts, fetching weather bundles, and reading existing artifacts for inspection.

Inputs And Outputs

Inputs:

• app request structs containing config, report or batch selection, clock time, optional report date, optional Storm Report bounds, output paths, renderer fakes, or state-store fakes
• resolved report definitions from internal/report
• forecast bundles from the Weather API adapter
• prior briefing snapshots from internal/state

Outputs:

• report results for generated report definitions with briefing, data package, preflight, report, metadata, prior snapshot, Recent Changes, and Scriptorium results
• batch summaries with per-report status and artifact paths
• inspection JSON values for reports, metadata, briefings, data packages, prior snapshots, and source provenance

Boundaries

• The package coordinates workflow order.
• It does not parse CLI flags, load YAML files directly, implement HTTP calls, derive forecast facts, define report periods, compare Markdown, or construct Scriptorium argv.

Config Fields Used

• weather_api.* for Weather API client construction and briefing metadata
• scriptorium.* for renderer construction
• workspace.* for filesystem state
• dayparts for daily and outlook summarization
• recent_change.* for structured Recent Changes thresholds

External Adapters Used

• internal/adapters/weatherapi for forecast bundle fetching
• internal/adapters/scriptorium for render preflight and report generation
• internal/state filesystem store for persisted artifacts

State Or Manifest Behavior

Generation saves the briefing snapshot, data package, preflight result when available, rendered report, and metadata. Metadata links all managed artifact paths. Inspection workflows read existing state and do not fetch weather data or invoke Scriptorium.

Skip And Resume Behavior

There is no resume workflow. Batch generation continues remaining independent reports after one report fails, then reports aggregate success and failure counts.

Failure Behavior

• Resolve errors stop the requested workflow before fetching weather data.
• Weather API or briefing errors stop that report before Scriptorium is called.
• Render preflight runs before Scriptorium report generation.
• If render preflight returns a result and an error, preflight JSON and metadata are persisted before the error is returned.
• If Scriptorium report generation returns an error after writing output, metadata and the managed report path remain inspectable.
• Batch failures are recorded per report and surfaced through aggregate batch failure.

Tests

Inspect:

• internal/app/app_test.go
• internal/cli/root_test.go
• internal/state/filesystem_test.go

Invariants

• Report behavior is resolved through internal/report.
• Generated reports use the same app request and result types regardless of report ID.
• Render preflight precedes Scriptorium report generation.
• Recent Changes are computed from structured briefing snapshots.
• Metadata links artifacts produced for a run.