# Stack Research

**Domain:** Self-hosted family calendar + shared-lists PWA on Fastmail
**Researched:** 2026-06-03
**Confidence:** MEDIUM-HIGH (calendar sharing cross-account caveat: LOW; rest HIGH)

---

## Recommended Stack

### Core Technologies

| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| Node.js + TypeScript | 22 LTS | Backend runtime | First-class typing, same language as frontend, largest CalDAV/OIDC library ecosystem |
| Hono | 4.12.23 | HTTP framework | Web-Standards-native, first-class TypeScript, built-in SSE helper, WebSocket via `@hono/node-server`; lighter than Express and better ergonomics than Fastify for this size |
| Drizzle ORM | 0.45.2 | MariaDB query layer | Type-safe SQL, zero runtime overhead, native `mysql2` driver support, schema-as-code migrations via `drizzle-kit` |
| mysql2 | 3.22.4 | MariaDB driver | The only maintained native MariaDB/MySQL driver; Drizzle targets it explicitly |
| React 19 | 19.x | PWA frontend | Required by project; concurrent features, stable |
| Vite | 8.0.x | Build tooling | De-facto standard for React PWAs; fast HMR, native ESM |
| vite-plugin-pwa | 1.3.0 | Service worker + manifest | Zero-config Workbox integration, handles install prompt, offline cache, background sync scaffolding |

### Supporting Libraries

| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| tsdav | 2.2.2 | CalDAV client for Node.js | All calendar reads and writes against Fastmail CalDAV endpoint; handles PROPFIND, REPORT, PUT, DELETE |
| ical.js | 2.2.1 | iCalendar (.ics) parsing | Parse raw VCALENDAR/VEVENT payloads returned by tsdav; handles VTIMEZONE, RDATE, EXDATE |
| rrule | 2.8.1 | Recurrence rule expansion | Expand RRULE strings into concrete event occurrences for the calendar view; ical.js's built-in expansion is less ergonomic for UI consumption |
| web-push | 3.6.7 | Server-side VAPID push | Generate VAPID keys, sign and dispatch push messages to browser push services (APNs for iOS, FCM for Android) |
| @hono/oidc-auth | 1.8.3 | OIDC session middleware for Hono | Storage-less JWT session cookies; authorization-code + PKCE flow; works with any RFC-compliant OIDC provider including Authelia |
| openid-client | 6.8.4 | Low-level OIDC primitives | If `@hono/oidc-auth` proves insufficient (e.g., custom token introspection), use this as the lower-level escape hatch |
| ioredis | 5.11.0 | Redis client | Pub/sub for broadcasting list-change events to SSE connections across Node processes |
| zod | 3.24.x | Schema validation | Validate API request bodies and CalDAV event payloads before writing back to Fastmail |
| @hono/zod-validator | 0.8.0 | Hono middleware for Zod | Validate request body/query in route handlers with Zod schemas |
| @tanstack/react-query | 5.101.0 | Server state + caching | Manages calendar and list data fetching, background refetch, stale-while-revalidate; pairs with SSE for live list updates |
| zustand | 5.0.14 | Client state | UI-only state (selected date range, color assignments, drawer open/closed); keep server state in React Query |
| drizzle-kit | 0.31.10 | Schema migrations | Generates and runs MariaDB migrations from Drizzle schema definitions |

### Development Tools

| Tool | Purpose | Notes |
|------|---------|-------|
| TypeScript 5.x | Strict typing across backend + frontend | `strict: true`; share types between packages via a `packages/shared` workspace |
| ESLint + Prettier | Lint + format | Standard config; no bikeshedding needed |
| Docker Compose | Local dev + production parity | Match Unraid stack exactly in dev |
| Vitest | Unit + integration tests | Vite-native, same config as frontend |

---

## Installation

```bash
# Backend
npm install hono @hono/node-server @hono/oidc-auth @hono/zod-validator
npm install drizzle-orm mysql2 ioredis
npm install tsdav ical.js rrule
npm install web-push zod openid-client

# Frontend
npm install react react-dom @tanstack/react-query zustand
npm install -D vite vite-plugin-pwa

# Dev
npm install -D typescript drizzle-kit vitest @types/node @types/web-push
```

---

## Calendar Integration: CalDAV, Not JMAP

**Decision: CalDAV via `tsdav`. JMAP for calendars is not available from Fastmail.**

Fastmail's developer docs (as of 2026-06-03) state explicitly: calendar access is CalDAV only; JMAP calendar support is planned but blocked on RFC 8984 specification finalization. The JMAP working group has not finalized the calendars spec. Do not plan around JMAP calendars — it is not a near-term option.

