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