5.8 KiB
Stemwijzer Improvement Roadmap
Created: 2026-04-24 Status: Active
This roadmap captures 17 improvement opportunities identified during a codebase review, organized into 5 phases by dependency and risk. Each item links to a detailed implementation plan (created separately) when available.
Phase 1: Foundation (CI/CD, Config, Documentation)
Prerequisite for everything else. Low risk, high developer-experience impact.
| # | Improvement | Priority | Effort | Plan | TDD |
|---|---|---|---|---|---|
| 1 | Fix broken CI test workflow (mindmodel-schedule.yml references missing requirements.txt) | High | Small | P1-001 | Yes |
| 2 | Fix docker-compose.yml (missing scheduler.py) | High | Small | P1-002 | No (config) |
| 3 | Consolidate duplicate config sources (config.py vs analysis/config.py) | Medium | Small | P1-003 | Yes |
| 4 | Rewrite README.md (22 lines → proper quickstart) | High | Small | P1-004 | No (docs) |
| 5 | Add pyright type-checking to CI | Medium | Small | P1-005 | Yes |
| 6 | Activate pre-commit hooks (black, ruff, isort) | Medium | Small | P1-006 | Yes |
Phase goal: Reliable CI, clean config, and onboarding docs that don't require discovering ARCHITECTURE.md.
Phase 2: Code Quality (Logging, Error Handling, Import Safety)
Builds on Phase 1 CI. Makes the codebase maintainable and production-ready.
| # | Improvement | Priority | Effort | Plan | TDD |
|---|---|---|---|---|---|
| 7 | Replace ~225 print() calls with structured logging | Medium | Medium | P2-001 | Yes |
| 8 | Fix broad except Exception: blocks in database.py and api_client.py |
Medium | Medium | P2-002 | Yes |
| 9 | Complete import-safe module guards (extend existing work) | Medium | Medium | — | Yes |
Phase goal: Observable, debuggable production behavior with clear error propagation.
Phase 3: Architecture (Decompose explorer.py)
Already partially completed. Remaining work is decoupling Streamlit from tab logic.
| # | Improvement | Priority | Effort | Plan | TDD |
|---|---|---|---|---|---|
| 10 | Complete explorer.py decomposition (extract tab logic from Streamlit) | Medium | Large | P3-001 | Yes |
Status: Constants extracted to analysis/config.py, placeholder tab modules created. Remaining: move build_*_tab functions out of explorer.py while preserving @st.cache_data decorators.
Phase goal: explorer.py under 1500 lines, tab modules independently testable.
Phase 4: New Features
User-facing value. Depends on Phase 2 for observability and Phase 3 for clean architecture.
| # | Improvement | Priority | Effort | Plan | TDD |
|---|---|---|---|---|---|
| 11 | REST API layer (read-only, FastAPI) | Low | Large | P4-001 | Yes |
| 12 | Automated pipeline scheduling (real scheduler.py) | Medium | Medium | P4-002 | Yes |
| 13 | Motion recommendation engine | Low | Medium | P4-003 | Yes |
| 14 | Export user voting profile (JSON/CSV/shareable image) | Low | Small | P4-004 | Yes |
| 15 | Data quality dashboard (Streamlit page or API) | Medium | Medium | P4-005 | Yes |
Phase goal: External API consumers, automated data freshness, and user engagement features.
Phase 5: Observability & Robustness
Production confidence. Can run in parallel with Phase 4.
| # | Improvement | Priority | Effort | Plan | TDD |
|---|---|---|---|---|---|
| 16 | Add Sentry or error tracking | Low | Small | P5-001 | No (config) |
| 17 | Pipeline health checks / alerting script | Medium | Medium | P5-002 | Yes |
| 18 | Benchmark suite (pytest-benchmark for SVD/fusion) | Low | Small | P5-003 | Yes |
Phase goal: Know when things break before users do; detect performance regressions.
Dependency Graph
Phase 1 (Foundation)
├─→ Phase 2 (Code Quality) ─┬─→ Phase 3 (Architecture)
│ │ └─→ Phase 4 (Features)
│ └──────────────→ Phase 4 (Features)
└─→ Phase 5 (Observability) ───────────────→
Phase 1 must come first. Phase 2 makes Phase 3/4 safer. Phase 3 unlocks some Phase 4 items. Phase 5 is largely independent.
Recommended Execution Order
Sprint 1: Items 1, 2, 4, 6 (CI + docs + pre-commit) Sprint 2: Items 5, 7, 8 (type checking + logging + errors) Sprint 3: Item 10 (explorer decomposition) Sprint 4: Items 12, 15, 17 (pipeline automation + health checks) Sprint 5+: Items 11, 13, 14, 16, 18 (API + features + observability)
Plan Document Inventory
| Plan ID | File | Status |
|---|---|---|
| P1-001 | docs/plans/2026-04-24-001-fix-ci-test-workflow-plan.md | Planned |
| P1-002 | docs/plans/2026-04-24-002-fix-docker-compose-scheduler-plan.md | Planned |
| P1-003 | docs/plans/2026-04-24-003-consolidate-config-sources-plan.md | Planned |
| P1-004 | docs/plans/2026-04-24-004-rewrite-readme-plan.md | Planned |
| P1-005 | docs/plans/2026-04-24-005-add-pyright-ci-plan.md | Planned |
| P1-006 | docs/plans/2026-04-24-006-activate-pre-commit-hooks-plan.md | Planned |
| P2-001 | docs/plans/2026-04-24-007-replace-print-with-logging-plan.md | Planned |
| P2-002 | docs/plans/2026-04-24-008-fix-broad-exception-handling-plan.md | Planned |
| P3-001 | docs/plans/2026-04-04-003-refactor-complete-explorer-decomposition-plan.md | In progress |
| P4-005 | docs/plans/2026-04-24-009-pipeline-health-checks-plan.md | Planned |
| P5-002 | docs/plans/2026-04-24-010-pipeline-health-checks-plan.md | Planned |
Notes
- All implementation plans use TDD (test-first) for code-bearing units.
- Config-only units (README, docker-compose fix) skip TDD but include verification checklists.
- Existing plans (e.g., explorer decomposition) are referenced rather than duplicated.