**CalDAV mechanics with tsdav:**

- Principal URL: `https://caldav.fastmail.com/dav/principals/user/broker@fastmail.com/`
- `tsdav` performs `PROPFIND` on the principal to discover all calendar collections, then fetches each collection's events via `REPORT` (calendar-query or calendar-multiget).
- One app password covers all calendars owned by that account under the default "Mail, Contacts & Calendars" scope.
- `tsdav` returns raw iCalendar strings. Pass each to `ical.js` for parsing into event objects, then use `rrule` for RRULE expansion into the date range the UI needs.
- Write-back (create/edit/delete): PUT a new `.ics` to the collection URL; DELETE by UID.

**Authentication model:**

Use a Fastmail app password (not OAuth) for the backend broker token. App passwords are simple HTTP Basic credentials. OAuth is intended for distributing apps to Fastmail users — not applicable here. The app password is a server secret stored in an environment variable; it never leaves the backend.

**Personal calendar aggregation — IMPORTANT CAVEAT (LOW confidence):**

Fastmail's multi-user calendar sharing is documented only for users within the same Fastmail account (i.e., a multi-user/family Fastmail subscription). If both household members are on the same Fastmail family plan, the primary account holder can be granted edit access to the other member's personal calendar, and the broker token for the primary account will discover and read/write those shared calendars via CalDAV. If the wife has a separate independent Fastmail account, cross-account CalDAV sharing via a single broker token is unconfirmed — this should be tested before Phase 1 commits to the personal-calendar overlay feature. The shared family calendar (owned by the primary account) works unconditionally.

**What NOT to use for calendars:**

- `node-ical`: older fork with weaker RRULE support; ical.js is maintained by Mozilla and is the reference implementation
- Direct `fetch`/`axios` against CalDAV: re-inventing XML namespace handling and PROPFIND parsing; tsdav exists specifically to avoid this
- JMAP: not available for calendars on Fastmail today

---

## Backend Framework

**Decision: Hono on Node.js**

Hono is the right size for this app. Express is fine but has no TypeScript-native ergonomics. NestJS is overkill for a two-person household app. Hono gives you:
- First-class TypeScript with RPC-style type sharing (Hono RPC can export typed client for the React frontend — eliminates API drift)
- Built-in SSE streaming helper (`streamSSE`) for live list updates
- WebSocket support via `@hono/node-server`
- Runs on Node.js 22 LTS in Docker with `@hono/node-server`

**ORM: Drizzle + mysql2**

Drizzle is the correct choice over Prisma for this stack:
- Prisma generates a binary engine that adds complexity in Docker images and has weaker MariaDB compatibility signals
- Drizzle uses `mysql2` directly — the same driver you'd use raw; no runtime translation layer
- Drizzle's `mysqlTable` schema is fully MariaDB-compatible (MariaDB is wire-compatible with MySQL; Drizzle's `mysql` dialect works)
- Type inference from schema → query results is the core value proposition; zero runtime overhead

---

## React PWA Stack

**Build: Vite 8 + vite-plugin-pwa 1.3.0**

Standard for React PWAs. `vite-plugin-pwa` configures the Web App Manifest and injects a Workbox service worker. Use `injectManifest` strategy (not `generateSW`) so you have explicit control over the service worker file — required for Web Push subscription management.

**State/data: TanStack Query + Zustand**

- TanStack Query owns all server-side state: calendar events, lists, user profile. It handles background refetch, cache invalidation, and loading states. Use `queryClient.invalidateQueries` from SSE event handlers to keep list data live.
- Zustand owns pure UI state: selected month, color assignments per calendar, drawer states. Do not put server data in Zustand.

**Web Push (VAPID):**

1. Generate a VAPID key pair once (`web-push generateVAPIDKeys`), store in environment variables.
2. Expose the public key via an API route; the PWA calls `pushManager.subscribe({ userVisibleOnly: true, applicationServerKey })` from a user-gesture handler.
3. Store the `PushSubscription` object (endpoint, keys) in MariaDB per user.
4. Backend sends notifications via `web-push.sendNotification(subscription, payload)`.

**iOS-specific Web Push constraints (CRITICAL):**

| Requirement | Detail |
|-------------|--------|
| Minimum iOS version | 16.4 — push is silently unavailable on earlier versions |
| Installation required | PWA **must** be added to Home Screen; push does not work from Safari browser tabs |
| User gesture | `pushManager.subscribe()` must be called inside a tap handler, not on page load |
| EU users on iOS 17.4+ | PWAs may open in Safari tabs instead of standalone mode due to DMA; affects push reach |
| Silent push | Not supported on iOS; all push messages must display a visible notification |
| Background sync | Not supported on iOS; no `BackgroundSync` or `PeriodicBackgroundSync` |

