From a20afd472a165e08dc8cce2cf47247c3cf93e6f9 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 3 Jun 2026 16:05:16 -0400 Subject: [PATCH] docs: define v1 requirements --- .planning/REQUIREMENTS.md | 123 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..9f0f1ca --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,123 @@ +# Requirements: FamilySync + +**Defined:** 2026-06-03 +**Core Value:** The household can see and co-edit one color-coded family calendar (shared + each member's personal) and shared lists from a single low-friction PWA — cross-ecosystem, no app store. + +## v1 Requirements + +Requirements for initial release. Each maps to roadmap phases. + +### Authentication & Onboarding + +> **Given:** Authelia is already deployed and both household members already have Authelia accounts. Auth scope is therefore app-side only — register FamilySync as an OIDC confidential client in Authelia and integrate the login flow. No Authelia deployment, no account provisioning. + +- [ ] **AUTH-01**: User can log in through Authelia (OIDC SSO) — no separate FamilySync account or password to create +- [ ] **AUTH-02**: User stays logged in across sessions so re-authentication is rare (persistent session) +- [ ] **AUTH-03**: Each member maps to a stable identity (OIDC `iss`+`sub`) and is assigned a consistent per-member color + +### Calendar + +- [ ] **CAL-01**: App reads the shared family Fastmail calendar via a CalDAV broker token and caches it locally (ctag polling) +- [ ] **CAL-02**: User sees a unified, color-coded calendar that aggregates every accessible calendar into one view +- [ ] **CAL-03**: User can switch between week, month, day, and agenda/list views +- [ ] **CAL-04**: User can create a timed or all-day event, written back to the correct Fastmail calendar +- [ ] **CAL-05**: User can edit an existing event +- [ ] **CAL-06**: User can delete an event +- [ ] **CAL-07**: User can create a recurring event and see all its occurrences expanded correctly (single-occurrence editing deferred to v1.x) +- [ ] **CAL-08**: Each member's personal Fastmail calendar is overlaid into the unified view — *spike-gated in Phase 1*; if cross-account CalDAV sharing proves infeasible, v1 falls back to shared-family-only and this moves to v1.x + +### Lists + +- [ ] **LIST-01**: User can create and delete named lists (e.g. Groceries, Gift Ideas) +- [ ] **LIST-02**: User can add items to a list, check them off, and delete them +- [ ] **LIST-03**: User can reorder items within a list +- [ ] **LIST-04**: Both members' list edits appear live for the other member without manual refresh + +### Notifications + +- [ ] **NOTIF-01**: User receives a Web Push reminder before an event starts +- [ ] **NOTIF-02**: User receives a Web Push alert when the other member changes a shared list +- [ ] **NOTIF-03**: User receives a Web Push alert when an event is added or changed + +### PWA & Install + +- [ ] **PWA-01**: App is installable to the Home Screen on iPhone and Android (web manifest + service worker, served over HTTPS) +- [ ] **PWA-02**: First-time users get a guided "Add to Home Screen" prompt (prerequisite for iOS Web Push) + +## v1.x Requirements + +Deferred to a near-term follow-up release. Tracked but not in the v1 roadmap. + +### Calendar + +- **CAL-09**: User can edit/delete a single occurrence of a recurring event (RECURRENCE-ID / EXDATE) +- **CAL-10**: User can apply a "this and following" edit to a recurring series +- **CAL-11**: Documentation for subscribing to the Fastmail calendar natively in Apple Calendar via CalDAV (no new code) +- **CAL-12**: Secondary-timezone display toggle for travel + +## v2 Requirements + +### Display + +- **DISP-01**: Always-on wall-display / kiosk dashboard view (Skylight-style) +- **DISP-02**: Upcoming-events / agenda summary widget tuned for the wall display + +## Out of Scope + +Explicitly excluded. Documented to prevent scope creep. Anti-features sourced from research (`.planning/research/FEATURES.md`). + +| Feature | Reason | +|---------|--------| +| Email features | Members keep existing mail clients; never the product's job | +| Self-hosted calendar server (Baikal/Radicale) | Fastmail hosts all calendars via CalDAV; one fewer service | +| Vikunja / external task backend | Lists live in MariaDB; cross-ecosystem native task sync is impossible anyway | +| React Native / App Store app | PWA delivers app-like UX without publishing overhead | +| PostgreSQL | Not in the stack; MariaDB is the database | +| Chores / rewards / star system | No children in the household; lists cover any task need | +| Meal planning / recipe box | Separate domain, high cost; grocery list covers the coordination need | +| Kids / sub-accounts | No children; irrelevant | +| AI email-to-event import | Requires email access (out of scope) + LLM backend; privacy risk | +| RSVP / invite flows (iTIP/iMIP) | Two people share one calendar; both attend by default | +| Event-level comments / photos | Two people can text; adds chat/media storage for ~zero value | +| Activity feed / audit log | Obvious with two users | +| Multi-household / accounts at scale | One household, two hardcoded Authelia accounts | +| Ads / monetization | Self-hosted; no revenue model | +| Complex permissions / role tiers | Two equal partners with identical write access | +| Offline-first with CRDT conflict resolution | Home WiFi is primary; optimistic updates + retry suffice | +| Grocery delivery integration | Third-party dependency; not needed | + +## Traceability + +Which phases cover which requirements. Populated during roadmap creation. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| AUTH-01 | TBD | Pending | +| AUTH-02 | TBD | Pending | +| AUTH-03 | TBD | Pending | +| CAL-01 | TBD | Pending | +| CAL-02 | TBD | Pending | +| CAL-03 | TBD | Pending | +| CAL-04 | TBD | Pending | +| CAL-05 | TBD | Pending | +| CAL-06 | TBD | Pending | +| CAL-07 | TBD | Pending | +| CAL-08 | TBD | Pending | +| LIST-01 | TBD | Pending | +| LIST-02 | TBD | Pending | +| LIST-03 | TBD | Pending | +| LIST-04 | TBD | Pending | +| NOTIF-01 | TBD | Pending | +| NOTIF-02 | TBD | Pending | +| NOTIF-03 | TBD | Pending | +| PWA-01 | TBD | Pending | +| PWA-02 | TBD | Pending | + +**Coverage:** +- v1 requirements: 20 total +- Mapped to phases: 0 (set by roadmapper) +- Unmapped: 20 ⚠️ (resolved at roadmap step) + +--- +*Requirements defined: 2026-06-03* +*Last updated: 2026-06-03 after initial definition*