# Feature Research

**Domain:** Self-hosted family organization hub — shared calendar + shared collaborative lists
**Researched:** 2026-06-03
**Confidence:** HIGH (table stakes and pitfalls well-evidenced across multiple products; differentiators MEDIUM — scoped to 2-person self-hosted context)

---

## Feature Landscape

### Table Stakes (Users Expect These)

Features that must exist on day one. Missing any of these makes the product feel broken, not incomplete.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Unified multi-calendar view | Core value — see all schedules at once | MEDIUM | Aggregating Fastmail shared + personal calendars via JMAP/CalDAV broker token. Color per calendar/member is the visual primitive the whole product depends on. |
| Per-member color coding | Cannot tell whose event is whose without it | LOW | Assign a color per user in app config; render all events in that color regardless of source calendar. |
| Day / week / month / agenda views | All competing apps offer these; absence is jarring | MEDIUM | Month view is the hardest (event overflow, multi-day spanning). Agenda view is easiest. Week view is most-used daily driver. |
| Create / edit / delete events | Read-only calendar is not a calendar app | HIGH | Write-back to the correct Fastmail CalDAV calendar via broker token. Recurring event edits are the hard part (see dependency notes). |
| All-day events | School holidays, birthdays, anniversaries | LOW | CalDAV `DATE` vs `DATETIME` distinction. Visual banner across top of day/week grid. |
| Recurring events (create + display) | Weekly team standups, recurring chores, birthdays | HIGH | RRULE parsing/expansion is deceptively complex. DST handling, exception dates (EXDATE), single-instance modification (RECURRENCE-ID) are all non-trivial. Must use a library (rrule.js or equivalent). |
| Event reminders / push notifications | Time-sensitive alerts are the whole point of a calendar | HIGH | Web Push must be wired in from the start. iOS requires PWA installed to Home Screen; service worker reliability post-device-restart is known to be fragile. Needs fallback strategy (see Pitfalls). |
| Shared list create / check-off / reorder | Grocery list is one of the two primary list use cases | LOW | Simple CRUD in MariaDB. Checkbox state toggle + drag-to-reorder. |
| Live list co-edit sync | Both members shop simultaneously; must not diverge | MEDIUM | WebSocket (preferred) or SSE for push. Optimistic updates in UI; server reconciliation. Redis pub/sub if multi-instance is ever needed — not needed for single-host Docker. |
| Multiple named lists | Groceries and gift ideas are different lists | LOW | A `lists` table with name; items reference list_id. |
| OIDC / SSO login (Authelia) | App must not have its own auth system | MEDIUM | OIDC confidential client flow. Session management. Token refresh. Wife must be able to log in without understanding what OAuth is. |
| PWA installability (Add to Home Screen) | Native-app feel without App Store friction | MEDIUM | Web app manifest, service worker, HTTPS. iOS Safari and Chrome Android have slightly different installation prompts. Icon and splash screen assets required. |
| Low-friction onboarding | Wife adoption is a hard constraint | LOW (UX) / MEDIUM (infra) | One URL → login via Authelia → installed PWA. No calendar credentials to enter. No separate account to create. The OIDC flow is the primary risk — it must feel seamless. |

---

### Differentiators (Competitive Advantage for This Product)

Features where this product can outperform commercial alternatives specifically because it is self-hosted, private, and purpose-built for exactly two people.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| No ads, no freemium walls | Every commercial app (Cozi, TimeTree, Maple) gates useful features behind paid tiers; Cozi restricts free users to 30-day history | LOW (operational cost) | Self-hosted means no monetization pressure. Zero marginal cost per feature. |
| Full personal calendar overlay | Skylight/Cozi only show a shared family calendar; this app aggregates shared + each member's personal Fastmail calendars into one view | MEDIUM | Requires Fastmail calendar sharing ACLs to be configured so the broker token can read both personal calendars. The "Skylight magic" per PROJECT.md. |
| Privacy — data stays home | Commercial apps store your family's schedule on their servers | LOW (architecture choice) | No data leaves the home network except via the Pangolin tunnel the household already controls. |
| Tailored to exactly two users | Commercial apps design for 4–6 family members with kids; complexity of permissions, chores, kids accounts is irrelevant overhead | LOW (scope reduction) | No "family manager" role, no parental controls, no per-member permission tiers. Two equals. |
| Event change notifications | Google Family Calendar explicitly does not send notifications when a member creates/edits an event — a documented pain point | MEDIUM | Web Push on list changes AND calendar changes. "Wife added something to the grocery list" push. "Event was changed" push. |
| Optimistic list UX (instant check-off) | OurGroceries is praised specifically for instant sync on check-off; most apps lag | MEDIUM | Optimistic update in React state, WebSocket confirmation, rollback on failure. |

