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, compares prior snapshots, executes exact-version Promptkit prompts, validates structured generated prose, and renders repository-owned Markdown. Completed managed Markdown may 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 workflow order, partial results, 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.
• internal/state owns workspace paths, V2 metadata, atomic persistence, and read-only inspection.

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 inspects 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.
• Prepared execution persists safe preparation provenance before provider work. Completed execution persists safe execution provenance; raw output is validated before template rendering.
• Generated text fills defined prose slots only. Deterministic facts remain authoritative and repository-owned templates produce all managed Markdown.
• Sensitive rendered prompts, schemas, input bodies, provider endpoints, and credentials never enter normal metadata, summaries, logs, or workspace artifacts. They are written only to an explicit secure debug root when requested.

State, Notification, And Testing Invariants

• Managed writes are atomic where practical and stay beneath the configured workspace root. Reached artifacts remain inspectable after later failures.
• New records use weatherreporter.metadata.v2; V1 records remain readable for inspection compatibility.
• Distributor uploads use only the managed Markdown report, never output copies or workspace scans. Notification follows report and final metadata success.
• 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.