PolyWeather/docs/TECH_DEBT.md

Technical Debt

Last updated: 2026-03-06

Current State

Overall system status: usable and deployable.

Stable pieces:

• Multi-source weather collection
• DEB forecast blending
• Web dashboard on Vercel
• FastAPI API backend
• Telegram proactive push loop
• Alert dedupe and cooldown
• Late-day peak suppression

Recently removed:

• Old FastAPI static web page
• Polymarket market-price integration
• /tradealert preview command

High-Priority Debt

1. Bot orchestration is still too centralized

bot_listener.py is operational, but too much runtime behavior is still coordinated from a single entrypoint.

Impact:

• Harder to test
• Harder to evolve subscription logic
• Harder to isolate push bugs

Suggested direction:

• Keep moving push and analysis concerns into src/utils and src/analysis

2. Alert transparency needs better operator visibility

The system now pushes the correct trigger types more conservatively, but group operators still need better evidence lines.

Impact:

• Hard to audit why a message fired
• Hard to distinguish strong vs weak advection calls

Suggested direction:

• Add a compact 依据 / Evidence line to alert messages
• Expose raw trigger metrics in a debug API or operator log

3. No persistent application store for subscriptions

Current architecture is ready for commercialization planning, but there is no real subscription state model yet.

Impact:

• No paid access enforcement
• No renewal logic
• No expiry / access revocation

Suggested direction:

• Add a database-backed subscription table before automating billing

Medium-Priority Debt

4. Backtesting is still missing

The system has live rules, but no proper replay framework for validating whether rule changes improve quality.

Impact:

• Rule changes are hard to evaluate objectively
• Alert tuning is still partly manual

Suggested direction:

• Build a replay harness from stored observations and forecasts

5. Thresholds remain code-defined

Important thresholds are still embedded in Python.

Examples:

• Momentum slope threshold
• Peak-passed rollback threshold
• Advection lead delta threshold
• Cooldown defaults

Suggested direction:

• Extract to constants or structured config

6. Frontend still uses a legacy shell inside Next

The production frontend is on Vercel, but the page is still driven by public/legacy/index.html plus static scripts.

Impact:

• Slower UI evolution
• Harder component-level reuse
• Harder design-system integration

Suggested direction:

• Migrate the legacy dashboard into native Next components incrementally

Low-Priority Debt

7. Caching is simple in-process cache only

Current cache is sufficient for the current deployment size, but not ideal long term.

Suggested direction:

• Move to Redis or another shared cache if multi-instance deployment is needed

8. Test tooling is not fully provisioned everywhere

The repository has tests, but some environments still do not have pytest installed.

Impact:

• Harder to run full verification on every host

Suggested direction:

• Standardize test dependencies in deployment and CI environments

Immediate Next Steps

1. Add evidence lines to Telegram alerts
2. Finish cleaning backend naming after removal of old static web flow
3. Design subscription storage for commercialization
4. Start replay/backtest tooling for alert-quality tuning