From c2b69db2e55a2f617a480455d507bf5bbe92b06f Mon Sep 17 00:00:00 2001 From: Christian Krakau-Louis Date: Sat, 23 May 2026 02:30:58 +0200 Subject: [PATCH] Docs: extend roadmap with themed releases Update roadmap doc with themed feature landscape and versioned release plan aligned to GitHub milestones and roadmap epics. --- docs/development/roadmap.md | 122 ++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md index 354c4d8..c1843f1 100644 --- a/docs/development/roadmap.md +++ b/docs/development/roadmap.md @@ -2,6 +2,14 @@ This roadmap is based on a senior-developer inspection of the current FastAPI, Jinja, and SQLAlchemy codebase. +## Roadmap Execution (GitHub) + +This document describes outcomes and acceptance criteria. Execution is tracked in GitHub: + +- Umbrella roadmap issue: https://github.com/christianlouis/LeagueLedger/issues/144 +- GitHub milestones track versions (`v0.3.0` → `v1.0.0`). +- Each version has a release epic (label: `roadmap`) with sub-issues for the scoped work. + ## Current Findings - LeagueLedger currently treats teams, QR sets, events, redemptions, and leaderboards as global records. That blocks multiple pubs or organizers from sharing one installation cleanly. @@ -10,11 +18,64 @@ This roadmap is based on a senior-developer inspection of the current FastAPI, J - Several workflows still include compatibility branches for removed model names, which makes behavior harder to reason about. - QR redemption did not consistently record the redeeming user on the QR code record, weakening auditability. +## Feature Landscape (Themes) + +These themes reflect what a modern, operator-friendly loyalty + league product typically needs beyond the foundational multi-league work. + +### Foundation & Governance (P0) + +- Multi-league operations: league creation, archival, and delegation. +- Role-based access control (RBAC) and strict data isolation by league. +- Migration safety and release hygiene (CI, smoke tests, release checklist). + +### QR Trust, Fraud Prevention & Auditability (P0/P1) + +- Rotating/expiring QR codes, replay protection, and rate limits. +- Clear redemption audit trails and admin review tooling. + +### Engagement, Rewards & Retention (P1) + +- Rewards catalog and redemption flow (points → rewards). +- Seasons (timeboxed leaderboards) and historical archives. +- Notifications, announcements, and team communication. +- Optional Apple/Google Wallet passes for “always-on” engagement. + +### Integrations & Automation (P1/P2) + +- Webhooks + exports as the baseline “integration surface”. +- Slack/Discord notifications and calendar feeds (ICS). +- PWA + offline QR scanning to make the mobile experience resilient. + +### Analytics, Insights & Reporting (P2) + +- Admin reports, retention/cohort analytics, and operational dashboards. + +### Platform Extensibility + MCP/AI (P2/P3) + +- Public API (read-first) with rate limits and scoped auth. +- MCP server for safe “tools” (create event, generate QR sets, query stats). +- Guardrailed AI operator UX built on top of MCP tools. + +## Release Plan (GitHub Milestones) + +| Version | Focus | Tracking Epic | Target (UTC) | +| --- | --- | --- | --- | +| v0.2.0 | Multi-league foundation (shipped) | Release notes: https://github.com/christianlouis/LeagueLedger/releases/tag/v0.2.0 | 2026-05-22 | +| v0.3.0 | League administration | https://github.com/christianlouis/LeagueLedger/issues/145 | 2026-06-30 | +| v0.4.0 | Data isolation + RBAC | https://github.com/christianlouis/LeagueLedger/issues/151 | 2026-07-31 | +| v0.5.0 | Migrations + release hardening | https://github.com/christianlouis/LeagueLedger/issues/156 | 2026-08-31 | +| v0.6.0 | QR trust + security | https://github.com/christianlouis/LeagueLedger/issues/162 | 2026-09-30 | +| v0.7.0 | Engagement layer | https://github.com/christianlouis/LeagueLedger/issues/165 | 2026-10-31 | +| v0.8.0 | Integrations + automation | https://github.com/christianlouis/LeagueLedger/issues/168 | 2026-11-30 | +| v0.9.0 | Analytics + reporting | https://github.com/christianlouis/LeagueLedger/issues/173 | 2026-12-31 | +| v1.0.0 | Platform + MCP + AI operator | https://github.com/christianlouis/LeagueLedger/issues/176 | 2027-03-31 | + ## Milestones ### 1. Multi-League Foundation Status: implemented in this branch. +Release: `v0.2.0` (shipped). Acceptance criteria: - Add a `League` model with a default league for existing data. @@ -25,6 +86,8 @@ Acceptance criteria: ### 2. League Administration +Release: `v0.3.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/145). + Acceptance criteria: - Add a dedicated admin workflow for creating, editing, activating, and archiving leagues. - Allow league managers to administer only their own league. @@ -33,6 +96,8 @@ Acceptance criteria: ### 3. Data Isolation and Permissions +Release: `v0.4.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/151). + Acceptance criteria: - Introduce league-level roles for owners, quiz masters, and staff. - Enforce league boundaries in every query that reads or mutates teams, events, QR sets, QR codes, achievements, and leaderboards. @@ -40,6 +105,8 @@ Acceptance criteria: ### 4. Migration Cleanup +Release: `v0.5.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/156). + Acceptance criteria: - Consolidate schema migrations into one approach. - Add repeatable migration tests against a fresh database and a simulated legacy database. @@ -47,7 +114,62 @@ Acceptance criteria: ### 5. Release Hardening +Release: `v0.5.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/156). + Acceptance criteria: - Add CI checks for syntax, tests, and a lightweight app smoke test. - Document local development with 1Password-injected environment secrets. - Add a release checklist with migration, rollback, and verification steps. + +### 6. QR Trust + Security + +Release: `v0.6.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/162). + +Acceptance criteria: +- Support rotating/dynamic QR codes where appropriate (see https://github.com/christianlouis/LeagueLedger/issues/96). +- Support expiration and scheduling for QR codes (see https://github.com/christianlouis/LeagueLedger/issues/102). +- Provide QR usage statistics (see https://github.com/christianlouis/LeagueLedger/issues/98). +- Add a redemption audit trail + admin review workflow. +- Add anti-fraud controls (rate limits, replay protection, optional constraints) with tests. + +### 7. Engagement Layer + +Release: `v0.7.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/165). + +Acceptance criteria: +- Rewards catalog primitives and a redemption flow (see https://github.com/christianlouis/LeagueLedger/issues/166). +- Seasons and controlled leaderboard resets with archives (see https://github.com/christianlouis/LeagueLedger/issues/167). +- Notifications and team comms are usable and league-scoped (see https://github.com/christianlouis/LeagueLedger/issues/75 and https://github.com/christianlouis/LeagueLedger/issues/92). +- Wallet passes are available as an opt-in enhancement (see https://github.com/christianlouis/LeagueLedger/issues/180). + +### 8. Integrations + Automation + +Release: `v0.8.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/168). + +Acceptance criteria: +- Webhook framework exists for core events (see https://github.com/christianlouis/LeagueLedger/issues/169). +- Slack/Discord notifications are available (see https://github.com/christianlouis/LeagueLedger/issues/170). +- Calendar feeds (ICS) are available (see https://github.com/christianlouis/LeagueLedger/issues/171). +- Exports v1 exist for core objects (see https://github.com/christianlouis/LeagueLedger/issues/172). +- PWA can be installed and supports offline scan queue + sync (see https://github.com/christianlouis/LeagueLedger/issues/181). + +### 9. Analytics + Reporting + +Release: `v0.9.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/173). + +Acceptance criteria: +- Admin reports exist for key operational views (see https://github.com/christianlouis/LeagueLedger/issues/23). +- Basic performance/health metrics are tracked (see https://github.com/christianlouis/LeagueLedger/issues/85). +- Cohort/retention analytics and report templates exist (see https://github.com/christianlouis/LeagueLedger/issues/174 and https://github.com/christianlouis/LeagueLedger/issues/175). + +### 10. Platform + MCP + AI Operator + +Release: `v1.0.0` (tracking: https://github.com/christianlouis/LeagueLedger/issues/176). + +Acceptance criteria: +- Public API v1 exists with scoped auth + rate limits (see https://github.com/christianlouis/LeagueLedger/issues/177). +- MCP server exists for safe operator tooling (see https://github.com/christianlouis/LeagueLedger/issues/178). +- AI operator UX uses MCP tools with explicit guardrails (see https://github.com/christianlouis/LeagueLedger/issues/179). +- Security baseline is in place (see https://github.com/christianlouis/LeagueLedger/issues/64, https://github.com/christianlouis/LeagueLedger/issues/66, https://github.com/christianlouis/LeagueLedger/issues/68). +- Backup/restore is available (see https://github.com/christianlouis/LeagueLedger/issues/82). +- API documentation is up to date (see https://github.com/christianlouis/LeagueLedger/issues/104).