fete/spec/implementation-phases.md

Implementation Phases

A recommended implementation order based on the dependency graph across all stories and setup tasks.

Phase 0: Project Infrastructure

All setup tasks must complete before any user story work begins. T-3 can run in parallel with Phase 1.

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)

Phase 1: Core Event Flow (Vertical Slice)

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	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	—

These three stories are strictly sequential. No parallelization within this phase.

Phase 2: Organizer Management & Event Lifecycle

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.

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

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.

Phase 3: Enhanced Event Page Features

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.

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

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).

Phase 4: Visual Customization

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.

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

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.

Phase 5: App Shell & PWA

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.

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

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).

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.

Deferred Acceptance Criteria

Several stories contain ACs that reference features from later phases. These are marked [deferred until US-X is implemented] in the story text:

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

Once the referenced story is implemented, revisit the deferring story to activate the deferred AC.

Dependency Graph

Render this diagram at mermaid.live or view it directly in Gitea (which renders mermaid blocks natively).

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
    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
    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)
    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).