weatherreporter/docs/internal/app-orchestration.md

App Orchestration Internals

This document describes the 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 JSON module snapshot, YAML data package, preflight, report, metadata, prior snapshot, Recent Changes, Scriptorium result details, generated-text artifact paths when applicable, 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.

Data Flow Terms

• CollectedFacts are normalized source facts fetched once from Weather API and made available to derivation and module builders.
• DerivedFacts are deterministic calculations over collected facts, the resolved valid period, daypart configuration, and report-specific windows.
• module.Output values are ordered deterministic stanzas built from collected and derived facts for prompt input and inspection.
• GeneratedText is structured prose returned by Scriptorium for generated-text-template reports and validated by internal/generatedtext.
• RenderContext is the typed template input built from report metadata, module outputs, and validated generated text before Markdown rendering.

Config Fields Used

• weather_api.* for Weather API client construction and module 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 shares this setup:

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.

For scriptorium_markdown reports, generation then:

12. Runs Scriptorium report generation to the managed report path.

For generated_text_template reports, generation then:

12. Looks up the generated-text catalog entry for the report schema/template IDs.
13. Runs structured Scriptorium generation to the raw generated-text JSON path.
14. Saves the structured Scriptorium run result.
15. Validates and saves normalized generated text.
16. Builds and saves a typed render context.
17. Renders Markdown from the embedded template to the managed report path.

After either mode has produced a managed Markdown report, shared finalization:

1. Copies the managed report to the requested --out or --out-dir path when provided.
2. Saves final metadata with the managed report path and any generated-text artifact paths already produced.
3. If distributor notification is enabled, notifies using the managed report path as the source file.
4. Saves a distributor notification debug artifact and updates 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. Generated-text report failures are returned with report ID, RunID, and the failed operation. When available, the app preserves the latest generated-text artifacts already reached by the workflow: preflight output, structured run result, raw generated text, validated generated text, and render context. 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 Today Report, 3-Day Outlook, and Weekend Outlook except on Sunday. run evening resolves Tomorrow Report. Daily Report is generated only through generate daily --date YYYY-MM-DD; it is not part of scheduled batches. 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 module execution 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.
• Generated-text report errors preserve available intermediate artifacts and do not create extra output copies.
• 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.
• Generated-text reports render Markdown from a curated render context, not from a raw data package.
• 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.