213 lines
17 KiB
Markdown
213 lines
17 KiB
Markdown
# 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*
|