**Declarative Web Push (Safari 18.4+):** Apple shipped Declarative Web Push in Safari 18.4 (iOS 18.4, March 2025). It's backward-compatible: send a JSON payload with `"web_push": 8030` and the browser renders the notification without a service worker handler. The `web-push` npm library (v3.6.7) does not generate this format natively — you'd hand-craft the JSON payload for iOS while the same endpoint handles standard Web Push for Android/desktop. As of mid-2026, Declarative Web Push is a W3C Working Draft and the preferred format for iOS/macOS push. Build the push payload to be Declarative Web Push compatible from day one (it's just a JSON schema change), since `web-push` still handles the VAPID transport layer.

**Onboarding UX for iOS (wife):** The install-to-home-screen step is unavoidable for push notifications. Design the first-run flow to prompt this explicitly (custom install banner, step-by-step guide). Once installed, OIDC login via Authelia is one tap — the low-friction goal is achievable.

---

## Authelia OIDC Integration

**Decision: `@hono/oidc-auth` middleware**

Authelia exposes a standards-compliant OIDC discovery endpoint. `@hono/oidc-auth` uses `oauth4webapi` under the hood, supports authorization code + PKCE, and produces storage-less JWT session cookies — no Redis or session DB required for auth state.

**Flow:**
1. Unauthenticated request → middleware redirects to Authelia's authorization endpoint
2. Authelia authenticates the user, redirects back with `code`
3. Middleware exchanges code for tokens, creates signed JWT session cookie (httpOnly, Secure, SameSite=Lax)
4. Cookie is verified on every request; refresh tokens are used to silently re-authenticate before expiry

**Authelia configuration requirements:**
- `response_types: [code]`
- `grant_types: [authorization_code, refresh_token]`
- `require_pkce: true`, `pkce_challenge_method: S256`
- `token_endpoint_auth_method: client_secret_basic`

Authelia's own integration docs show this exact pattern for Express.js (`express-openid-connect`). `@hono/oidc-auth` is the Hono-native equivalent. If it hits edge cases, `openid-client` v6 is the lower-level fallback.

**Do NOT use:** `oidc-client-ts` — it is a browser-side library for SPAs doing the OIDC flow in the frontend. This app has a backend session; the OIDC flow belongs on the server.

---

## Live List Sync

**Decision: SSE (Server-Sent Events) + Redis Pub/Sub, not WebSockets**

Lists are co-edited by two people. The update direction is server → client (server broadcasts when one client mutates a list). SSE is simpler than WebSockets for this: plain HTTP, works through proxies, automatic reconnection in browsers.

Pattern:
1. Client opens `GET /api/lists/stream` → Hono `streamSSE` keeps connection alive
2. On a list mutation, the backend publishes a `list:updated:{listId}` event to Redis
3. All Node processes subscribed to Redis receive the event and push it to connected SSE clients
4. React Query on the client receives the SSE event → `invalidateQueries(['lists', listId])` → refetches

Redis (`ioredis`) is only needed if multiple Node containers run behind a load balancer. For a single Unraid Docker Compose with one backend container, you can skip Redis and use an in-process event emitter — leave the abstraction clean so Redis can be added later.

---

## Alternatives Considered

| Recommended | Alternative | Why Not |
|-------------|-------------|---------|
| Hono | Express | No native TypeScript ergonomics; no built-in SSE; larger ecosystem but more boilerplate |
| Hono | Fastify | Good choice but heavier plugin model; Hono's Web Standards alignment is better for this size |
| Drizzle | Prisma | Binary engine complicates Docker; weaker explicit MariaDB support; heavier |
| tsdav | Raw fetch + xml2js | CalDAV XML namespace handling is tedious; tsdav is the established TypeScript CalDAV client |
| ical.js | node-ical | node-ical is a fork that has diverged; ical.js is the Mozilla-maintained reference implementation |
| @hono/oidc-auth | express-openid-connect | express-openid-connect is Express-specific; Hono middleware is the correct fit |
| SSE | WebSockets | WebSockets are bidirectional; list sync is server→client only; SSE is simpler and proxy-friendly |
| CalDAV | JMAP | JMAP calendars not available on Fastmail as of 2026 |

---

## What NOT to Use

| Avoid | Why | Use Instead |
|-------|-----|-------------|
| JMAP for calendars | Not implemented by Fastmail; spec not finalized | CalDAV via tsdav |
| Prisma | Binary engine, weaker MariaDB compat, larger footprint in Docker | Drizzle ORM |
| oidc-client-ts | Browser-side OIDC library; wrong layer for a backend-session app | @hono/oidc-auth |
| node-ical | Older fork of ical.js, less maintained, weaker RRULE handling | ical.js |
| Create React App | Deprecated February 2025 | Vite |
| PostgreSQL | Not in the Unraid stack; hard constraint | MariaDB |
| NestJS | Massive framework overhead for a two-user household app | Hono |
| Firebase/FCM as push broker | Third-party dependency; VAPID direct push works without it | web-push (VAPID) |

---

## Version Compatibility

| Package | Compatible With | Notes |
|---------|-----------------|-------|
| drizzle-orm@0.45.x | mysql2@3.x | Use `drizzle-orm/mysql2` import path; mysql2@3.x uses Promises API by default |
| vite-plugin-pwa@1.3.x | Vite@8.x, Workbox@7.x | vite-plugin-pwa 0.16+ requires Node 16+; 1.x tracks Vite 6+ |
| @hono/oidc-auth@1.8.x | hono@4.x, oauth4webapi | Peer-depends on hono 4.x |
| ical.js@2.x | rrule@2.8.x | Use together: ical.js parses the RRULE string, pass to `new RRule(RRule.parseString(...))` |
| web-push@3.6.x | Node.js 18+ | VAPID uses Web Crypto; works in Node.js 18+ natively |

---

## Open Questions Flagged for Phase Research

1. **Personal calendar cross-account sharing (LOW confidence):** Does the wife's personal Fastmail calendar (if she has a separate account) appear in the broker token's CalDAV principal discovery? This must be manually tested before committing to the personal-calendar overlay in Phase 1. If it does not work, the v1 fallback is: shared family calendar only, with a read-only ICS subscription URL for the wife's personal calendar displayed separately.

2. **Declarative Web Push server-side format:** The `web-push` npm library does not natively output the `"web_push": 8030` Declarative Web Push JSON format. Verify whether iOS 18.4+ APNs endpoint accepts standard VAPID push payloads (it does for the VAPID transport layer) vs. needing the declarative JSON in the payload body. The answer is: VAPID is the transport; Declarative Web Push is the payload format. Both can coexist in the same push subscription.

3. **EU DMA regression:** If either household member is in the EU on iOS 17.4+, PWA standalone mode is broken and push will not work. Confirm geographic context is outside EU — this is the project owner's constraint to verify.

---

## Sources

- [Fastmail API Documentation](https://www.fastmail.com/dev/) — Confirmed CalDAV-only for calendars; JMAP calendars not available
- [Fastmail App Passwords](https://www.fastmail.help/hc/en-us/articles/360058752854-App-passwords) — Scope covers CalDAV; single password covers all calendars in account
- [Using Fastmail with CalDAV libraries](https://utf9k.net/blog/fastmail-caldav/) — Principal URL pattern, app password auth
- [Fastmail Calendar Sharing](https://www.fastmail.help/hc/en-us/articles/1500000279781-Sharing-calendars-with-other-users) — Sharing is multi-user-account scoped; cross-account sharing unconfirmed
- [tsdav npm](https://www.npmjs.com/package/tsdav) — Version 2.2.2 confirmed
- [ical.js npm](https://www.npmjs.com/package/ical.js) — Version 2.2.1 confirmed; Mozilla-maintained
- [rrule npm](https://www.npmjs.com/package/rrule) — Version 2.8.1 confirmed
- [Hono](https://hono.dev/) — Version 4.12.23; Node.js adapter confirmed
- [Drizzle ORM MySQL](https://orm.drizzle.team/docs/get-started-mysql) — MariaDB via mysql2 confirmed
- [vite-plugin-pwa](https://vite-pwa-org.netlify.app/) — Version 1.3.0; Workbox 7 integration
- [web-push npm](https://www.npmjs.com/package/web-push) — Version 3.6.7
- [Meet Declarative Web Push — WebKit](https://webkit.org/blog/16535/meet-declarative-web-push/) — Safari 18.4+, iOS 18.4+ confirmed
- [PWA iOS Limitations 2026](https://www.magicbell.com/blog/pwa-ios-limitations-safari-support-complete-guide) — iOS 16.4 minimum; home screen required; EU DMA regression
- [Authelia Express.js Integration](https://www.authelia.com/integration/openid-connect/clients/expressjs/) — Authorization code + PKCE flow; client_secret_basic
- [@hono/oidc-auth GitHub](https://github.com/honojs/middleware/tree/main/packages/oidc-auth) — Storage-less JWT session cookies; Version 1.8.3

---

*Stack research for: FamilySync — self-hosted family calendar + shared-lists PWA on Fastmail*
*Researched: 2026-06-03*