74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# Architecture Policy
|
|
|
|
## Purpose
|
|
|
|
This policy defines Weatherreporter's system shape, ownership, dependency direction,
|
|
and safety invariants. The [development guide](../development.md) 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](testing.md).
|
|
|
|
## 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.
|