PolyWeather/docs/TECH_DEBT.md

Technical Debt Backlog

Purpose: keep engineering debt explicit while shipping production features.

---

1. Debt Snapshot

Current estimate: 90% stable / 10% debt.

flowchart TD
    A["Tech Debt"]

    subgraph PI["Payment Infra"]
        PI1["Payment event ingestion"]
        PI2["Subscriber persistence"]
        PI3["Entitlement parity"]
    end

    subgraph Q["Quality"]
        Q1["Replay harness"]
        Q2["Mixed integration tests"]
    end

    subgraph O["Observability"]
        O1["Alert evidence schema"]
        O2["Ops dashboards"]
    end

    A --> PI
    A --> Q
    A --> O

---

2. Recently Closed (2026-03-12)

• Bot entry refactor completed:
  • bot_listener.py simplified to thin entrypoint.
  • Runtime split into orchestrator/handlers/services/analysis/guard/coordinator layers.
• Startup diagnostics landed:
  • /diag command
  • loop-level startup status reporting (trade alerts, polygon watcher, polymarket watcher)
• Multi-model anchor migration completed for mispricing radar (replaced single Open-Meteo anchor).
• Non-tradable market hard-skip guard completed (closed/inactive/not accepting orders/past end time).
• Wallet activity watcher upgraded with alias parsing, link preview switch, and anti-spam debounce/immediate controls.
• Frontend BFF HTTP caching (ETag/304) completed for cities/summary/history.
• Meteoblue fully removed from runtime paths and docs.

---

3. Active High-Priority Debt

Item	Impact	Suggested Work
Payment event ingestion pipeline	Cannot automate paid access reliably	Build idempotent onchain payment ingest + reconciliation worker
Subscriber persistence model	Manual entitlement ops do not scale	Add managed PostgreSQL/Supabase subscriber state
Entitlement parity matrix	Access leaks/false denies across channels	Unify policy across frontend middleware, backend API, and bot guard
Alert evidence contract	Harder to debug false positives quickly	Standardize machine-readable evidence schema for each push

---

4. Active Medium-Priority Debt

Item	Impact	Suggested Work
Replay simulation harness	Edge-case regressions hard to reproduce	Deterministic replay from stored weather + market snapshots
End-to-end integration coverage	Runtime regressions can slip	Add integration tests for /api/city/{name}/detail + push decisions
Config sprawl	Tuning is error-prone	Consolidate env knobs into structured config groups
Naming and data contracts	Boundary confusion persists	Normalize model/market field naming and compatibility aliases

---

5. Active Low-Priority Debt

Item	Impact	Suggested Work
Cold-start variance	First request latency jitter	Add prewarm strategy for top city routes
Local state files	Harder multi-instance scaling	Continue migration to managed storage

---

6. Next Milestones

1. Land subscriber DB + entitlement expiry model.
2. Ship payment ingest + automatic entitlement sync.
3. Add replay harness for weather/market mixed scenarios.
4. Publish alert evidence schema and operator tooling.

---

Last Updated: 2026-03-12