90 lines
3.1 KiB
Markdown
90 lines
3.1 KiB
Markdown
# 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.
|