weatherreporter/docs/policy/architecture.md

Architecture Policy

Purpose

This policy defines Weatherreporter's system shape, ownership, dependency direction, and safety invariants. The development guide owns the package inventory; focused documents in docs/internal/ own implementation detail.

System Shape

Weatherreporter is a deterministic weather-report CLI. It collects normalized weather data, derives facts and modules, builds a curated YAML data package, executes exact-version Promptkit prompts, validates structured generated prose, and renders repository-owned Markdown in memory. Completed Markdown is atomically published to an operator-owned output destination and may then be uploaded through Distributor.

The supported report products are Daily, Today, Tomorrow, and Hourly. A batch collects once, validates its complete candidate prompt/profile set before collection, then executes planned reports sequentially with one executor. It continues after independent report failures and sends a batch notification only after every planned report succeeds.

Ownership And Boundaries

• internal/cli owns command parsing, help, summaries, and one executor construction per action.
• internal/config owns defaults, loading, validation, and secret loading.
• internal/app owns in-memory workflow order, partial results, atomic output publication, and notification coordination through project-owned contracts.
• Deterministic domain packages own weather derivation, report periods, modules, generated-text validation, and template contexts.
• internal/adapters/weatherapi, internal/adapters/promptkit, and internal/adapters/distributor own their external dependency mechanics.

Dependency-specific Promptkit types remain inside its adapter. The application does not parse flags, construct provider clients, or render provider output directly.

Prompt Execution Invariants

• Prompts receive curated module packages, never unbounded raw weather payloads.
• Every execution validates the exact prompt version and output contract before collection. The selected profile is configured explicitly or declared by the prompt; unsupported direct-key profiles and missing reported credentials fail before collection.
• Prompt and profile validation completes before weather collection. Raw output is validated before template rendering.
• Generated text fills defined prose slots only. Deterministic facts remain authoritative and repository-owned templates produce all Markdown output.
• Sensitive rendered prompts, schemas, input bodies, provider endpoints, and credentials never enter normal summaries or logs. They are written only to an explicit secure debug root when requested.

Output, Notification, And Testing Invariants

• Normal execution is stateless: it keeps weather data, prompt input, generated text, and render context in memory and creates no application-owned durable state.
• Markdown writes are atomic at an operator-selected destination. A pre-publication failure does not replace an existing destination; a notification failure does not remove a newly published output.
• Distributor uploads use only the published Markdown output, never a scan of local files. Single notification follows publication; batch notification follows publication of every selected report.
• Default tests are deterministic, offline, and use Promptkit/provider fakes rather than live provider calls. See the testing policy.

Non-Goals

Weatherreporter is not a weather-data ingestion service, general LLM orchestration framework, plugin platform, HTTP service, multi-user job system, or a replacement for Promptkit or Distributor.