PolyWeather/docs/TECH_DEBT.md

Technical Debt Backlog

Purpose: keep engineering debt explicit while shipping production features.

---

1. Debt Landscape

flowchart TD
    A["Tech Debt"]

    subgraph AR["Architecture"]
        AR1["Monolithic bot entry"]
        AR2["Shared runtime coupling"]
    end

    subgraph PI["Product Infra"]
        PI1["Entitlement hardening"]
        PI2["Subscription persistence"]
    end

    subgraph Q["Quality"]
        Q1["Replay harness"]
        Q2["Broader regression tests"]
    end

    subgraph O["Observability"]
        O1["Alert evidence trace"]
        O2["SLO dashboards"]
    end

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

Current system health estimate: 84% stable / 16% debt.

---

2. Recently Closed (2026-03-11)

• Meteoblue API path fully removed from backend, frontend, config and docs.
• Market top-bucket duplicate temperature issue fixed (backend dedupe + frontend guard).
• Detail panel a11y conflict fixed (aria-hidden focus conflict resolved with inert + blur).
• Vercel Speed Insights integrated for frontend performance telemetry.

---

3. High Priority Debt

Item	Impact	Suggested Work
Monolithic bot entry (bot_listener.py)	Hard to test and safely refactor	Split orchestration, IO and analysis modules
Entitlement enforcement consistency	Revenue leakage risk	Align frontend middleware and backend enforcement
Subscriber persistence model	Manual operations do not scale	Move to managed PostgreSQL/Supabase state
Alert explainability	Operator trust and debugging cost	Standardize evidence payload per alert

---

4. Medium Priority Debt

Item	Impact	Suggested Work
Replay simulation harness	Hard to reproduce edge cases	Build deterministic replay over stored records
Chart/UI regression coverage	Visual regressions can slip	Add snapshot + interaction test coverage
Config centralization	Threshold changes are error-prone	Consolidate runtime knobs into structured config
Naming cleanup	Legacy terms reduce clarity	Refactor naming in market/weather boundary layer

---

5. Low Priority Debt

Item	Impact	Suggested Work
Cold-start behavior	First request latency variance	Add warming strategy for top city routes
Storage abstraction	Local file assumptions remain	Continue moving state to remote services

---

6. Next Milestones

1. Entitlement parity: one policy across frontend and backend.
2. Subscriber DB integration and migration scripts.
3. Alert evidence schema + tooling for quick operator audit.
4. Replay runner for weather/market mixed regression scenarios.

---

Last Updated: 2026-03-11