# App Orchestration Internals

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

## Purpose

`internal/app` coordinates top-level use cases: generating one report, 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 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`.
- Render preflight precedes Scriptorium report generation.
- Recent Changes are computed from structured briefing snapshots.
- Metadata links artifacts produced for a run.