docs(roadmap): Glint/Spark/Kindling/Flame/Ember/Wildfire/Phoenix — Sprint 0 = wait, Sprint 1 = MVP

2026-06-24 14:46:37 +02:00
parent f5ff3383a2
commit 461b8ea1cf
1 changed files with 199 additions and 0 deletions
@@ -0,0 +1,199 @@
+# Roadmap
+
+Sparkboard's sprint cadence is loose. There is no fixed-length sprint, no story-point budget, no demo day. A "sprint" here is a coherent shippable chunk of work — usually one to three weekends.
+
+The theme is **campfire**: every sprint name continues the metaphor of igniting and tending a fire. The metaphor is for the developer (Patrick); the users will never see these names.
+
+---
+
+## Naming theme
+
+| # | Codename | Metaphor | What ships |
+|---|----------|----------|------------|
+| 0 | **Glint** | Striker poised on the flint — no fire yet | _Nothing._ Sprint 0 is waiting for [plate-auth v0.1.0](https://git.plate-software.de/pplate/plate-auth/wiki/Roadmap) |
+| 1 | **Spark** | First flash — does anything burn? | Walking skeleton: plate-auth wired up, one idea CRUD, deployed |
+| 2 | **Kindling** | Building up the structure that lets the fire spread | Reactions, status transitions, archive, profile |
+| 3 | **Flame** | A self-sustaining fire | Comments, simple search, polish |
+| 4 | **Ember** | Warmth that persists overnight | Notifications, digest emails, offline cache |
+| 5 | **Wildfire** | Spreading beyond the original campfire | Capacitor APK / native mobile, share-target |
+| 6 | **Phoenix** _(optional)_ | Rising from the original implementation | Whatever the previous five sprints made us regret |
+
+The naming is decorative. The work is what it is.
+
+---
+
+## Sprint 0 — **Glint** (waiting for plate-auth)
+
+**Goal:** be unblocked, not be coded.
+
+| Activity | Status |
+|----------|--------|
+| plate-auth v0.1.0 published to Gitea Maven registry | ⏳ Depends on plate-auth Sprint 0 |
+| `@platesoft/auth@0.1.0` published to Gitea npm registry | ⏳ Same |
+| plate-auth wiki marked "v0.1.0 shipped" on its Home page | ⏳ Same |
+| Sparkboard repo created (empty) at `git.plate-software.de/pplate/sparkboard` | ✅ Pre-Sprint 1 setup |
+| Gitea OAuth app for Google created (production credentials) | ⏳ Pre-Sprint 1 |
+| TrueNAS dataset for Postgres volume reserved | ⏳ Pre-Sprint 1 |
+| frps port 30011 reserved | ⏳ Pre-Sprint 1 |
+| DNS: `sparkboard.plate-software.de` CNAME created at IONOS | ⏳ Pre-Sprint 1 |
+
+**Definition of done for Sprint 0:** the moment a `pom.xml` snippet `<dependency><groupId>de.platesoft</groupId><artifactId>plate-auth-starter</artifactId><version>0.1.0</version></dependency>` resolves on a developer machine. That's the gate.
+
+There is no Sprint 0 plan document for Sparkboard. Sprint 0 is **plate-auth's** Sprint 0, observed.
+
+---
+
+## Sprint 1 — **Spark**
+
+**Goal:** the walking skeleton. Four humans can sign in, post an idea, see each other's ideas, and the app is reachable from the public internet.
+
+| Workstream | What | Doc |
+|------------|------|-----|
+| W0 | New Spring Boot 4.1 + Java 25 backend + Next.js 15 frontend skeleton; CI builds | [Plan §W0](Sprint-1-Plan.md#w0-skeleton) |
+| W1 | Pull `plate-auth-starter` + `@platesoft/auth`, configure single-org + allowlist, Google OAuth | [Plan §W1](Sprint-1-Plan.md#w1-plate-auth-wire-up) |
+| W2 | `Idea` entity, `spark_org` table, `SparkboardOnboardingHook` | [Plan §W2](Sprint-1-Plan.md#w2-domain) |
+| W3 | `GET/POST /api/ideas` + DTO + validation | [Plan §W3](Sprint-1-Plan.md#w3-api) |
+| W4 | `/login`, `/ideas` (list + create form), PWA manifest + SW stub | [Plan §W4](Sprint-1-Plan.md#w4-frontend) |
+| W5 | Flyway seed: Family Spark org + admin allowlist; dev seed data | [Plan §W5](Sprint-1-Plan.md#w5-seed-data) |
+| W6 | Docker, docker-compose.prod, IONOS Apache vhost, frps tunnel, Gitea Actions CI/CD | [Plan §W6](Sprint-1-Plan.md#w6-deploy--cicd) |
+
+**Acceptance: A1–A6.** See [Sprint 1 — Assessment](Sprint-1-Assessment.md#7-acceptance-criteria-a1a6).
+
+**Out of scope for Sprint 1** (deferred to Sprint 2+):
+
+- Reactions (any 💡⚡🔥❓👀 buttons)
+- Status transitions (you can _have_ a status field but you cannot _change_ it from the UI)
+- Idea archive / soft-delete UI
+- Idea edit
+- Idea detail page (just the list view in v1)
+- Profile / account-settings page
+- Admin panel / member management
+- Tags, comments, search
+- Notifications
+
+---
+
+## Sprint 2 — **Kindling**
+
+**Goal:** the board becomes _useful_. People can actually express opinions.
+
+| Theme | What |
+|-------|------|
+| Reactions | A fixed 5-emoji palette (💡 ⚡ 🔥 ❓ 👀). One reaction per user per idea per emoji. New table `idea_reactions(user_id, idea_id, emoji)`. |
+| Status transitions | Admin and author can move an idea between `RAW → EXPLORING → BUILDING → SHIPPED → DEAD`. UI: dropdown next to the idea card. |
+| Archive | Soft-delete via `archived_at`. Archived ideas hidden from list by default; "Show archive" toggle reveals them. |
+| Idea edit | Author can edit title/description while not archived. Admin can edit any. |
+| Idea detail page | `/ideas/[id]` — full description, reaction breakdown, history. |
+| Profile page | `/profile` — show display name and email (read-only). |
+| Theme + branding | Settle on the Sparkboard colour and final icon set. Light + dark mode parity. |
+
+**Probable acceptance:** the four real users have each reacted to at least one idea and at least one idea has moved past `RAW`.
+
+---
+
+## Sprint 3 — **Flame**
+
+**Goal:** ideas can grow into conversations.
+
+| Theme | What |
+|-------|------|
+| Comments | Flat (non-threaded) comments per idea. Markdown rendering via `react-markdown` or similar. |
+| Mentions (lightweight) | `@patrick` resolves to the four-person allowlist; renders as a chip. No notification yet. |
+| Simple search | Server-side `ILIKE '%q%'` over title + description (and comments). No Postgres FTS yet — that's Sprint 4. |
+| Pagination / infinite scroll | List view starts paginating once we have >50 ideas (unlikely for a family of four, but lined up for completeness). |
+| Polish | Empty states, error toasts, loading skeletons. The app stops feeling like a prototype. |
+
+**Probable acceptance:** the team has had at least one cross-thread conversation under an idea.
+
+---
+
+## Sprint 4 — **Ember**
+
+**Goal:** the app reaches into people's day even when they're not opening it.
+
+| Theme | What |
+|-------|------|
+| Notifications — email | New idea, new comment on your idea, reaction on your idea. Opt-in per category. Uses `plate-auth`'s `InvitationMailer` SPI (Sparkboard would now implement `EmailService` and reuse SMTP plumbing). |
+| Notifications — web push | iOS 16.4+ supports web-push for installed PWAs. Android Chrome supports it natively. Server uses VAPID keys. |
+| Digest | Daily / weekly digest email summarising activity. Per-user opt-in. |
+| Offline cache | Service worker actually caches the idea list and recent details (read-only) so the PWA loads instantly. |
+| Postgres FTS | Replace the `ILIKE` search with a real `tsvector` column (Sparkboard's first migration that imports learnings from InspectFlow Sprint 7). |
+
+**Probable acceptance:** Patrick wakes up to a digest email and is happy about it (not annoyed).
+
+---
+
+## Sprint 5 — **Wildfire**
+
+**Goal:** the PWA stops being "almost a real app". It _is_ one.
+
+| Theme | What |
+|-------|------|
+| Capacitor APK | Wrap the existing Next.js build in Capacitor, ship as an Android APK on the Gitea release page. No iOS App Store — too much effort for four users. |
+| Share-target | On Android, register Sparkboard as a share-target so other apps can "Share to Sparkboard" and pre-fill the idea form. |
+| Image attachments | One image per idea. Stored on TrueNAS volume; backend serves via `/api/ideas/{id}/image`. |
+| Drag-to-reorder | Optional pinning / drag-reorder for ideas. |
+| Performance pass | Lighthouse > 90 across all four categories. |
+
+**Probable acceptance:** at least one user has the APK installed and uses it as their primary surface.
+
+---
+
+## Sprint 6 — **Phoenix** _(optional)_
+
+**Goal:** burn down the things we now know we got wrong.
+
+This sprint may not happen. Its job is to be the place where post-v1 regrets get fixed. Likely contents (we cannot predict from here):
+
+- Migrate any pieces of "ad hoc local-only logic" back behind plate-auth APIs
+- Lock down the membership API surface that proves to be too loose
+- Either implement `OrgValidator` for real, or document that we're not going to
+- Adopt whatever plate-auth v0.2 ships that Sparkboard would benefit from
+- Possibly: extract a re-usable `@plate-software/idea-board` library if a second app turns out to want this surface (low probability)
+
+---
+
+## Cross-cutting themes
+
+Some things are not tied to a sprint:
+
+| Theme | Where |
+|-------|------|
+| **plate-auth version tracking** | Sparkboard upgrades its `plate-auth-starter` and `@platesoft/auth` versions in lockstep when plate-auth ships a new minor. See [plate-auth Roadmap — Versioning policy](https://git.plate-software.de/pplate/plate-auth/wiki/Roadmap#versioning-policy). |
+| **Spring Boot patch updates** | Spring Boot 4.1.x patches get applied as released. Major (4.2, 5.0) is its own assessment. |
+| **Documentation discipline** | Every sprint produces Assessment + Plan + Testplan + Review in this wiki. No exceptions. |
+| **Testing discipline** | Backend unit tests with JUnit 5; backend integration tests with Testcontainers (Postgres); frontend E2E with Playwright. |
+| **Security review** | Every sprint that touches auth code (will be rare — that's plate-auth's job) gets a security-reviewer pass. |
+
+---
+
+## Velocity / cadence
+
+This is a side project.
+
+- **Sprint 1:** ~2–3 weekends after plate-auth v0.1.0 ships. Walking skeleton fits.
+- **Sprint 2:** likely a month wall-clock (reactions + status + archive + edit + detail page + profile is a lot).
+- **Sprint 3–5:** opportunistic. Patrick will start them when there is a concrete itch from real usage.
+- **Sprint 6:** maybe never.
+
+Sprint boundaries are decided by what gets shipped, not by what was planned.
+
+---
+
+## Open questions
+
+See [Open Questions](Open-Questions.md) for the ten Sparkboard-specific design decisions still on Patrick's desk. The biggest ones for the roadmap shape:
+
+- [Q01 — Single-org name and ID strategy](Open-Questions.md#q01-single-org-name-and-id-strategy) (affects Sprint 1)
+- [Q04 — Idea status workflow](Open-Questions.md#q04-idea-status-workflow) (affects Sprint 2)
+- [Q05 — Reaction model](Open-Questions.md#q05-reaction-model) (affects Sprint 2)
+- [Q08 — Mobile strategy: PWA-only vs native APK](Open-Questions.md#q08-mobile-strategy-pwa-only-vs-native-apk) (affects Sprint 5 — possibly cancels it)
+
+---
+
+## Cross-references
+
+- [plate-auth Roadmap](https://git.plate-software.de/pplate/plate-auth/wiki/Roadmap) — Sparkboard's roadmap dovetails with plate-auth's release horizon
+- [Vision](Vision.md) — why these sprints in this order
+- [Architecture](Architecture.md) — what the v1 shape looks like
+- [Sprint 1 — Plan](Sprint-1-Plan.md) — the only sprint with a real plan document yet