diff --git a/spec/implementation-phases.md b/spec/implementation-phases.md index f912de9..51e5e91 100644 --- a/spec/implementation-phases.md +++ b/spec/implementation-phases.md @@ -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 | -|-------|------|------------|-------| -| 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) | +## Prerequisites -## 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 | -|-------|-------|------------|----------------| -| 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 | — | +### Increment 1: Minimal Viable Event — US-1, US-2, US-3 -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 | -|-------|------------|-------| -| 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 | +The organizer needs to correct mistakes and moderate spam before the app goes to real users. -**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 | -|-------|------------|---------------------| -| 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 | +Complete lifecycle management. After this increment, the privacy guarantee is enforced and abuse prevention is in place. -**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 | -|-------|------------|-------| -| 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 | +The app gets a home screen. Users can find their events without the original link. -**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 | -|-------|------------|------------------------| -| 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 | +### Increment 5: Rich Event Page — US-8, US-11, US-9, US-10a, US-10b -**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 | -|-------|-----|---------------|----------------| -| 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 | +### Increment 6: Visual Polish & PWA — US-15, US-16, US-14 -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 -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 +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. - %% Phase 0: Infrastructure - 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 +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. - %% Phase 1: Core Event Flow - T4 --> US1["US-1: Create Event"]:::core - US1 --> US2["US-2: View Event"]:::core - US2 --> US3["US-3: RSVP"]:::core +## Deferred AC Activation Schedule - %% Phase 2: Organizer & Lifecycle (branch from US-1) - US1 --> US4["US-4: Guest List"]:::organizer - US1 --> US5["US-5: Edit Event"]:::organizer - US1 --> US18["US-18: Cancel"]:::organizer - US1 --> US19["US-19: Delete"]:::organizer - US1 --> US12["US-12: Auto-Cleanup"]:::organizer - US1 --> US13["US-13: Event Limit"]:::organizer - - %% 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). +| When implementing | Activate deferred AC in | AC description | +|-------------------|------------------------|----------------| +| US-18 (#6) | US-2 AC5 | Cancelled state display | +| US-18 (#6) | US-3 AC11 | RSVP blocked on cancelled event | +| 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) | +| US-19 (#7) | US-2 AC6 | Event not found (organizer deletion) | +| US-12 (#8) | US-2 AC6 | Event not found (expiry deletion) | +| US-16 (#19) | US-12 AC2 | Delete stored header images on expiry |