Architecture Signals & Invalidated Assumptions — Retrospective

Scope:

• Derived from Weekly Learnings published between 2026-02-15 and 2026-02-20
• No changes made to original Weekly Learnings
• Signals extracted retrospectively

Architecture signals (emergent)

• Pattern: Deterministic analytics engine as system spine (Runs → WeeklySnapshotEngine → TrendEngine → Agents).
• Pattern: Recompute-from-raw invariant as single source of truth enforcement.
• Pattern: Null-object enforcement to stabilise empty-state domain contracts.
• Pattern: Centralised multi-provider abstraction via LLMClient + LiteLLM boundary.
• Pattern: Observability maturation (trace_id propagation, structured logs, span lifecycle discipline).
• Pattern: Platform lifecycle awareness as architectural constraint (HF async bootstrap behaviour).
• Anti-pattern: Model duplication across domain boundaries (parallel models in different layers).
• Anti-pattern: In-memory vs persisted ambiguity during refactor transitions.
• Anti-pattern: Treating empty states as edge cases rather than first-class contracts.
• Heuristic: When complexity spikes, define invariants first, then refactor around them.
• Heuristic: Separate deterministic computation (domain layer) from generative reasoning (agent layer).
• Heuristic: Centralise vendor/provider integration early to reduce blast radius.

Assumptions invalidated

• Assumption: Recompute would implicitly restore deleted historical weeks.
• Assumption: Storage-disabled mode would degrade gracefully without explicit domain contracts.
• Assumption: Async lifecycle behaves consistently across local and managed environments.
• Assumption: Basic logging is sufficient for multi-agent orchestration debugging.
• Assumption: Provider configuration can remain distributed without long-term architectural cost.
• Assumption: Ingestion pipeline (e.g., GPX HR parsing) was sufficiently complete.

Notes on confidence

• Deterministic engine spine and recompute invariant: high confidence (repeated across refactors and bug fixes).
• Provider centralisation via LiteLLM: high confidence (strategic boundary reinforced through integration testing across Gemini, OpenAI, HF).
• Observability as architectural requirement: high confidence (critical in debugging cross-agent and deployment issues).
• Platform lifecycle constraints as recurring driver: medium confidence (environment-specific but strongly evidenced).
• Long-term scalability of recompute-on-startup strategy: tentative (validated manually, not yet stress-tested at larger historical scale).