---

### Anti-Features (Deliberately Exclude)

Features that appear in commercial products but are wrong for a two-person self-hosted household. Building these would bloat scope without providing value.

| Feature | Why Commercial Apps Have It | Why to Exclude | What to Do Instead |
|---------|----------------------------|-----------------|--------------------|
| Chores / rewards / star system | Skylight's chore-chart is a primary SKU driver; kid motivation is a multi-child household need | Zero children in this household. Chores as a product concept doesn't exist here. | Lists serve any "task" need. A grocery list is a chore list if you want it to be. |
| Meal planning / recipe box | Cozi, FamCal, Maple, Skylight all have it; drives DAU | Adds a distinct domain (recipes, ingredients, nutrition) with high implementation cost. A family calendar + grocery list serves 90% of the coordination need without a recipe database. | Add grocery items manually or via list. If meal planning is ever wanted, it's a separate v3 concern. |
| Kids / sub-accounts without email | FamCal's differentiator — create accounts for children | No children; irrelevant | N/A |
| AI email-to-event import | Sense's primary differentiator; Skylight's Magic Import | Requires email access (out of scope), an LLM backend, and ongoing maintenance. Privacy risk. | Create events manually. Event creation UX should be fast enough that manual entry isn't painful. |
| RSVP / event invite flows | Used in apps targeting external coordination | For a two-person household sharing one calendar, RSVP is moot — both members see all events by default. CalDAV RSVP (iTIP/iMIP) is a substantial protocol on top of the calendar work. | Both users always attend shared events. Personal calendar events are visible but don't need RSVP. |
| Event-level comments / photos (TimeTree-style) | TimeTree's differentiator; useful for larger groups coordinating event details | Two people can just text each other. Adds a chat/media system with storage for near-zero incremental value. | Use SMS/iMessage for event-level discussion as now. |
| Activity feed / audit log | TimeTree, some Cozi Gold features | Useful when you need to know which of 5 family members deleted the dentist appointment. With two users it's obvious. | N/A |
| Accounts at scale / multi-household | Commercial apps target 4–6 household members, sometimes multiple households | One household, two users. Multi-tenant adds auth and data isolation complexity for zero gain. | Hardcode exactly two accounts in Authelia. |
| Ads / monetization | Cozi free tier is ad-supported | Self-hosted; no revenue model needed | N/A |
| Complex permissions / role tiers | "Family manager", read-only members, etc. | Two equal partners. | Both users have identical write access to all calendars and lists. |
| Offline-first with full conflict resolution | Required for apps targeting users with spotty connectivity | Home WiFi + PWA is the primary use surface. Brief offline tolerance (optimistic updates + retry) is sufficient. CRDTs and full offline sync are engineering overhead without commensurate benefit. | Optimistic updates + graceful "offline" indicator. Retry on reconnect. |
| Push-to-native-calendar (CalDAV subscribe URL) | Useful for Apple Calendar native integration | Optional, not v1. The PWA is the primary interface. Native calendar subscribe is a nice-to-have for the wife if she wants it — document it, don't build UI for it. | CalDAV subscribe URL for Fastmail calendars already works natively; just document how to set it up. |
| Grocery delivery integration (Instacart, etc.) | Maple's differentiator | Third-party API dependency; not needed when the family handles their own shopping | N/A |

---

## Feature Dependencies

