Document internal component boundaries

docs/internal/app-orchestration.md

@@ -0,0 +1,89 @@
+# 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.