124 lines
4.8 KiB
Markdown
124 lines
4.8 KiB
Markdown
# 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 briefing and prompt-input artifacts, invokes Scriptorium through the
|
|
adapter 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
|
|
- `BriefingRequest` and `ReportRequest` for package-level orchestration tests
|
|
and internal composition
|
|
- resolved report definitions from `internal/report`
|
|
- forecast bundles from `internal/adapters/weatherapi`
|
|
- prior snapshots loaded from `internal/state`
|
|
- optional renderer and state-store fakes for tests
|
|
|
|
Outputs:
|
|
|
|
- generated report results with briefing, data package, preflight, report,
|
|
metadata, prior snapshot, Recent Changes, and Scriptorium result details
|
|
- batch summaries with per-report status, artifact paths, and error text
|
|
- saved Weather API bundle JSON for fetch workflows
|
|
- inspection JSON values for reports, metadata, briefings, 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, derive forecast
|
|
facts, define report periods, compare rendered Markdown, or construct
|
|
Scriptorium argv.
|
|
|
|
Report selection and report identity policy come from `internal/report`.
|
|
Weather API transport stays in `internal/adapters/weatherapi`. Scriptorium
|
|
subprocess behavior stays in `internal/adapters/scriptorium`. 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
|
|
|
|
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 a report-specific briefing package.
|
|
6. Save the briefing snapshot.
|
|
7. Compute Recent Changes from structured prior and current briefings.
|
|
8. Build and save the 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.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
- 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 briefing snapshots.
|
|
- Metadata links artifacts produced for a run.
|