```
[OIDC Login]
    └──required by──> [All other features] (nothing works without auth)

[CalDAV/JMAP broker token]
    └──required by──> [Calendar read]
                          └──required by──> [Unified calendar view]
                          └──required by──> [Per-member color coding]
                          └──required by──> [Day/week/month views]
    └──required by──> [Event create/edit/delete]
                          └──required by──> [All-day events] (DATE type)
                          └──required by──> [Recurring event display]
                                                └──required by──> [Recurring event edit]
                                                                      (RECURRENCE-ID, EXDATE — hardest sub-feature)

[Web Push registration]
    └──required by──> [Event reminders]
    └──required by──> [List change notifications]
    └──enhances──> [Live list sync] (push as fallback to WebSocket on reconnect)

[PWA installability]
    └──required by──> [Web Push on iOS] (iOS only delivers push to installed PWAs)
    └──required by──> [Low-friction onboarding] (one URL → installed app)

[MariaDB lists schema]
    └──required by──> [Named lists]
                          └──required by──> [List items CRUD]
                                                └──required by──> [Check-off / reorder]
                                                └──enhanced by──> [Live list sync via WebSocket]

[Service worker]
    └──required by──> [PWA installability]
    └──required by──> [Web Push]
    └──enhances──> [Offline tolerance] (cache shell, retry queue)
```

### Dependency Notes

- **OIDC login must come first.** Everything else is gated on auth. The OIDC flow with Authelia must be smooth enough that the non-technical member can complete it once, then never see it again (persistent session).
- **CalDAV/JMAP broker token is the calendar foundation.** All calendar features depend on proving this integration works reliably before building display or editing UI on top of it.
- **Recurring events require a library.** Implementing RRULE expansion manually is impractical. Use rrule.js (frontend) and a server-side equivalent for reminder scheduling. Single-instance edits (RECURRENCE-ID) and "this and following" edits add significant complexity and should be scoped carefully — basic recurring create/display can ship before full edit support.
- **PWA install is a prerequisite for iOS Web Push.** Web Push on iOS does not work from a Safari tab — only from an installed PWA. This means the install step is not optional for the wife to receive notifications. The onboarding flow must guide her through Add to Home Screen.
- **Live list sync requires WebSocket infrastructure.** This is a dependency on the server-side connection management (Socket.io or native WS). Redis pub/sub is only needed if the backend ever runs as multiple instances — not relevant for single-Docker-host deployment.

---

## MVP Definition

### Launch With (v1)

- [ ] OIDC login via Authelia — required for everything else; must be seamless for non-technical user
- [ ] CalDAV/JMAP broker integration — read Fastmail calendars (shared + personal)
- [ ] Unified calendar view with per-member colors — day, week, month views
- [ ] Create / edit / delete events (write-back to Fastmail) — all-day and timed; recurring create/display; single-instance edit is a stretch goal
- [ ] Shared lists — create named list, add/check/reorder items, delete items
- [ ] Live list sync via WebSocket — both members co-edit in real time
- [ ] Web Push notifications — event reminders, list change alerts
- [ ] PWA manifest + service worker — installable on iPhone and Android
- [ ] Guided Add to Home Screen prompt on first visit (iOS)

### Add After Validation (v1.x)

- [ ] Recurring event single-instance edit (RECURRENCE-ID) — add after core recurring display is stable and tested
- [ ] "This and following" recurring edit — complex; only add if users report the need
- [ ] Native CalDAV subscribe URL documentation — wife can optionally add to Apple Calendar; no new code needed, just documented
- [ ] Timezone display toggle — show events in a secondary timezone if the household ever travels across zones

### Future Consideration (v2+)

- [ ] Wall-display / kiosk dashboard — per PROJECT.md, explicitly deferred to v2
- [ ] Upcoming events widget / agenda summary — nice home screen widget-style view for the display
- [ ] Calendar event color override per event — current plan is color per member; per-event override adds UI complexity

---

## Feature Prioritization Matrix

| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| OIDC login | HIGH | MEDIUM | P1 |
| CalDAV/JMAP broker | HIGH | HIGH | P1 |
| Unified calendar view (read) | HIGH | MEDIUM | P1 |
| Per-member color coding | HIGH | LOW | P1 |
| Day / week / month views | HIGH | MEDIUM | P1 |
| Event create/edit/delete | HIGH | HIGH | P1 |
| All-day events | HIGH | LOW | P1 |
| Recurring events (create + display) | HIGH | HIGH | P1 |
| Shared lists CRUD | HIGH | LOW | P1 |
| Live list sync (WebSocket) | HIGH | MEDIUM | P1 |
| Web Push notifications | HIGH | HIGH | P1 |
| PWA installability | HIGH | MEDIUM | P1 |
| List change notifications | MEDIUM | LOW | P1 (shares push infra) |
| Recurring event single-instance edit | MEDIUM | HIGH | P2 |
| "This and following" recurring edit | LOW | HIGH | P3 |
| Native CalDAV subscribe docs | LOW | LOW | P2 |
| Timezone display toggle | LOW | MEDIUM | P3 |
| Wall-display kiosk view | MEDIUM | MEDIUM | P3 (v2) |

---

## Competitor Feature Analysis

| Feature | Skylight | Cozi | TimeTree | Google Family | This Product |
|---------|----------|------|----------|---------------|--------------|
| Color per member | Yes | Yes | Yes | No | Yes |
| Personal + shared calendar overlay | No (shared only) | No | No | No | Yes (Fastmail aggregation) |
| Multiple calendar views | Yes | Partial (Gold gates month) | Yes | Yes | Yes |
| Recurring events | Yes | Yes | Yes | Yes | Yes (display v1; full edit v1.x) |
| Shared lists | Yes | Yes | No | No | Yes |
| Live list sync | Unknown | Yes | N/A | N/A | Yes (WebSocket) |
| Push notifications on change | Yes | Partial | Yes | No | Yes |
| Event-level comments | No | No | Yes | No | No (anti-feature) |
| Chores / rewards | Yes (primary feature) | Yes | No | No | No (anti-feature) |
| Meal planning | Yes | Yes | No | No | No (anti-feature) |
| AI import | Yes (Magic Import) | No | No | No | No (anti-feature) |
| RSVP | No | No | No | No | No (anti-feature) |
| Self-hosted / private | No | No | No | No | Yes (differentiator) |
| No ads / no paywall | No (Plus plan) | No (Gold plan) | No (Premium) | Yes | Yes |
| Cross-ecosystem (iOS + Android) | App + hardware | App | App | App | PWA (single URL) |

---

## Sources

- [Skylight Calendar product page](https://myskylight.com/calendar/)
- [Skylight Calendar 2 TechCrunch review, Jan 2026](https://techcrunch.com/2026/01/07/skylight-debuts-calendar-2-to-keep-your-family-organized/)
- [Cozi feature overview](https://www.cozi.com/feature-overview/)
- [Cozi Gold features](https://www.cozi.com/cozi-gold-features/)
- [Maple best family calendar app comparison](https://www.growmaple.com/blog-posts/best-family-calendar-app)
- [Best Family Calendar Apps 2026 — getsense.ai](https://getsense.ai/blog/posts/best-family-calendar-apps-2026)
- [TimeTree review and features](https://toolstack.io/tools/timetree)
- [Google Family Calendar — support.google.com](https://support.google.com/families/answer/7157782)
- [Nylas: The Deceptively Complex World of RRULEs](https://www.nylas.com/blog/calendar-events-rrules/)
- [Mozilla Wiki: Calendar Recurrence and Exceptions](https://wiki.mozilla.org/Calendar:Recurrence_and_Exceptions)
- [PWA iOS limitations 2026 — magicbell.com](https://www.magicbell.com/blog/pwa-ios-limitations-safari-support-complete-guide)
- [PWA push notifications iOS — OneSignal docs](https://documentation.onesignal.com/docs/en/web-push-for-ios)
- [Real-time data sync with WebSockets — GTCSys](https://gtcsys.com/real-time-communication-in-pwas-websockets-server-sent-events-and-webrtc/)

---
*Feature research for: FamilySync — self-hosted family organization hub*
*Researched: 2026-06-03*
