initial commit
This commit is contained in:
Lucas Berger
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: FamilySync Architecture Decisions
|
||||
date: 2026-06-02
|
||||
context: Exploration + verification sessions — reasoning captured before project kickoff
|
||||
---
|
||||
|
||||
# FamilySync Architecture Decisions
|
||||
|
||||
## What we're building
|
||||
|
||||
A self-hosted family organization hub, modeled loosely on Skylight, with two concerns:
|
||||
1. **Shared calendar** — one family calendar everyone can see and edit, surfaced natively
|
||||
where possible and in a custom app everywhere else
|
||||
2. **Shared collaborative lists** — grocery lists, gift ideas, anything co-edited
|
||||
3. **Family display** — Skylight-style always-on view + mobile-accessible dashboard
|
||||
|
||||
Email is **out of scope** — members keep using their existing mail clients unchanged.
|
||||
|
||||
## Household
|
||||
|
||||
- **Primary user (me):** Fastmail account, Android, uses the Fastmail app
|
||||
- **Other members (e.g. wife):** Apple (iPhone/Mac)
|
||||
- Wife adoption is a hard UX constraint — must be slick and low-friction
|
||||
|
||||
## Infrastructure
|
||||
|
||||
- **Host**: Unraid running Docker containers + Docker Compose
|
||||
- **Auth**: Authelia (already deployed) — OIDC/OAuth2 for the custom app
|
||||
- **DNS**: Split-DNS internal domain, private IPs internally
|
||||
- **Public exposure**: Pangolin/Newt tunnel (no open ports)
|
||||
- **Database**: MariaDB (preferred), Redis available, PostgreSQL not available
|
||||
- **Existing service leveraged**: Fastmail (paid) — used as the calendar host
|
||||
|
||||
## Stack decisions (verified)
|
||||
|
||||
### Calendar → Fastmail (NOT self-hosted)
|
||||
|
||||
The shared family calendar lives on Fastmail. Self-hosting the calendar data was evaluated and
|
||||
explicitly rejected as unnecessary — Fastmail already provides a CalDAV/JMAP server everyone can
|
||||
reach.
|
||||
|
||||
- **Me (Android/Fastmail):** native in the Fastmail app, read-write. Nothing to install.
|
||||
- **Custom app:** holds a Fastmail JMAP/CalDAV token; reads AND writes the shared calendar as the
|
||||
broker for everyone else.
|
||||
- **Apple members:** use the PWA by default (app writes to Fastmail on their behalf — no Fastmail
|
||||
account needed). Optional: add the Fastmail calendar via CalDAV to native Apple Calendar for
|
||||
native read-write. Not required.
|
||||
|
||||
**Why not Baikal (self-hosted CalDAV)?** It was the prior pick, now dropped. The Fastmail Android
|
||||
app cannot display a self-hosted CalDAV calendar, so Baikal bought *me* nothing on Android — it
|
||||
only helped Apple members, who are equally served by the PWA. Fastmail-hosted gives the whole
|
||||
household native-or-PWA access with one fewer self-hosted service.
|
||||
|
||||
**Reversibility:** if self-hosted calendar is ever wanted, Baikal slots in as source of truth and
|
||||
the app reads from it instead of Fastmail. Nothing else changes.
|
||||
|
||||
### Lists → custom app backend (MariaDB)
|
||||
|
||||
Shared lists live directly in the custom app's MariaDB, served via the app's own API to the PWA.
|
||||
Redis optional for live/push updates.
|
||||
|
||||
**Why not Vikunja?** Prior pick, now dropped. Native cross-ecosystem list sync is impossible here
|
||||
(Apple Reminders is CalDAV VTODO; Fastmail has no real tasks product; Google Tasks isn't CalDAV).
|
||||
So lists must live in the app regardless. Since the custom backend is being built anyway, a list
|
||||
table in its own MariaDB is trivial — whereas Vikunja means another container, another schema, and
|
||||
another Authelia SSO integration to maintain for features (assignees, gantt, recurring) not needed
|
||||
for "groceries + gift ideas." Reversible later if richer task management is wanted.
|
||||
|
||||
### Display + aggregation → custom app (the actual product)
|
||||
|
||||
- Aggregates the Fastmail shared calendar (+ optionally each member's personal calendars) into a
|
||||
unified, color-coded family view — the Skylight magic; nothing off-the-shelf does this.
|
||||
- Owns the shared lists.
|
||||
- Authelia OIDC for app login (true SSO; no separate calendar credential problem since Baikal is gone).
|
||||
- Serves the React PWA + the wall-display view.
|
||||
|
||||
### Frontend → React PWA
|
||||
|
||||
- Runs as a kiosk URL on a wall-mounted display (future state)
|
||||
- Installable on iPhone/Android via "Add to Home Screen" — no App Store
|
||||
- Wife onboards by visiting one URL — the universal surface for everyone
|
||||
- Single codebase for all surfaces (display, phone, desktop)
|
||||
|
||||
## What we decided NOT to do
|
||||
|
||||
- **No self-hosted calendar server (Baikal)** — Fastmail hosts the calendar
|
||||
- **No Vikunja** — lists live in the custom backend
|
||||
- **No DAVx5** — not needed
|
||||
- **No forking** — value is the aggregation/display layer, not the backends
|
||||
- **No React Native / App Store** — PWA gives app-like experience without publishing overhead
|
||||
- **No PostgreSQL** — not in the existing stack
|
||||
- **No email features** — out of scope
|
||||
|
||||
## Net result
|
||||
|
||||
You build **one thing** — the custom app (backend + MariaDB + React PWA) behind Authelia — on top
|
||||
of Fastmail you already pay for. Far lighter than the prior Baikal + Vikunja + PWA design, and the
|
||||
lowest-friction path for non-technical household members (one PWA).
|
||||
|
||||
## Open questions
|
||||
|
||||
- Fastmail API: JMAP vs CalDAV for the app's calendar read/write — which is cleaner to build against?
|
||||
- Aggregating Apple members' *personal* calendars into the display — via shared CalDAV/ICS, or skip
|
||||
and only show the shared family calendar?
|
||||
- PWA push notifications: sufficient for family alerts, or need something else?
|
||||
|
||||
## Resolved questions
|
||||
|
||||
- **Calendar host**: Fastmail (self-hosting rejected as unnecessary)
|
||||
- **Calendar server (Baikal vs Radicale)**: moot — calendar moved to Fastmail
|
||||
- **Lists backend (Vikunja)**: dropped — lists live in the custom app's MariaDB
|
||||
- **Email**: out of scope
|
||||
@@ -0,0 +1,46 @@
|
||||
# Research Questions
|
||||
|
||||
## Open
|
||||
|
||||
### RQ-003 — Fastmail calendar API: JMAP vs CalDAV
|
||||
**Question**: For the custom app to read AND write the shared family calendar on Fastmail, is JMAP
|
||||
or CalDAV the cleaner integration? Can a scoped Fastmail API token grant calendar read-write without
|
||||
exposing the full account?
|
||||
|
||||
**Why it matters**: The app brokers calendar access for all Apple members via the PWA, so reliable
|
||||
programmatic read-write to the Fastmail calendar is core. JMAP is Fastmail-native and modern; CalDAV
|
||||
is the interoperable standard.
|
||||
|
||||
**Suggested approach**: Check Fastmail JMAP Calendars docs + API token scoping. Confirm event
|
||||
create/update/delete works via token. Compare to CalDAV (sabre-dav style) effort.
|
||||
|
||||
---
|
||||
|
||||
## Resolved
|
||||
|
||||
### RQ-001 — Vikunja MariaDB compatibility — SUPERSEDED
|
||||
Vikunja was dropped from the architecture (lists now live in the custom app's own MariaDB). The
|
||||
MariaDB findings still apply to the custom app itself: use MariaDB 10.6+, set `utf8mb4` collation,
|
||||
pin versions before upgrades.
|
||||
|
||||
---
|
||||
|
||||
### RQ-002 — CalDAV server: Radicale vs Baikal — SUPERSEDED
|
||||
Both dropped. The shared calendar now lives on **Fastmail**, not a self-hosted CalDAV server.
|
||||
Rationale: the Fastmail Android app cannot display a self-hosted CalDAV calendar, so Baikal gave the
|
||||
primary (Android/Fastmail) user no native benefit — it only helped Apple members, who are equally
|
||||
served by the PWA. Fastmail-hosted removes a self-hosted service while keeping native access for the
|
||||
Fastmail user and PWA access for everyone.
|
||||
|
||||
Original finding (retained for reversibility): if self-hosting the calendar is ever required, **Baikal**
|
||||
(`ckulka/baikal`) is the pick over Radicale — Radicale has no native shared-calendar write support.
|
||||
|
||||
---
|
||||
|
||||
### Calendar host decision — RESOLVED
|
||||
Self-hosting the calendar data was evaluated and rejected. Fastmail (already paid for) hosts the
|
||||
shared family calendar. Other household members are Apple — they reach it via the PWA (default) or
|
||||
native Apple Calendar over CalDAV (optional).
|
||||
|
||||
### Email scope — RESOLVED
|
||||
Out of scope. Members keep existing mail clients unchanged.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Kick off FamilySync with /gsd:new-project
|
||||
date: 2026-06-02
|
||||
priority: high
|
||||
---
|
||||
|
||||
# Kick off FamilySync with /gsd:new-project
|
||||
|
||||
Run `/gsd:new-project` to formalize the architecture decisions into a PROJECT.md, REQUIREMENTS.md,
|
||||
and ROADMAP.md with phase breakdown.
|
||||
|
||||
Architecture is verified and settled (see `.planning/notes/familysync-architecture.md`).
|
||||
|
||||
## Pre-work before running
|
||||
|
||||
- [ ] (Optional) Answer RQ-003: Fastmail calendar API — JMAP vs CalDAV for app read/write
|
||||
- [ ] Review `.planning/notes/familysync-architecture.md` — feed this into the project questionnaire
|
||||
|
||||
## Context to bring into the session
|
||||
|
||||
- Family hub modeled on Skylight. Owner on Fastmail/Android; other members Apple. Wife adoption is
|
||||
a hard UX constraint (one slick PWA).
|
||||
- **Calendar**: hosted on Fastmail (NOT self-hosted). Custom app brokers read/write via JMAP/CalDAV
|
||||
token. Owner native in Fastmail app; Apple members via PWA.
|
||||
- **Lists + display**: one self-hosted custom app — backend + MariaDB, aggregates calendars into a
|
||||
Skylight-style view, owns shared lists, serves React PWA (phones + wall-display kiosk).
|
||||
- **Auth**: Authelia OIDC for the app.
|
||||
- **Infra**: Unraid + Docker Compose + Pangolin/Newt + split-DNS. MariaDB + Redis.
|
||||
- **Dropped**: Baikal, Vikunja, DAVx5 (see architecture note for why).
|
||||
- **Out of scope**: email. **Excluded**: PostgreSQL, App Store/React Native, forking.
|
||||
- Net: build ONE app on top of existing Fastmail.
|
||||
Reference in New Issue
Block a user