nitrix/fete
1
0
Fork 0
Code Issues 1 Pull Requests 10 Actions Packages Projects Releases 13 Wiki Activity

Replace implementation phases with sequential implementation order

Browse Source 
Rework the implementation roadmap from parallelizable phases to a strict
sequential order optimized for earliest usable increments. Key changes:
- All 20 user stories in a single sequential queue (no parallelization)
- Progress tracker at the top for status tracking
- US-17 (dark mode) moved from Phase 5 to Increment 4 (before US-15)
- US-14 (PWA) moved to last position
- Deferred AC activation schedule added

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
nitrix
2026-03-04 22:02:13 +01:00
parent e9110ea143
commit 747ed18945
1 changed files with 88 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
spec/implementation-phases.md
View File

@@ -1,160 +1,123 @@
# Implementation Phases # Implementation Order
A recommended implementation order based on the dependency graph across all stories and setup tasks. Sequential implementation order for all user stories. No parallelization — one story at a time.
## Phase 0: Project Infrastructure ## Progress Tracker
All setup tasks must complete before any user story work begins. T-3 can run in parallel with Phase 1. - [ ] US-1 Create event
- [ ] US-2 View event page
- [ ] US-3 RSVP
- [ ] US-5 Edit event
- [ ] US-4 Manage guest list
- [ ] US-18 Cancel event
- [ ] US-19 Delete event
- [ ] US-12 Auto-cleanup after expiry
- [ ] US-13 Limit active events
- [ ] US-6 Bookmark event
- [ ] US-7 Local event overview
- [ ] US-17 Dark/light mode
- [ ] US-8 Calendar integration
- [ ] US-11 QR code
- [ ] US-9 Change highlights
- [ ] US-10a Update messages
- [ ] US-10b New-update indicator
- [ ] US-15 Color themes
- [ ] US-16 Unsplash header images
- [ ] US-14 PWA install
| Order | Task | Depends on | Notes | ## Prerequisites
|-------|------|------------|-------|
| 1 | T-1: Initialize monorepo structure | — | Scaffolds empty backend + frontend projects |
| 2 | T-5: API-first tooling setup | T-1 | OpenAPI spec, codegen plugins, generated types |
| 3 | T-2: Docker deployment setup | T-1, T-5 | Multi-stage Dockerfile — builds backend + frontend into one container |
| 4 | T-4: Development infrastructure | T-2, T-5 | Migrations, DB wiring, router, test infra, docker-compose docs — gates all user stories |
| 4* | T-3: CI/CD pipeline | T-1, T-2 | Parallelizable with T-4. Uses Gitea Actions (per Q-5 resolution) |
## Phase 1: Core Event Flow (Vertical Slice) All setup tasks (T-1 through T-5) are complete.
The end-to-end journey from creating an event to viewing it to RSVPing. US-1 is the "Durchstich" that bootstraps the full stack (DB table, backend endpoint, frontend form, localStorage, routing). It will take significantly longer than subsequent stories. ## Order Rationale
| Order | Story | Depends on | Parallelizable | ### Increment 1: Minimal Viable Event — US-1, US-2, US-3
|-------|-------|------------|----------------|
| 1 | US-1: Create an event | T-4 | — |
| 2 | US-2: View event landing page | US-1 | — |
| 3 | US-3: RSVP to an event | US-2 | — |
These three stories are strictly sequential. No parallelization within this phase. The vertical slice. After these three stories, the app is usable: an organizer creates an event, shares the link, guests view it and RSVP.
## Phase 2: Organizer Management & Event Lifecycle | # | Story | Depends on | Delivers |
|---|-------|------------|----------|
| 1 | US-1: Create event | T-4 | Event creation with tokens, localStorage, honeypot |
| 2 | US-2: View event page | US-1 | Public event page with attendee list, expired state |
| 3 | US-3: RSVP | US-2 | Attend/decline flow, localStorage dedup, honeypot |
All stories in this phase depend on US-1 (and T-4 transitively). They can be implemented in parallel since they are independent of each other. Some are more useful after Phase 1 completes (e.g. US-4 needs RSVPs to manage), but they are structurally implementable after US-1. ### Increment 2: Organizer Toolset — US-5, US-4
| Story | Depends on | Notes | The organizer needs to correct mistakes and moderate spam before the app goes to real users.
|-------|------------|-------|
| US-4: Manage guest list | US-1 | Most useful after US-3 provides RSVPs to manage |
| US-5: Edit event details | US-1 | Required by US-9 in Phase 3 |
| US-18: Cancel an event | US-1 | Enables deferred ACs in US-2, US-3, US-8 |
| US-19: Delete an event | US-1 | Enables deferred AC in US-2 |
| US-12: Automatic data deletion after expiry | US-1 | Enables deferred AC in US-2; server-side scheduled job |
| US-13: Limit active events | US-1 | Server-side config; independent of all other stories |
**Recommended order within phase:** US-5, US-4, US-18, US-19, US-12, US-13 — starting with US-5 because US-9 (Phase 3) depends on it, and US-4 because it completes the organizer toolset around RSVPs. | # | Story | Depends on | Delivers |
|---|-------|------------|----------|
| 4 | US-5: Edit event | US-1 | Edit all fields, expiry-must-be-future constraint |
| 5 | US-4: Manage guest list | US-1 | View RSVPs, delete spam entries |
## Phase 3: Enhanced Event Page Features US-5 before US-4: US-9 (change highlights) depends on US-5, so getting it done early unblocks Phase 3 work.
Features that enrich the event page for guests. Most depend on US-2 (event page exists). US-9 additionally requires US-5 (editing). US-10b requires US-10a. ### Increment 3: Event Lifecycle — US-18, US-19, US-12, US-13
| Story | Depends on | Parallelizable with | Complete lifecycle management. After this increment, the privacy guarantee is enforced and abuse prevention is in place.
|-------|------------|---------------------|
| US-6: Bookmark an event | US-2 | US-8, US-10a, US-11 |
| US-8: Add event to calendar (.ics / webcal) | US-2 | US-6, US-10a, US-11 |
| US-9: Highlight changed event details | US-2, US-5 | US-6, US-8, US-10a, US-11 (if US-5 is done) |
| US-10a: Post update messages | US-1, US-2 | US-6, US-8, US-11 |
| US-10b: New-update indicator | US-10a | Must follow US-10a |
| US-11: Generate QR code | US-2 | US-6, US-8, US-10a |
**Recommended order within phase:** US-6, US-8, US-11 (simple, independent), then US-10a → US-10b (sequential pair), then US-9 (requires US-5 from Phase 2). | # | Story | Depends on | Delivers | Activates deferred ACs |
|---|-------|------------|----------|----------------------|
| 6 | US-18: Cancel event | US-1 | One-way cancellation with optional message, expiry adjustment | US-2 AC5, US-3 AC11 |
| 7 | US-19: Delete event | US-1 | Immediate permanent deletion, localStorage cleanup | US-2 AC6 (partial) |
| 8 | US-12: Auto-cleanup | US-1 | Scheduled deletion after expiry, silent logging | US-2 AC6 (complete) |
| 9 | US-13: Event limit | US-1 | `MAX_ACTIVE_EVENTS` env var, server-side enforcement | — |
## Phase 4: Visual Customization When implementing US-18, US-19, and US-12: immediately activate their deferred ACs in US-2 and US-3 (cancelled state display, RSVP blocking, event-not-found handling). These stories exist at this point — no reason to defer further.
Event-level theming and image selection. Both depend on US-1 and US-2. US-15 and US-16 are independent of each other but share the event creation/editing form surface area, so coordinating them is beneficial. ### Increment 4: App Shell — US-6, US-7, US-17
| Story | Depends on | Notes | The app gets a home screen. Users can find their events without the original link.
|-------|------------|-------|
| US-15: Choose event color theme | US-1, US-2 | Predefined theme picker in creation/edit forms |
| US-16: Select header image from Unsplash | US-1, US-2 | Optional feature gated by API key config |
**Recommended order:** US-15 first (simpler, no external dependency), then US-16. Consider the interaction between event themes and dark/light mode (US-17) — implement US-17 before or alongside US-15 if possible. | # | Story | Depends on | Delivers |
|---|-------|------------|----------|
| 10 | US-6: Bookmark event | US-2 | Client-only bookmark, no server contact |
| 11 | US-7: Local event overview | — | Root page `/` with all tracked events from localStorage |
| 12 | US-17: Dark/light mode | — | System preference detection, manual toggle, localStorage persistence |
## Phase 5: App Shell & PWA US-6 before US-7: bookmarking populates localStorage entries that the overview displays. Without US-6, the overview only shows created and RSVPed events.
Client-side infrastructure and app-level UX features. These have no or minimal structural dependencies but are only meaningfully testable after earlier phases provide content and data. US-17 here (not in a late phase): event color themes (US-15) must account for dark/light mode. Having it in place before US-15 avoids rework.
| Story | Depends on | Practically useful after | ### Increment 5: Rich Event Page — US-8, US-11, US-9, US-10a, US-10b
|-------|------------|------------------------|
| US-7: Local event overview | None (structural) | US-1, US-3, US-6 populate localStorage |
| US-14: Install as PWA | T-4 (structural) | US-2, US-7 provide pages to cache |
| US-17: Dark/light mode | None (structural) | T-4 provides frontend scaffold |
**Recommended order:** US-17 (can be started early once the frontend scaffold exists — consider implementing alongside Phase 2 or 3), then US-7 (after localStorage-populating stories are available), then US-14 (after the app has real pages and assets). Features that enrich the event page for guests and organizers.
**Note on US-17 timing:** US-17 is listed in Phase 5 for logical grouping, but it can be implemented as early as Phase 2 since it only needs the frontend scaffold. Implementing it earlier is recommended because US-15 (Phase 4) must consider the interaction between event color themes and dark/light mode. Having dark/light mode in place before US-15 simplifies that work. | # | Story | Depends on | Delivers |
|---|-------|------------|----------|
| 13 | US-8: Calendar .ics + webcal | US-2 | RFC 5545 download, webcal subscription, STATUS:CANCELLED support |
| 14 | US-11: QR code | US-2 | Server-generated QR, SVG/PNG download |
| 15 | US-9: Change highlights | US-2, US-5 | Field-level change indicators, localStorage-based read tracking |
| 16 | US-10a: Update messages | US-1, US-2 | Organizer posts, reverse-chronological display, delete capability |
| 17 | US-10b: New-update indicator | US-10a | localStorage-based unread badge |
## Deferred Acceptance Criteria US-8 benefits from US-18 being complete: `STATUS:CANCELLED` in .ics can be implemented directly instead of deferred.
Several stories contain ACs that reference features from later phases. These are marked `[deferred until US-X is implemented]` in the story text: US-9 benefits from US-5 being complete (increment 2): no dependency waiting.
| Story | AC | Deferred until | Phase unlocked | ### Increment 6: Visual Polish & PWA — US-15, US-16, US-14
|-------|-----|---------------|----------------|
| US-2 AC 5 | Cancelled state display | US-18 | Phase 2 |
| US-2 AC 6 | Event not found (expiry deletion) | US-12 | Phase 2 |
| US-2 AC 6 | Event not found (organizer deletion) | US-19 | Phase 2 |
| US-3 AC 11 | RSVP blocked on cancelled event | US-18 | Phase 2 |
| US-8 AC 9 | STATUS:CANCELLED in .ics | US-18 | Phase 2 |
| US-12 AC 2 | Delete stored header images | US-16 | Phase 4 |
Once the referenced story is implemented, revisit the deferring story to activate the deferred AC. Final layer: visual customization and native app feel.
## Dependency Graph | # | Story | Depends on | Delivers |
|---|-------|------------|----------|
| 18 | US-15: Color themes | US-1, US-2 | Predefined theme picker, event-scoped styling |
| 19 | US-16: Unsplash images | US-1, US-2 | Server-proxied search, local storage, attribution |
| 20 | US-14: PWA | T-4 | Manifest, service worker, installability |
Render this diagram at [mermaid.live](https://mermaid.live) or view it directly in Gitea (which renders `mermaid` blocks natively). US-15 before US-16: themes are self-contained, Unsplash adds external API complexity.
```mermaid US-14 last: PWA caching is most effective when the app has all its pages and assets. Service worker strategy can cover everything in one pass.
graph TD
classDef infra fill:#4a90d9,stroke:#2c5f8a,color:#fff
classDef core fill:#e8a838,stroke:#b07c1e,color:#fff
classDef organizer fill:#50b86c,stroke:#2d8043,color:#fff
classDef enhanced fill:#9b59b6,stroke:#6c3483,color:#fff
classDef visual fill:#e74c3c,stroke:#a93226,color:#fff
classDef shell fill:#7f8c8d,stroke:#566566,color:#fff
%% Phase 0: Infrastructure Note: US-12 AC2 (delete stored header images on expiry) remains deferred until US-16 is implemented. When implementing US-16, activate this AC in US-12.
T1(["T-1: Monorepo"]):::infra --> T5(["T-5: API-First Tooling"]):::infra
T1 --> T2(["T-2: Docker"]):::infra
T5 --> T2
T2 --> T4(["T-4: Dev Infra + DB"]):::infra
T5 --> T4
T2 --> T3(["T-3: CI/CD"]):::infra
%% Phase 1: Core Event Flow ## Deferred AC Activation Schedule
T4 --> US1["US-1: Create Event"]:::core
US1 --> US2["US-2: View Event"]:::core
US2 --> US3["US-3: RSVP"]:::core
%% Phase 2: Organizer & Lifecycle (branch from US-1) | When implementing | Activate deferred AC in | AC description |
US1 --> US4["US-4: Guest List"]:::organizer |-------------------|------------------------|----------------|
US1 --> US5["US-5: Edit Event"]:::organizer | US-18 (#6) | US-2 AC5 | Cancelled state display |
US1 --> US18["US-18: Cancel"]:::organizer | US-18 (#6) | US-3 AC11 | RSVP blocked on cancelled event |
US1 --> US19["US-19: Delete"]:::organizer | US-18 (#6) | US-8 AC9 | STATUS:CANCELLED in .ics (if US-8 not yet done — in this order, US-8 comes later, so implement directly) |
US1 --> US12["US-12: Auto-Cleanup"]:::organizer | US-19 (#7) | US-2 AC6 | Event not found (organizer deletion) |
US1 --> US13["US-13: Event Limit"]:::organizer | US-12 (#8) | US-2 AC6 | Event not found (expiry deletion) |
| US-16 (#19) | US-12 AC2 | Delete stored header images on expiry |
%% Phase 3: Enhanced Features (branch from US-2)
US2 --> US6["US-6: Bookmark"]:::enhanced
US2 --> US8["US-8: Calendar .ics"]:::enhanced
US2 --> US10a["US-10a: Messages"]:::enhanced
US2 --> US11["US-11: QR Code"]:::enhanced
US5 --> US9["US-9: Change Highlights"]:::enhanced
US2 --> US9
US10a --> US10b["US-10b: New-Update Badge"]:::enhanced
%% Phase 4: Visual Customization (branch from US-2)
US2 --> US15["US-15: Color Themes"]:::visual
US2 --> US16["US-16: Unsplash Images"]:::visual
%% Phase 5: App Shell & PWA
T4 --> US14["US-14: PWA"]:::shell
US7["US-7: Local Overview"]:::shell
US17["US-17: Dark/Light Mode"]:::shell
```
**Legend:**
- 🔵 Infrastructure (T-1 – T-5)
- 🟠 Core Event Flow (US-1 – US-3)
- 🟢 Organizer & Lifecycle (US-4, US-5, US-12, US-13, US-18, US-19)
- 🟣 Enhanced Features (US-6, US-8 – US-11)
- 🔴 Visual Customization (US-15, US-16)
- ⚪ App Shell & PWA (US-7, US-14, US-17)
US-7 and US-17 appear as isolated nodes — they have no structural dependencies but are only practically useful after earlier phases provide content (see Phase 5 notes above).