weatherreporter/docs/internal/app-orchestration.md

App Orchestration Internals

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

Purpose

internal/app coordinates the top-level use cases after CLI parsing and config loading are complete. It resolves report definitions, fetches weather data, builds collected and derived facts, builds module snapshots and prompt-input artifacts, invokes Scriptorium through the adapter boundary, optionally notifies distributor through an app-owned notifier boundary, persists managed state, runs batches, and reads existing artifacts for inspection.

Inputs And Outputs

Inputs:

• GenerateRequest for one report command
• BatchRequest for morning or evening batch commands
• FetchBundleRequest for explicit bundle fetch and save workflows
• ReportRequest for single-report generation
• resolved report definitions from internal/report
• weather data bundles from internal/adapters/weatherapi
• prior snapshots loaded from internal/state
• optional renderer, notifier, and state-store fakes for tests

Outputs:

• generated report results with module snapshot, data package, preflight, report, metadata, prior snapshot, Recent Changes, Scriptorium result details, and notification result when attempted
• batch summaries with per-report status, artifact paths, error text, and notification outcome when attempted
• saved Weather API bundle JSON for fetch workflows
• inspection JSON values for reports, metadata, module snapshots, data packages, prior snapshots, and source provenance

Boundaries

internal/app owns workflow order and request composition. It does not parse CLI flags, load YAML files directly, implement HTTP transport, own fact derivation algorithms, define report periods, compare rendered Markdown, or construct Scriptorium argv.

Report selection and report identity policy come from internal/report. Collected and derived fact contracts come from internal/facts. Weather API transport stays in internal/adapters/weatherapi. Scriptorium subprocess behavior stays in internal/adapters/scriptorium. Distributor upload behavior stays in internal/adapters/distributor. Filesystem layout and persisted metadata stay in internal/state.

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
• notify.distributor.* for optional notification after report generation

Output copy flags are command request fields. They are not configuration defaults.

Generation Workflow

Single-report generation follows this order:

1. Resolve the command report to a report.Resolved value.
2. Create or use a filesystem store.
3. Locate any prior compatible snapshot through internal/state.
4. Fetch a Weather API bundle.
5. Build collected and derived facts once.
6. Execute configured modules and save the module snapshot.
7. Compute Recent Changes from structured prior and current module snapshots.
8. Build and save the YAML Scriptorium data_package.
9. Run Scriptorium render preflight.
10. Save preflight JSON when a render result is available.
11. Save metadata for inspection.
12. Run Scriptorium report generation to the managed report path.
13. Copy the managed report to the requested --out path when provided.
14. Save metadata with the managed report path.
15. If distributor notification is enabled, notify using the managed report path as the source file.
16. Save a distributor notification debug artifact and update metadata with its path.

If render preflight returns both 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, the managed report and metadata remain inspectable. Notification is not attempted after Weather API, module snapshot, prompt input, render, Scriptorium run, or metadata-save failures. When notification is attempted, the debug artifact records request identity, including rendered pipeline ID, bundle paths, accepted upload fields, distributor status fields, raw status report JSON when available, and redacted failure context. --out copies are never used as notification source files.

Batch Workflow

run morning resolves Daily Today, 3-Day Outlook, and Weekend Outlook except on Sunday. run evening resolves Daily Tomorrow. Batch output copy names come from report definitions. Batch generation continues independent reports after a failure, records each result, writes compact status lines to stderr, emits a JSON summary to stdout, and returns an aggregate error when any report failed. When notification is enabled, each successfully generated report is notified independently. Notification failure marks that report failed, records notification fields in the batch result, and does not stop later reports. --out-dir copies are never used as notification source files.

Inspection Workflow

Inspection workflows load existing filesystem state only. They do not fetch weather data or invoke Scriptorium. Run-specific inspect commands share the same store and metadata lookup path, then load the requested artifact or derived inspection view.

Failure Behavior

• Resolve errors stop the requested workflow before fetching weather data.
• Weather API and briefing errors stop that report before Scriptorium runs.
• Prompt input validation fails before render preflight.
• Render and run errors preserve Scriptorium stderr and exit-code context.
• Notification errors are wrapped with report ID, RunID, and managed report path context and are recorded separately in batch results.
• Metadata and artifact path errors include filesystem context.
• Batch failures are recorded per report and surfaced through an aggregate batch error.

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 module snapshots.
• Metadata links artifacts produced for a run.
• Distributor notification maps the managed Markdown report path to configured bundle paths; extra output copies are not upload sources.