cleanup

- pnpm monorepo (apps/client + apps/server)
- Server: Express + node:sqlite with numbered migration runner,
  REST API for all 9 features (members, events, chores, shopping,
  meals, messages, countdowns, photos, settings)
- Client: React 18 + Vite + TypeScript + Tailwind + Framer Motion + Zustand
- Theme system: dark/light + 5 accent colors, CSS custom properties,
  anti-FOUC script, ThemeToggle on every surface
- AppShell: collapsible sidebar, animated route transitions, mobile drawer
- Phase 2 features: Calendar (custom month grid, event chips, add/edit modal),
  Chores (card grid, complete/reset, member filter, streaks),
  Shopping (multi-list tabs, animated check-off, quick-add bar, member assign)
- Family member CRUD with avatar, color picker
- Settings page: theme/accent, photo folder, slideshow, weather, date/time
- Docker: multi-stage Dockerfile, docker-compose.yml, entrypoint with PUID/PGID
- Unraid: CA XML template, CLI install script, UNRAID.md guide
- .gitignore covering node_modules, dist, db files, secrets, build artifacts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,30 @@
+# Git
+.git
+.gitignore
+
+# Node modules (installed fresh in Docker)
+node_modules
+apps/*/node_modules
+
+# Dev/test artifacts
+apps/client/dist
+apps/server/dist
+apps/server/data
+
+# Env files (never bake secrets into the image)
+.env
+.env.*
+
+# OS / editor noise
+.DS_Store
+Thumbs.db
+*.log
+
+# Agent / docs (not needed at runtime)
+AGENTS.md
+DEPLOYMENT-PROFILE.md
+INSTALL.md
+ROUTING-EXAMPLES.md
+SKILLS.md
+hubs/
+skills/

.env.example

@@ -0,0 +1,19 @@
+# Copy this file to .env and fill in your values.
+# docker-compose.yml reads these automatically.
+
+# Host port the app will be accessible on
+PORT=3001
+
+# Your timezone (used for correct date/time display)
+TZ=America/New_York
+
+# Host path where the SQLite database is stored
+DATA_PATH=/mnt/user/appdata/family-planner
+
+# Host path to your photo library (mounted read-only into the container)
+PHOTOS_PATH=/mnt/user/Photos
+
+# File ownership inside the container
+# Unraid default: nobody (99) + users (100)
+PUID=99
+PGID=100

.gitignore

@@ -0,0 +1,39 @@
+# ── Dependencies ──────────────────────────────────────────────────────────────
+node_modules/
+.pnpm-store/
+
+# ── Build output ──────────────────────────────────────────────────────────────
+apps/client/dist/
+apps/server/dist/
+*.tsbuildinfo
+
+# ── Database & runtime data ───────────────────────────────────────────────────
+apps/server/data/
+*.db
+*.db-shm
+*.db-wal
+
+# ── Environment files ─────────────────────────────────────────────────────────
+.env
+.env.local
+.env.*.local
+
+# ── Claude Code local settings ────────────────────────────────────────────────
+.claude/settings.local.json
+
+# ── Editor & OS noise ─────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+Desktop.ini
+*.swp
+*.swo
+.vscode/
+.idea/
+
+# ── Logs ──────────────────────────────────────────────────────────────────────
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# ── Misc pnpm artifacts ───────────────────────────────────────────────────────
+.pnpm-approve-builds.json

.npmrc

@@ -0,0 +1 @@
+shamefully-hoist=true

Dockerfile

@@ -0,0 +1,88 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 1 — Build client
+# ─────────────────────────────────────────────────────────────────────────────
+FROM node:22-alpine AS client-builder
+
+WORKDIR /build
+
+# Install pnpm
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
+# Copy workspace manifests first for better layer caching
+COPY pnpm-workspace.yaml package.json pnpm-lock.yaml* ./
+COPY apps/client/package.json ./apps/client/
+COPY apps/server/package.json ./apps/server/
+COPY tsconfig.base.json ./
+
+# Install all workspace deps
+RUN pnpm install --frozen-lockfile
+
+# Copy client source and build
+COPY apps/client ./apps/client/
+RUN pnpm --filter client build
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 2 — Build server
+# ─────────────────────────────────────────────────────────────────────────────
+FROM node:22-alpine AS server-builder
+
+WORKDIR /build
+
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
+COPY pnpm-workspace.yaml package.json pnpm-lock.yaml* ./
+COPY apps/server/package.json ./apps/server/
+COPY apps/client/package.json ./apps/client/
+COPY tsconfig.base.json ./
+
+# Install only server production deps + rebuild native modules for target arch
+RUN pnpm install --frozen-lockfile
+
+COPY apps/server ./apps/server/
+RUN pnpm --filter server build
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 3 — Production runtime
+# ─────────────────────────────────────────────────────────────────────────────
+FROM node:22-alpine AS runtime
+
+# Install tini for proper PID 1 signal handling
+RUN apk add --no-cache tini su-exec
+
+WORKDIR /app
+
+# No native deps — runtime only needs node_modules for pure-JS packages (express, cors, etc.)
+# Copy them directly from the builder stage instead of re-installing
+COPY --from=server-builder /build/node_modules ./node_modules
+COPY --from=server-builder /build/apps/server/node_modules ./apps/server/node_modules 2>/dev/null || true
+
+# Copy compiled server output (includes dist/db/migrations/*.js compiled by tsc)
+COPY --from=server-builder /build/apps/server/dist ./apps/server/dist
+
+# Copy built client into the path the server expects
+COPY --from=client-builder /build/apps/client/dist ./apps/client/dist
+
+# ── Runtime configuration ─────────────────────────────────────────────────
+ENV NODE_ENV=production \
+    PORT=3001 \
+    DATA_DIR=/data \
+    PHOTOS_DIR=/photos \
+    PUID=99 \
+    PGID=100 \
+    TZ=UTC \
+    NODE_NO_WARNINGS=1
+
+# /data  — persistent: SQLite database
+# /photos — bind-mount: read-only user photo library
+VOLUME ["/data"]
+
+EXPOSE 3001
+
+# Entrypoint: fix ownership then drop to PUID/PGID
+COPY docker-entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+ENTRYPOINT ["/sbin/tini", "--", "/usr/local/bin/entrypoint.sh"]
+CMD ["node", "apps/server/dist/index.js"]

UNRAID.md

@@ -0,0 +1,325 @@
+# Unraid Install Guide — Family Planner
+
+Two installation methods are available: the **GUI** method using the Community Applications template, and the **CLI** method using the Unraid terminal. Both produce an identical container. Choose whichever you prefer.
+
+---
+
+## Prerequisites
+
+- Unraid 6.10 or later
+- Docker service enabled (Unraid Settings → Docker → Enable Docker: Yes)
+- The Family Planner image published to a container registry (e.g. `ghcr.io/your-username/family-planner:latest`)
+- At least one share for app data (e.g. `appdata`) — created automatically by Unraid if it does not exist
+
+---
+
+## Paths and Variables Reference
+
+Understand these before installing. Both methods use the same values.
+
+### Volume Mounts
+
+| Container path | Host path (default) | Access | Required | Purpose |
+|---|---|---|---|---|
+| `/data` | `/mnt/user/appdata/family-planner` | read/write | **Yes** | SQLite database, migrations state |
+| `/photos` | `/mnt/user/Photos` | read-only | No | Photo library for the slideshow screensaver |
+
+**`/data` must be writable.** This is where the database file (`family.db`) lives. If this volume is lost, all data is lost — back it up like any other appdata folder.
+
+**`/photos` is read-only.** The app scans this folder recursively for images (`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.avif`, `.bmp`). Point it at any existing share or subfolder on your array. You can also leave it unmapped and configure the path later inside the app under Settings → Photo Slideshow.
+
+### Port Mapping
+
+| Host port | Container port | Protocol | Purpose |
+|---|---|---|---|
+| `3001` (configurable) | `3001` | TCP | Web UI |
+
+Change the host port if `3001` is already in use on your server. The container port stays `3001`.
+
+### Environment Variables
+
+| Variable | Default | Required | Description |
+|---|---|---|---|
+| `TZ` | `America/New_York` | Recommended | Timezone for date/time display. Full list: [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |
+| `PUID` | `99` | No | UID the process runs as inside the container. Unraid's `nobody` = `99`. Run `id <username>` in the terminal to find yours. |
+| `PGID` | `100` | No | GID the process runs as. Unraid's `users` group = `100`. |
+| `PORT` | `3001` | No | Internal app port. Do not change unless you have a specific reason. |
+| `DATA_DIR` | `/data` | No | Internal path to the data directory. Do not change. |
+| `PHOTOS_DIR` | `/photos` | No | Internal path to the photos directory. Do not change. |
+| `NODE_NO_WARNINGS` | `1` | No | Suppresses the Node.js experimental SQLite warning. Do not change. |
+
+**Finding your PUID/PGID** — open the Unraid terminal and run:
+```bash
+id nobody
+# uid=99(nobody) gid=100(users)
+```
+If you want files written with your personal user's ownership instead:
+```bash
+id your-username
+# uid=1000(your-username) gid=100(users)
+```
+
+---
+
+## Method 1 — GUI (Community Applications Template)
+
+### Step 1 — Copy the template file
+
+Open the Unraid terminal (Tools → Terminal) and run:
+
+```bash
+cp /path/to/family-planner/unraid/family-planner.xml \
+   /boot/config/plugins/dockerMan/templates-user/family-planner.xml
+```
+
+If you cloned the repo directly onto your server, the path will be wherever you placed it. Alternatively, paste the XML file content manually into a new file at that location.
+
+### Step 2 — Open Docker and add the container
+
+1. In the Unraid web UI, go to the **Docker** tab
+2. Click **Add Container**
+3. At the top, click the **Template** dropdown and select **Family Planner** from the user templates section
+4. The form will pre-fill with all default values
+
+### Step 3 — Review and adjust each field
+
+Work through the form top to bottom:
+
+**Repository**
+```
+ghcr.io/your-username/family-planner:latest
+```
+Replace `your-username` with the actual GitHub username or registry path once the image is published.
+
+**Network Type**
+```
+Bridge
+```
+Leave as-is unless you have a specific reason to use host or a custom network.
+
+**Port Mappings**
+
+| Name | Container port | Host port |
+|---|---|---|
+| Web UI Port | `3001` | `3001` (change if needed) |
+
+**Path Mappings**
+
+| Name | Container path | Host path | Access |
+|---|---|---|---|
+| App Data | `/data` | `/mnt/user/appdata/family-planner` | Read/Write |
+| Photos Path | `/photos` | `/mnt/user/Photos` | Read Only |
+
+To change the photos path: click the field and type the full path to your photos share. Common examples:
+- `/mnt/user/Photos`
+- `/mnt/user/Media/Family Photos`
+- `/mnt/disk1/photos` (specific disk, bypasses cache)
+
+Leave the Photos Path blank or point it at an empty folder if you do not want the slideshow feature yet — you can configure it later in the app.
+
+**Variables**
+
+| Name | Value |
+|---|---|
+| TZ | Your timezone, e.g. `America/Chicago` |
+| PUID | `99` (or your personal UID) |
+| PGID | `100` |
+| PORT | `3001` (leave as-is) |
+
+### Step 4 — Apply
+
+Click **Apply** at the bottom of the form. Unraid will:
+1. Pull the image
+2. Create the container
+3. Start it automatically
+
+### Step 5 — Verify
+
+Click the container row to expand it, then click **WebUI** (or navigate to `http://YOUR-SERVER-IP:3001` in your browser). The Family Planner dashboard should load.
+
+To check container logs:
+1. Click the container icon (the colored square to the left of the container name)
+2. Select **Logs**
+3. You should see:
+   ```
+   [db] Running 1 pending migration(s)...
+   [db]  ✓ Applied: 001_initial
+   [db] Migrations complete.
+   Family Planner running on http://0.0.0.0:3001
+   ```
+
+---
+
+## Method 2 — CLI (Terminal Script)
+
+This method runs a shell script from the Unraid terminal. It pulls the image, creates the container, and verifies it started correctly — all in one step.
+
+### Step 1 — Open the Unraid terminal
+
+Tools → Terminal (or SSH into your server).
+
+### Step 2 — Run the installer
+
+**Option A — If you have the repo on the server:**
+```bash
+bash /path/to/family-planner/unraid/install.sh
+```
+
+**Option B — Override any defaults inline before running:**
+```bash
+HOST_PORT=3001 \
+DATA_PATH=/mnt/user/appdata/family-planner \
+PHOTOS_PATH=/mnt/user/Photos \
+PUID=99 \
+PGID=100 \
+TZ=America/New_York \
+bash /path/to/family-planner/unraid/install.sh
+```
+
+**Option C — Once the image is published, pull and run in one step:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/your-username/family-planner/main/unraid/install.sh | bash
+```
+Or with custom values:
+```bash
+HOST_PORT=8080 PHOTOS_PATH=/mnt/user/Media/Photos \
+  curl -fsSL https://raw.githubusercontent.com/your-username/family-planner/main/unraid/install.sh | bash
+```
+
+### Step 3 — Confirm the settings prompt
+
+The script will display a summary of the values it will use and ask for confirmation:
+```
+[INFO]  Family Planner — Unraid Installer
+
+  Container : family-planner
+  Image     : ghcr.io/your-username/family-planner:latest
+  Port      : 3001 → 3001
+  Data path : /mnt/user/appdata/family-planner
+  Photos    : /mnt/user/Photos  (read-only)
+  PUID/PGID : 99/100
+  TZ        : America/New_York
+
+Proceed with these settings? [Y/n]
+```
+Press **Enter** (or type `Y`) to proceed.
+
+### Step 4 — Wait for completion
+
+The script will:
+1. Stop and remove any existing container named `family-planner`
+2. Create the data directory if it does not exist
+3. Pull the latest image
+4. Start the container
+5. Wait up to 30 seconds for a successful health check
+
+On success you will see:
+```
+[OK]    Family Planner is up!
+[OK]    Installation complete.
+
+  Open in browser : http://192.168.1.X:3001
+  View logs       : docker logs -f family-planner
+  Stop            : docker stop family-planner
+```
+
+### Step 5 — Verify manually (optional)
+
+```bash
+# Check the container is running
+docker ps | grep family-planner
+
+# Tail live logs
+docker logs -f family-planner
+
+# Hit the API to confirm the app is responding
+curl -s http://localhost:3001/api/settings | python3 -m json.tool
+```
+
+---
+
+## Updating
+
+### GUI
+
+1. In the Docker tab, click the container icon and select **Check for Updates**
+2. If an update is available, click **Update** — Unraid will pull the new image and recreate the container preserving your volume mappings
+
+### CLI
+
+```bash
+# Pull the new image
+docker pull ghcr.io/your-username/family-planner:latest
+
+# Stop and remove the old container (data is safe — it lives in /data volume)
+docker stop family-planner
+docker rm family-planner
+
+# Re-run the install script with the same settings
+bash /path/to/family-planner/unraid/install.sh
+```
+
+Or as a one-liner:
+```bash
+docker pull ghcr.io/your-username/family-planner:latest \
+  && docker stop family-planner \
+  && docker rm family-planner \
+  && bash /path/to/family-planner/unraid/install.sh
+```
+
+> **Database migrations run automatically on startup.** When a new version adds schema changes, the migration runner applies them the first time the updated container starts. Your existing data is preserved.
+
+---
+
+## Backup
+
+The entire application state lives in one file:
+
+```
+/mnt/user/appdata/family-planner/family.db
+```
+
+Back this up with Unraid's built-in **Appdata Backup** plugin, or manually:
+
+```bash
+# One-time backup
+cp /mnt/user/appdata/family-planner/family.db \
+   /mnt/user/Backups/family-planner-$(date +%Y%m%d).db
+
+# Restore (stop the container first)
+docker stop family-planner
+cp /mnt/user/Backups/family-planner-20260101.db \
+   /mnt/user/appdata/family-planner/family.db
+docker start family-planner
+```
+
+---
+
+## Troubleshooting
+
+**Container exits immediately**
+```bash
+docker logs family-planner
+```
+Look for `[db] ✗ Failed:` — a migration failure aborts startup. This usually means the `/data` volume is not writable or the database file is corrupted.
+
+**Cannot access the web UI**
+- Confirm the container is running: `docker ps | grep family-planner`
+- Check the host port is not blocked by Unraid's firewall or already in use: `ss -tlnp | grep 3001`
+- Try accessing via the server's LAN IP directly: `http://192.168.1.X:3001`
+
+**Photos not showing in slideshow**
+- Verify the `/photos` volume is mapped and the path exists: `docker exec family-planner ls /photos`
+- Check the path in the app: Settings → Photo Slideshow → Photo Folder Path
+- Supported formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.avif`, `.bmp`
+
+**Wrong timezone / dates**
+- Set `TZ` to a valid tz database name, e.g. `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`
+- Full list: `docker exec family-planner cat /usr/share/zoneinfo/tzdata.zi | head -20` or see [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+- Recreate the container after changing `TZ` — it is read at startup
+
+**File permission errors in logs**
+- The entrypoint script sets ownership of `/data` to `PUID:PGID` on every start
+- If you see permission errors, check that `PUID`/`PGID` match the owner of your appdata share
+- Run `ls -la /mnt/user/appdata/family-planner` to see current ownership
+- Run `id nobody` and `id your-username` to compare UIDs

apps/client/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Family Planner</title>
+    <script>
+      // Prevent FOUC — apply dark class before React hydrates
+      try {
+        const s = JSON.parse(localStorage.getItem('fp-theme') || '{}');
+        if (s?.state?.mode === 'dark') document.documentElement.classList.add('dark');
+      } catch {}
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/client/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "client",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.28.4",
+    "axios": "^1.6.7",
+    "clsx": "^2.1.0",
+    "date-fns": "^3.3.1",
+    "framer-motion": "^11.0.14",
+    "lucide-react": "^0.359.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.22.3",
+    "zustand": "^4.5.2"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.66",
+    "@types/react-dom": "^18.2.22",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.18",
+    "postcss": "^8.4.37",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.2.0"
+  }
+}

apps/client/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

apps/client/src/App.tsx

@@ -0,0 +1,33 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { AppShell } from '@/components/layout/AppShell';
+import Dashboard from '@/pages/Dashboard';
+import CalendarPage from '@/pages/Calendar';
+import ShoppingPage from '@/pages/Shopping';
+import ChoresPage from '@/pages/Chores';
+import MealsPage from '@/pages/Meals';
+import BoardPage from '@/pages/Board';
+import CountdownsPage from '@/pages/Countdowns';
+import PhotosPage from '@/pages/Photos';
+import SettingsPage from '@/pages/Settings';
+import MembersPage from '@/pages/Members';
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <AppShell>
+        <Routes>
+          <Route path="/"                  element={<Dashboard />} />
+          <Route path="/calendar"          element={<CalendarPage />} />
+          <Route path="/shopping"          element={<ShoppingPage />} />
+          <Route path="/chores"            element={<ChoresPage />} />
+          <Route path="/meals"             element={<MealsPage />} />
+          <Route path="/board"             element={<BoardPage />} />
+          <Route path="/countdowns"        element={<CountdownsPage />} />
+          <Route path="/photos"            element={<PhotosPage />} />
+          <Route path="/settings"          element={<SettingsPage />} />
+          <Route path="/settings/members"  element={<MembersPage />} />
+        </Routes>
+      </AppShell>
+    </BrowserRouter>
+  );
+}

apps/client/src/components/layout/AppShell.tsx

@@ -0,0 +1,197 @@
+import { ReactNode, useState } from 'react';
+import { NavLink, useLocation } from 'react-router-dom';
+import { motion, AnimatePresence } from 'framer-motion';
+import { clsx } from 'clsx';
+import {
+  LayoutDashboard, Calendar, ShoppingCart, CheckSquare,
+  UtensilsCrossed, MessageSquare, Timer, Settings,
+  Image, Menu, X, ChevronRight,
+} from 'lucide-react';
+import { ThemeToggle } from '@/components/ui/ThemeToggle';
+
+interface NavItem {
+  to: string;
+  icon: ReactNode;
+  label: string;
+  end?: boolean;
+}
+
+const NAV_ITEMS: NavItem[] = [
+  { to: '/',          icon: <LayoutDashboard size={20} />, label: 'Dashboard',    end: true },
+  { to: '/calendar',  icon: <Calendar size={20} />,        label: 'Calendar'  },
+  { to: '/shopping',  icon: <ShoppingCart size={20} />,    label: 'Shopping'  },
+  { to: '/chores',    icon: <CheckSquare size={20} />,     label: 'Chores'    },
+  { to: '/meals',     icon: <UtensilsCrossed size={20} />, label: 'Meals'     },
+  { to: '/board',     icon: <MessageSquare size={20} />,   label: 'Board'     },
+  { to: '/countdowns',icon: <Timer size={20} />,           label: 'Countdowns'},
+  { to: '/photos',    icon: <Image size={20} />,           label: 'Photos'    },
+  { to: '/settings',  icon: <Settings size={20} />,        label: 'Settings'  },
+];
+
+function SidebarLink({ item, collapsed }: { item: NavItem; collapsed: boolean }) {
+  return (
+    <NavLink
+      to={item.to}
+      end={item.end}
+      className={({ isActive }) =>
+        clsx(
+          'group flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm font-medium',
+          'transition-all duration-150',
+          isActive
+            ? 'bg-accent text-white shadow-sm'
+            : 'text-secondary hover:bg-surface-raised hover:text-primary'
+        )
+      }
+    >
+      <span className="shrink-0">{item.icon}</span>
+      <AnimatePresence initial={false}>
+        {!collapsed && (
+          <motion.span
+            initial={{ opacity: 0, width: 0 }}
+            animate={{ opacity: 1, width: 'auto' }}
+            exit={{ opacity: 0, width: 0 }}
+            transition={{ duration: 0.15 }}
+            className="overflow-hidden whitespace-nowrap"
+          >
+            {item.label}
+          </motion.span>
+        )}
+      </AnimatePresence>
+    </NavLink>
+  );
+}
+
+interface AppShellProps {
+  children: ReactNode;
+}
+
+export function AppShell({ children }: AppShellProps) {
+  const [collapsed, setCollapsed] = useState(false);
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const location = useLocation();
+
+  // Close mobile menu on nav
+  // (handled via useEffect would add complexity; NavLink click is enough)
+
+  return (
+    <div className="flex h-screen overflow-hidden bg-app">
+      {/* ── Desktop Sidebar ──────────────────────────────────────────── */}
+      <motion.aside
+        animate={{ width: collapsed ? 68 : 240 }}
+        transition={{ duration: 0.2, ease: 'easeInOut' }}
+        className="hidden md:flex flex-col shrink-0 h-full bg-surface border-r border-theme overflow-hidden"
+      >
+        {/* Logo / Header */}
+        <div className="flex items-center gap-3 px-4 py-5 border-b border-theme">
+          <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-accent text-white font-bold text-sm">
+            FP
+          </span>
+          <AnimatePresence initial={false}>
+            {!collapsed && (
+              <motion.span
+                initial={{ opacity: 0, width: 0 }}
+                animate={{ opacity: 1, width: 'auto' }}
+                exit={{ opacity: 0, width: 0 }}
+                transition={{ duration: 0.15 }}
+                className="overflow-hidden whitespace-nowrap font-semibold text-primary text-base"
+              >
+                Family Planner
+              </motion.span>
+            )}
+          </AnimatePresence>
+        </div>
+
+        {/* Nav */}
+        <nav className="flex-1 overflow-y-auto p-3 flex flex-col gap-1">
+          {NAV_ITEMS.map((item) => (
+            <SidebarLink key={item.to} item={item} collapsed={collapsed} />
+          ))}
+        </nav>
+
+        {/* Bottom: theme + collapse */}
+        <div className="p-3 border-t border-theme flex flex-col gap-2">
+          {!collapsed && <ThemeToggle className="w-full justify-center" />}
+          <button
+            onClick={() => setCollapsed((c) => !c)}
+            className="flex items-center justify-center h-9 w-full rounded-xl text-secondary hover:bg-surface-raised hover:text-primary transition-colors"
+            aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+          >
+            <motion.span animate={{ rotate: collapsed ? 0 : 180 }} transition={{ duration: 0.2 }}>
+              <ChevronRight size={18} />
+            </motion.span>
+          </button>
+        </div>
+      </motion.aside>
+
+      {/* ── Mobile Overlay Drawer ────────────────────────────────────── */}
+      <AnimatePresence>
+        {mobileOpen && (
+          <>
+            <motion.div
+              className="fixed inset-0 z-40 bg-black/50 backdrop-blur-sm md:hidden"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              onClick={() => setMobileOpen(false)}
+            />
+            <motion.aside
+              className="fixed inset-y-0 left-0 z-50 w-64 bg-surface border-r border-theme flex flex-col md:hidden"
+              initial={{ x: -256 }}
+              animate={{ x: 0 }}
+              exit={{ x: -256 }}
+              transition={{ duration: 0.2, ease: 'easeInOut' }}
+            >
+              <div className="flex items-center justify-between px-4 py-5 border-b border-theme">
+                <span className="font-semibold text-primary text-base">Family Planner</span>
+                <button onClick={() => setMobileOpen(false)} className="p-1.5 rounded-lg text-secondary hover:bg-surface-raised">
+                  <X size={18} />
+                </button>
+              </div>
+              <nav className="flex-1 overflow-y-auto p-3 flex flex-col gap-1">
+                {NAV_ITEMS.map((item) => (
+                  <div key={item.to} onClick={() => setMobileOpen(false)}>
+                    <SidebarLink item={item} collapsed={false} />
+                  </div>
+                ))}
+              </nav>
+              <div className="p-3 border-t border-theme">
+                <ThemeToggle className="w-full justify-center" />
+              </div>
+            </motion.aside>
+          </>
+        )}
+      </AnimatePresence>
+
+      {/* ── Main Content ─────────────────────────────────────────────── */}
+      <div className="flex flex-col flex-1 min-w-0 overflow-hidden">
+        {/* Top bar (mobile only) */}
+        <header className="md:hidden flex items-center justify-between px-4 py-3 bg-surface border-b border-theme">
+          <button
+            onClick={() => setMobileOpen(true)}
+            className="p-2 rounded-lg text-secondary hover:bg-surface-raised"
+          >
+            <Menu size={20} />
+          </button>
+          <span className="font-semibold text-primary">Family Planner</span>
+          <ThemeToggle />
+        </header>
+
+        {/* Page content */}
+        <main className="flex-1 overflow-y-auto">
+          <AnimatePresence mode="wait">
+            <motion.div
+              key={location.pathname}
+              initial={{ opacity: 0, y: 6 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -6 }}
+              transition={{ duration: 0.18 }}
+              className="h-full"
+            >
+              {children}
+            </motion.div>
+          </AnimatePresence>
+        </main>
+      </div>
+    </div>
+  );
+}

apps/client/src/components/ui/Avatar.tsx

@@ -0,0 +1,37 @@
+import { clsx } from 'clsx';
+
+interface AvatarProps {
+  name: string;
+  color: string;
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  className?: string;
+}
+
+const sizeMap = {
+  xs: 'h-6 w-6 text-xs',
+  sm: 'h-8 w-8 text-sm',
+  md: 'h-10 w-10 text-base',
+  lg: 'h-12 w-12 text-lg',
+};
+
+export function Avatar({ name, color, size = 'md', className }: AvatarProps) {
+  const initials = name
+    .split(' ')
+    .map((w) => w[0])
+    .slice(0, 2)
+    .join('')
+    .toUpperCase();
+
+  return (
+    <span
+      className={clsx(
+        'inline-flex shrink-0 items-center justify-center rounded-full font-semibold text-white select-none',
+        sizeMap[size],
+        className
+      )}
+      style={{ backgroundColor: color }}
+    >
+      {initials}
+    </span>
+  );
+}

apps/client/src/components/ui/Badge.tsx

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { clsx } from 'clsx';
+
+interface BadgeProps {
+  children: ReactNode;
+  color?: string;
+  className?: string;
+}
+
+export function Badge({ children, color, className }: BadgeProps) {
+  return (
+    <span
+      className={clsx('inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium', className)}
+      style={color ? { backgroundColor: `${color}22`, color } : undefined}
+    >
+      {children}
+    </span>
+  );
+}

apps/client/src/components/ui/Button.tsx

@@ -0,0 +1,51 @@
+import { forwardRef, ButtonHTMLAttributes } from 'react';
+import { clsx } from 'clsx';
+
+type Variant = 'primary' | 'secondary' | 'ghost' | 'danger';
+type Size = 'sm' | 'md' | 'lg';
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: Variant;
+  size?: Size;
+  loading?: boolean;
+}
+
+const variantClasses: Record<Variant, string> = {
+  primary:   'bg-accent text-white hover:opacity-90 active:opacity-80 shadow-sm',
+  secondary: 'bg-surface-raised border border-theme text-primary hover:bg-accent-light hover:text-accent',
+  ghost:     'text-secondary hover:bg-surface-raised hover:text-primary',
+  danger:    'bg-red-500 text-white hover:bg-red-600 active:bg-red-700 shadow-sm',
+};
+
+const sizeClasses: Record<Size, string> = {
+  sm: 'px-3 py-1.5 text-sm gap-1.5',
+  md: 'px-4 py-2 text-sm gap-2',
+  lg: 'px-5 py-2.5 text-base gap-2',
+};
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ variant = 'primary', size = 'md', loading, className, children, disabled, ...props }, ref) => (
+    <button
+      ref={ref}
+      disabled={disabled || loading}
+      className={clsx(
+        'inline-flex items-center justify-center rounded-lg font-medium',
+        'transition-all duration-150 focus-visible:ring-2 ring-accent focus-visible:outline-none',
+        'disabled:opacity-50 disabled:cursor-not-allowed',
+        variantClasses[variant],
+        sizeClasses[size],
+        className
+      )}
+      {...props}
+    >
+      {loading && (
+        <svg className="animate-spin h-4 w-4 shrink-0" fill="none" viewBox="0 0 24 24">
+          <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+          <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8v8H4z" />
+        </svg>
+      )}
+      {children}
+    </button>
+  )
+);
+Button.displayName = 'Button';

apps/client/src/components/ui/Input.tsx

@@ -0,0 +1,38 @@
+import { forwardRef, InputHTMLAttributes } from 'react';
+import { clsx } from 'clsx';
+
+interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  label?: string;
+  error?: string;
+  hint?: string;
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ label, error, hint, className, id, ...props }, ref) => {
+    const inputId = id ?? label?.toLowerCase().replace(/\s+/g, '-');
+    return (
+      <div className="flex flex-col gap-1.5">
+        {label && (
+          <label htmlFor={inputId} className="text-sm font-medium text-secondary">
+            {label}
+          </label>
+        )}
+        <input
+          ref={ref}
+          id={inputId}
+          className={clsx(
+            'w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary',
+            'placeholder:text-muted focus:outline-none focus:ring-2 ring-accent focus:border-transparent',
+            'transition-colors duration-150',
+            error && 'border-red-400 focus:ring-red-400',
+            className
+          )}
+          {...props}
+        />
+        {hint && !error && <p className="text-xs text-muted">{hint}</p>}
+        {error && <p className="text-xs text-red-500">{error}</p>}
+      </div>
+    );
+  }
+);
+Input.displayName = 'Input';

apps/client/src/components/ui/Modal.tsx

@@ -0,0 +1,83 @@
+import { ReactNode, useEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { motion, AnimatePresence } from 'framer-motion';
+import { X } from 'lucide-react';
+import { clsx } from 'clsx';
+import { useThemeStore } from '@/store/themeStore';
+
+interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  title?: string;
+  children: ReactNode;
+  size?: 'sm' | 'md' | 'lg' | 'xl';
+  className?: string;
+}
+
+const sizeClasses = {
+  sm: 'max-w-sm',
+  md: 'max-w-md',
+  lg: 'max-w-lg',
+  xl: 'max-w-2xl',
+};
+
+export function Modal({ open, onClose, title, children, size = 'md', className }: ModalProps) {
+  // Ensure dark class is on root so modal portal inherits theme
+  const mode = useThemeStore((s) => s.mode);
+
+  useEffect(() => {
+    if (!open) return;
+    const handleKey = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose(); };
+    document.addEventListener('keydown', handleKey);
+    return () => document.removeEventListener('keydown', handleKey);
+  }, [open, onClose]);
+
+  useEffect(() => {
+    document.body.style.overflow = open ? 'hidden' : '';
+    return () => { document.body.style.overflow = ''; };
+  }, [open]);
+
+  return createPortal(
+    <AnimatePresence>
+      {open && (
+        <div className={clsx('fixed inset-0 z-50 flex items-center justify-center p-4', mode === 'dark' ? 'dark' : '')}>
+          {/* Backdrop */}
+          <motion.div
+            className="absolute inset-0 bg-black/50 backdrop-blur-sm"
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            onClick={onClose}
+          />
+          {/* Panel */}
+          <motion.div
+            className={clsx(
+              'relative w-full rounded-2xl shadow-2xl z-10',
+              'bg-surface border border-theme',
+              sizeClasses[size],
+              className
+            )}
+            initial={{ opacity: 0, scale: 0.95, y: 8 }}
+            animate={{ opacity: 1, scale: 1, y: 0 }}
+            exit={{ opacity: 0, scale: 0.95, y: 8 }}
+            transition={{ duration: 0.2, ease: 'easeOut' }}
+          >
+            {title && (
+              <div className="flex items-center justify-between px-6 pt-5 pb-4 border-b border-theme">
+                <h2 className="text-lg font-semibold text-primary">{title}</h2>
+                <button
+                  onClick={onClose}
+                  className="p-1.5 rounded-lg text-secondary hover:bg-surface-raised hover:text-primary transition-colors"
+                >
+                  <X size={18} />
+                </button>
+              </div>
+            )}
+            <div className="p-6">{children}</div>
+          </motion.div>
+        </div>
+      )}
+    </AnimatePresence>,
+    document.body
+  );
+}

apps/client/src/components/ui/Select.tsx

@@ -0,0 +1,40 @@
+import { forwardRef, SelectHTMLAttributes } from 'react';
+import { clsx } from 'clsx';
+
+interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+  label?: string;
+  error?: string;
+  hint?: string;
+}
+
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(
+  ({ label, error, hint, className, id, children, ...props }, ref) => {
+    const inputId = id ?? label?.toLowerCase().replace(/\s+/g, '-');
+    return (
+      <div className="flex flex-col gap-1.5">
+        {label && (
+          <label htmlFor={inputId} className="text-sm font-medium text-secondary">
+            {label}
+          </label>
+        )}
+        <select
+          ref={ref}
+          id={inputId}
+          className={clsx(
+            'w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary',
+            'focus:outline-none focus:ring-2 ring-accent focus:border-transparent',
+            'transition-colors duration-150 cursor-pointer',
+            error && 'border-red-400 focus:ring-red-400',
+            className
+          )}
+          {...props}
+        >
+          {children}
+        </select>
+        {hint && !error && <p className="text-xs text-muted">{hint}</p>}
+        {error && <p className="text-xs text-red-500">{error}</p>}
+      </div>
+    );
+  }
+);
+Select.displayName = 'Select';

apps/client/src/components/ui/Textarea.tsx

@@ -0,0 +1,39 @@
+import { forwardRef, TextareaHTMLAttributes } from 'react';
+import { clsx } from 'clsx';
+
+interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  label?: string;
+  error?: string;
+  hint?: string;
+}
+
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ label, error, hint, className, id, ...props }, ref) => {
+    const inputId = id ?? label?.toLowerCase().replace(/\s+/g, '-');
+    return (
+      <div className="flex flex-col gap-1.5">
+        {label && (
+          <label htmlFor={inputId} className="text-sm font-medium text-secondary">
+            {label}
+          </label>
+        )}
+        <textarea
+          ref={ref}
+          id={inputId}
+          rows={3}
+          className={clsx(
+            'w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary',
+            'placeholder:text-muted focus:outline-none focus:ring-2 ring-accent focus:border-transparent',
+            'transition-colors duration-150 resize-none',
+            error && 'border-red-400 focus:ring-red-400',
+            className
+          )}
+          {...props}
+        />
+        {hint && !error && <p className="text-xs text-muted">{hint}</p>}
+        {error && <p className="text-xs text-red-500">{error}</p>}
+      </div>
+    );
+  }
+);
+Textarea.displayName = 'Textarea';

apps/client/src/components/ui/ThemeToggle.tsx

@@ -0,0 +1,56 @@
+import { Sun, Moon } from 'lucide-react';
+import { motion } from 'framer-motion';
+import { useThemeStore } from '@/store/themeStore';
+import { clsx } from 'clsx';
+
+interface ThemeToggleProps {
+  className?: string;
+  showLabel?: boolean;
+}
+
+export function ThemeToggle({ className, showLabel }: ThemeToggleProps) {
+  const { mode, toggleMode } = useThemeStore();
+  const isDark = mode === 'dark';
+
+  return (
+    <button
+      onClick={toggleMode}
+      aria-label={isDark ? 'Switch to light mode' : 'Switch to dark mode'}
+      className={clsx(
+        'relative flex items-center gap-2 rounded-full px-1 py-1',
+        'bg-surface-raised border border-theme',
+        'hover:border-accent transition-colors duration-200',
+        className
+      )}
+    >
+      <span
+        className={clsx(
+          'flex h-7 w-7 items-center justify-center rounded-full transition-colors duration-200',
+          !isDark ? 'bg-accent text-white' : 'text-muted'
+        )}
+      >
+        <Sun size={14} />
+      </span>
+      <span
+        className={clsx(
+          'flex h-7 w-7 items-center justify-center rounded-full transition-colors duration-200',
+          isDark ? 'bg-accent text-white' : 'text-muted'
+        )}
+      >
+        <Moon size={14} />
+      </span>
+      {showLabel && (
+        <span className="pr-2 text-sm font-medium text-secondary">
+          {isDark ? 'Dark' : 'Light'}
+        </span>
+      )}
+      {/* Sliding indicator */}
+      <motion.span
+        className="absolute inset-y-1 w-9 rounded-full bg-accent/10 border border-accent/30 pointer-events-none"
+        animate={{ x: isDark ? 32 : 0 }}
+        transition={{ type: 'spring', stiffness: 400, damping: 30 }}
+        style={{ left: 4 }}
+      />
+    </button>
+  );
+}

apps/client/src/features/calendar/CalendarGrid.tsx

@@ -0,0 +1,109 @@
+import { useMemo } from 'react';
+import {
+  startOfMonth, endOfMonth, startOfWeek, endOfWeek,
+  eachDayOfInterval, isSameMonth, isToday, isSameDay, format,
+} from 'date-fns';
+import { motion } from 'framer-motion';
+import { clsx } from 'clsx';
+import type { CalendarEvent, Member } from '@/lib/api';
+
+const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+interface Props {
+  month: Date;
+  events: CalendarEvent[];
+  members: Member[];
+  onDayClick: (date: Date) => void;
+  onEventClick: (event: CalendarEvent) => void;
+}
+
+function eventColor(event: CalendarEvent, members: Member[]): string {
+  if (event.color) return event.color;
+  if (event.member_id) {
+    return members.find((m) => m.id === event.member_id)?.color ?? '#6366f1';
+  }
+  return '#6366f1';
+}
+
+export function CalendarGrid({ month, events, members, onDayClick, onEventClick }: Props) {
+  const days = useMemo(() => {
+    const start = startOfWeek(startOfMonth(month));
+    const end   = endOfWeek(endOfMonth(month));
+    return eachDayOfInterval({ start, end });
+  }, [month]);
+
+  function dayEvents(day: Date) {
+    return events.filter((e) => {
+      const start = new Date(e.start_at);
+      const end   = new Date(e.end_at);
+      // All-day or events that touch this day
+      return isSameDay(start, day) || (start <= day && end >= day);
+    });
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Weekday headers */}
+      <div className="grid grid-cols-7 border-b border-theme">
+        {WEEKDAYS.map((d) => (
+          <div key={d} className="py-2 text-center text-xs font-semibold text-muted uppercase tracking-wide">
+            {d}
+          </div>
+        ))}
+      </div>
+
+      {/* Day grid */}
+      <div className="grid grid-cols-7 flex-1" style={{ gridTemplateRows: `repeat(${days.length / 7}, 1fr)` }}>
+        {days.map((day, i) => {
+          const de = dayEvents(day);
+          const inMonth = isSameMonth(day, month);
+          const today = isToday(day);
+
+          return (
+            <motion.div
+              key={i}
+              whileHover={{ backgroundColor: 'var(--color-surface-raised)' }}
+              onClick={() => onDayClick(day)}
+              className={clsx(
+                'relative min-h-[80px] border-b border-r border-theme p-1.5 cursor-pointer',
+                'transition-colors duration-100',
+                !inMonth && 'opacity-40',
+              )}
+            >
+              {/* Date number */}
+              <div className="flex justify-end mb-1">
+                <span
+                  className={clsx(
+                    'h-6 w-6 flex items-center justify-center rounded-full text-xs font-semibold',
+                    today
+                      ? 'bg-accent text-white'
+                      : 'text-primary hover:bg-surface-raised'
+                  )}
+                >
+                  {format(day, 'd')}
+                </span>
+              </div>
+
+              {/* Event chips */}
+              <div className="flex flex-col gap-0.5">
+                {de.slice(0, 3).map((ev) => (
+                  <button
+                    key={ev.id}
+                    onClick={(e) => { e.stopPropagation(); onEventClick(ev); }}
+                    className="w-full text-left px-1.5 py-0.5 rounded text-xs font-medium text-white truncate leading-5"
+                    style={{ backgroundColor: eventColor(ev, members) }}
+                  >
+                    {ev.all_day ? '' : `${format(new Date(ev.start_at), 'h:mm')} `}{ev.title}
+                  </button>
+                ))}
+                {de.length > 3 && (
+                  <span className="text-xs text-muted px-1">+{de.length - 3} more</span>
+                )}
+              </div>
+            </motion.div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

apps/client/src/features/calendar/DayEventsModal.tsx

@@ -0,0 +1,87 @@
+import { format } from 'date-fns';
+import { Plus, Clock, RefreshCw } from 'lucide-react';
+import { Modal } from '@/components/ui/Modal';
+import { Button } from '@/components/ui/Button';
+import type { CalendarEvent, Member } from '@/lib/api';
+
+interface Props {
+  open: boolean;
+  onClose: () => void;
+  date: Date | null;
+  events: CalendarEvent[];
+  members: Member[];
+  onAdd: () => void;
+  onEdit: (event: CalendarEvent) => void;
+}
+
+function eventColor(event: CalendarEvent, members: Member[]): string {
+  if (event.color) return event.color;
+  if (event.member_id) {
+    return members.find((m) => m.id === event.member_id)?.color ?? '#6366f1';
+  }
+  return '#6366f1';
+}
+
+export function DayEventsModal({ open, onClose, date, events, members, onAdd, onEdit }: Props) {
+  if (!date) return null;
+
+  return (
+    <Modal
+      open={open}
+      onClose={onClose}
+      title={format(date, 'EEEE, MMMM d, yyyy')}
+      size="md"
+    >
+      <div className="space-y-3">
+        {events.length === 0 ? (
+          <p className="text-secondary text-sm text-center py-4">No events this day.</p>
+        ) : (
+          events.map((ev) => {
+            const color = eventColor(ev, members);
+            const member = members.find((m) => m.id === ev.member_id);
+            return (
+              <button
+                key={ev.id}
+                onClick={() => { onClose(); onEdit(ev); }}
+                className="w-full text-left flex items-start gap-3 p-3 rounded-xl border border-theme hover:border-accent/40 hover:bg-surface-raised transition-colors group"
+              >
+                <span className="mt-1 h-3 w-3 rounded-full shrink-0" style={{ backgroundColor: color }} />
+                <div className="flex-1 min-w-0">
+                  <p className="font-medium text-primary text-sm truncate">{ev.title}</p>
+                  <div className="flex items-center gap-3 mt-0.5">
+                    {!ev.all_day && (
+                      <span className="flex items-center gap-1 text-xs text-muted">
+                        <Clock size={11} />
+                        {format(new Date(ev.start_at), 'h:mm a')} – {format(new Date(ev.end_at), 'h:mm a')}
+                      </span>
+                    )}
+                    {ev.all_day && <span className="text-xs text-muted">All day</span>}
+                    {ev.recurrence && ev.recurrence !== 'none' && (
+                      <span className="flex items-center gap-1 text-xs text-muted capitalize">
+                        <RefreshCw size={10} /> {ev.recurrence}
+                      </span>
+                    )}
+                    {member && (
+                      <span className="text-xs font-medium" style={{ color: member.color }}>
+                        {member.name}
+                      </span>
+                    )}
+                  </div>
+                  {ev.description && (
+                    <p className="text-xs text-muted mt-1 truncate">{ev.description}</p>
+                  )}
+                </div>
+              </button>
+            );
+          })
+        )}
+
+        <div className="pt-2 border-t border-theme">
+          <Button onClick={() => { onClose(); onAdd(); }} className="w-full">
+            <Plus size={16} /> Add Event for {format(date, 'MMM d')}
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}

apps/client/src/features/calendar/EventModal.tsx

@@ -0,0 +1,241 @@
+import { useState, useEffect } from 'react';
+import { format } from 'date-fns';
+import { Trash2 } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { api, type CalendarEvent } from '@/lib/api';
+import { useMembers } from '@/hooks/useMembers';
+import { Modal } from '@/components/ui/Modal';
+import { Input } from '@/components/ui/Input';
+import { Textarea } from '@/components/ui/Textarea';
+import { Select } from '@/components/ui/Select';
+import { Button } from '@/components/ui/Button';
+
+interface Props {
+  open: boolean;
+  onClose: () => void;
+  event?: CalendarEvent | null;
+  defaultDate?: Date;
+}
+
+function toDateTimeLocal(iso: string) {
+  return iso ? iso.slice(0, 16) : '';
+}
+
+function toISO(local: string) {
+  return local ? new Date(local).toISOString() : '';
+}
+
+const RECURRENCE_OPTIONS = [
+  { value: 'none',    label: 'Does not repeat' },
+  { value: 'daily',   label: 'Daily' },
+  { value: 'weekly',  label: 'Weekly' },
+  { value: 'monthly', label: 'Monthly' },
+  { value: 'yearly',  label: 'Yearly' },
+];
+
+export function EventModal({ open, onClose, event, defaultDate }: Props) {
+  const qc = useQueryClient();
+  const { data: members = [] } = useMembers();
+  const isEdit = !!event;
+
+  const blank = () => {
+    const d = defaultDate ?? new Date();
+    const start = new Date(d);
+    start.setHours(9, 0, 0, 0);
+    const end = new Date(d);
+    end.setHours(10, 0, 0, 0);
+    return {
+      title: '', description: '', all_day: false, recurrence: 'none',
+      member_id: '', color: '',
+      start_at: format(start, "yyyy-MM-dd'T'HH:mm"),
+      end_at: format(end,   "yyyy-MM-dd'T'HH:mm"),
+    };
+  };
+
+  const [form, setForm] = useState(blank);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    if (!open) return;
+    if (event) {
+      setForm({
+        title:       event.title,
+        description: event.description ?? '',
+        all_day:     !!event.all_day,
+        recurrence:  event.recurrence ?? 'none',
+        member_id:   event.member_id ? String(event.member_id) : '',
+        color:       event.color ?? '',
+        start_at:    toDateTimeLocal(event.start_at),
+        end_at:      toDateTimeLocal(event.end_at),
+      });
+    } else {
+      setForm(blank());
+    }
+    setError('');
+  }, [open, event]);
+
+  const set = (k: keyof typeof form, v: string | boolean) =>
+    setForm((f) => ({ ...f, [k]: v }));
+
+  const saveMutation = useMutation({
+    mutationFn: (body: object) =>
+      isEdit
+        ? api.put(`/events/${event!.id}`, body).then((r) => r.data)
+        : api.post('/events', body).then((r) => r.data),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['events'] }); onClose(); },
+    onError: () => setError('Failed to save event. Please try again.'),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: () => api.delete(`/events/${event!.id}`),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['events'] }); onClose(); },
+  });
+
+  const handleSubmit = () => {
+    if (!form.title.trim()) { setError('Title is required'); return; }
+    if (!form.start_at || !form.end_at) { setError('Start and end times are required'); return; }
+    saveMutation.mutate({
+      title:       form.title.trim(),
+      description: form.description || null,
+      start_at:    toISO(form.start_at),
+      end_at:      toISO(form.end_at),
+      all_day:     form.all_day,
+      recurrence:  form.recurrence === 'none' ? null : form.recurrence,
+      member_id:   form.member_id ? Number(form.member_id) : null,
+      color:       form.color || null,
+    });
+  };
+
+  // Derive chip color: use selected member's color, or user-picked color, or accent
+  const chipColor = (() => {
+    if (form.color) return form.color;
+    if (form.member_id) return members.find((m) => m.id === Number(form.member_id))?.color ?? '';
+    return '';
+  })();
+
+  return (
+    <Modal open={open} onClose={onClose} title={isEdit ? 'Edit Event' : 'New Event'} size="lg">
+      <div className="space-y-4">
+        <Input
+          label="Title"
+          value={form.title}
+          onChange={(e) => set('title', e.target.value)}
+          placeholder="Event title"
+          autoFocus
+        />
+
+        <div className="grid grid-cols-2 gap-4">
+          <div>
+            <label className="text-sm font-medium text-secondary block mb-1.5">Start</label>
+            <input
+              type={form.all_day ? 'date' : 'datetime-local'}
+              value={form.all_day ? form.start_at.slice(0, 10) : form.start_at}
+              onChange={(e) => set('start_at', e.target.value)}
+              className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent transition-colors"
+            />
+          </div>
+          <div>
+            <label className="text-sm font-medium text-secondary block mb-1.5">End</label>
+            <input
+              type={form.all_day ? 'date' : 'datetime-local'}
+              value={form.all_day ? form.end_at.slice(0, 10) : form.end_at}
+              onChange={(e) => set('end_at', e.target.value)}
+              className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent transition-colors"
+            />
+          </div>
+        </div>
+
+        <label className="flex items-center gap-3 cursor-pointer select-none">
+          <div
+            onClick={() => set('all_day', !form.all_day)}
+            className={`relative h-5 w-9 rounded-full transition-colors duration-200 ${form.all_day ? 'bg-accent' : 'bg-border'}`}
+          >
+            <span className={`absolute top-0.5 h-4 w-4 rounded-full bg-white shadow transition-all duration-200 ${form.all_day ? 'left-[18px]' : 'left-0.5'}`} />
+          </div>
+          <span className="text-sm font-medium text-secondary">All day</span>
+        </label>
+
+        <div className="grid grid-cols-2 gap-4">
+          <Select
+            label="Family Member"
+            value={form.member_id}
+            onChange={(e) => set('member_id', e.target.value)}
+          >
+            <option value="">No one assigned</option>
+            {members.map((m) => (
+              <option key={m.id} value={m.id}>{m.name}</option>
+            ))}
+          </Select>
+          <Select
+            label="Repeats"
+            value={form.recurrence}
+            onChange={(e) => set('recurrence', e.target.value)}
+          >
+            {RECURRENCE_OPTIONS.map((o) => (
+              <option key={o.value} value={o.value}>{o.label}</option>
+            ))}
+          </Select>
+        </div>
+
+        <Textarea
+          label="Description"
+          value={form.description}
+          onChange={(e) => set('description', e.target.value)}
+          placeholder="Optional notes…"
+          rows={2}
+        />
+
+        <div>
+          <label className="text-sm font-medium text-secondary block mb-1.5">
+            Event Color <span className="text-muted font-normal">(overrides member color)</span>
+          </label>
+          <div className="flex items-center gap-3">
+            <input
+              type="color"
+              value={chipColor || '#6366f1'}
+              onChange={(e) => set('color', e.target.value)}
+              className="h-9 w-12 cursor-pointer rounded-lg border border-theme bg-transparent"
+            />
+            {chipColor && (
+              <span
+                className="px-3 py-1 rounded-full text-xs font-medium text-white"
+                style={{ backgroundColor: chipColor }}
+              >
+                Preview
+              </span>
+            )}
+            {form.color && (
+              <button
+                className="text-xs text-muted hover:text-secondary"
+                onClick={() => set('color', '')}
+              >
+                Clear override
+              </button>
+            )}
+          </div>
+        </div>
+
+        {error && <p className="text-sm text-red-500">{error}</p>}
+
+        <div className="flex items-center gap-2 pt-1">
+          {isEdit && (
+            <Button
+              variant="ghost"
+              onClick={() => deleteMutation.mutate()}
+              loading={deleteMutation.isPending}
+              className="text-red-500 hover:bg-red-50 dark:hover:bg-red-950"
+            >
+              <Trash2 size={16} />
+            </Button>
+          )}
+          <div className="flex gap-2 ml-auto">
+            <Button variant="secondary" onClick={onClose}>Cancel</Button>
+            <Button onClick={handleSubmit} loading={saveMutation.isPending}>
+              {isEdit ? 'Save Changes' : 'Add Event'}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </Modal>
+  );
+}

apps/client/src/features/chores/ChoreCard.tsx

@@ -0,0 +1,125 @@
+import { useState } from 'react';
+import { motion } from 'framer-motion';
+import { CheckCircle2, Circle, Pencil, RefreshCw, Calendar, Trophy } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { format, isPast, isToday } from 'date-fns';
+import { clsx } from 'clsx';
+import { api, type Chore } from '@/lib/api';
+import { Avatar } from '@/components/ui/Avatar';
+
+interface Props {
+  chore: Chore;
+  onEdit: (chore: Chore) => void;
+}
+
+const STATUS_STYLES: Record<string, string> = {
+  pending:     'bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400',
+  'in-progress':'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400',
+  done:        'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400',
+};
+
+export function ChoreCard({ chore, onEdit }: Props) {
+  const qc = useQueryClient();
+  const [completing, setCompleting] = useState(false);
+  const isDone = chore.status === 'done';
+
+  const completeMutation = useMutation({
+    mutationFn: () => api.post(`/chores/${chore.id}/complete`, { member_id: chore.member_id }),
+    onMutate: () => setCompleting(true),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['chores'] }); },
+    onSettled: () => setCompleting(false),
+  });
+
+  const resetMutation = useMutation({
+    mutationFn: () => api.put(`/chores/${chore.id}`, { status: 'pending' }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['chores'] }),
+  });
+
+  const dueDateOverdue = chore.due_date && !isDone && isPast(new Date(chore.due_date)) && !isToday(new Date(chore.due_date));
+
+  return (
+    <motion.div
+      layout
+      initial={{ opacity: 0, y: 6 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, scale: 0.97 }}
+      className={clsx(
+        'group flex items-start gap-4 p-4 rounded-2xl bg-surface border transition-colors duration-150',
+        isDone ? 'border-theme opacity-60' : 'border-theme hover:border-accent/40',
+      )}
+      style={chore.member_color ? { borderLeftColor: chore.member_color, borderLeftWidth: 3 } : {}}
+    >
+      {/* Complete button */}
+      <button
+        onClick={() => isDone ? resetMutation.mutate() : completeMutation.mutate()}
+        disabled={completing}
+        className="mt-0.5 shrink-0 transition-transform duration-150 hover:scale-110"
+        aria-label={isDone ? 'Mark as pending' : 'Mark as done'}
+      >
+        {isDone ? (
+          <CheckCircle2 size={22} className="text-green-500" />
+        ) : (
+          <Circle size={22} className="text-muted hover:text-accent transition-colors" />
+        )}
+      </button>
+
+      {/* Content */}
+      <div className="flex-1 min-w-0">
+        <div className="flex items-start justify-between gap-2">
+          <p className={clsx(
+            'font-semibold text-primary leading-snug',
+            isDone && 'line-through text-muted'
+          )}>
+            {chore.title}
+          </p>
+          <button
+            onClick={() => onEdit(chore)}
+            className="shrink-0 p-1.5 rounded-lg opacity-0 group-hover:opacity-100 text-secondary hover:bg-surface-raised hover:text-accent transition-all"
+          >
+            <Pencil size={14} />
+          </button>
+        </div>
+
+        {chore.description && (
+          <p className="text-sm text-secondary mt-0.5 line-clamp-1">{chore.description}</p>
+        )}
+
+        <div className="flex flex-wrap items-center gap-2 mt-2">
+          {/* Status badge */}
+          <span className={clsx('px-2 py-0.5 rounded-full text-xs font-medium capitalize', STATUS_STYLES[chore.status] ?? STATUS_STYLES.pending)}>
+            {chore.status}
+          </span>
+
+          {/* Recurrence */}
+          {chore.recurrence !== 'none' && (
+            <span className="flex items-center gap-1 text-xs text-muted">
+              <RefreshCw size={11} /> {chore.recurrence}
+            </span>
+          )}
+
+          {/* Due date */}
+          {chore.due_date && (
+            <span className={clsx('flex items-center gap-1 text-xs', dueDateOverdue ? 'text-red-500 font-medium' : 'text-muted')}>
+              <Calendar size={11} />
+              {isToday(new Date(chore.due_date)) ? 'Today' : format(new Date(chore.due_date), 'MMM d')}
+            </span>
+          )}
+
+          {/* Completion streak */}
+          {chore.completion_count > 0 && (
+            <span className="flex items-center gap-1 text-xs text-muted">
+              <Trophy size={11} className="text-amber-500" /> {chore.completion_count}×
+            </span>
+          )}
+        </div>
+      </div>
+
+      {/* Member avatar */}
+      {chore.member_name && chore.member_color && (
+        <div className="shrink-0">
+          <Avatar name={chore.member_name} color={chore.member_color} size="sm" />
+        </div>
+      )}
+    </motion.div>
+  );
+}

apps/client/src/features/chores/ChoreModal.tsx

@@ -0,0 +1,146 @@
+import { useState, useEffect } from 'react';
+import { Trash2 } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { api, type Chore } from '@/lib/api';
+import { useMembers } from '@/hooks/useMembers';
+import { Modal } from '@/components/ui/Modal';
+import { Input } from '@/components/ui/Input';
+import { Textarea } from '@/components/ui/Textarea';
+import { Select } from '@/components/ui/Select';
+import { Button } from '@/components/ui/Button';
+
+const RECURRENCE = [
+  { value: 'none',    label: 'One-time' },
+  { value: 'daily',   label: 'Daily' },
+  { value: 'weekly',  label: 'Weekly' },
+  { value: 'monthly', label: 'Monthly' },
+];
+
+interface Props {
+  open: boolean;
+  onClose: () => void;
+  chore?: Chore | null;
+}
+
+export function ChoreModal({ open, onClose, chore }: Props) {
+  const qc = useQueryClient();
+  const { data: members = [] } = useMembers();
+  const isEdit = !!chore;
+
+  const blank = () => ({ title: '', description: '', member_id: '', recurrence: 'none', due_date: '' });
+  const [form, setForm] = useState(blank);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    if (!open) return;
+    if (chore) {
+      setForm({
+        title:       chore.title,
+        description: chore.description ?? '',
+        member_id:   chore.member_id ? String(chore.member_id) : '',
+        recurrence:  chore.recurrence,
+        due_date:    chore.due_date ?? '',
+      });
+    } else {
+      setForm(blank());
+    }
+    setError('');
+  }, [open, chore]);
+
+  const set = (k: keyof typeof form, v: string) => setForm((f) => ({ ...f, [k]: v }));
+
+  const saveMutation = useMutation({
+    mutationFn: (body: object) =>
+      isEdit
+        ? api.put(`/chores/${chore!.id}`, body).then((r) => r.data)
+        : api.post('/chores', body).then((r) => r.data),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['chores'] }); onClose(); },
+    onError: () => setError('Failed to save. Please try again.'),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: () => api.delete(`/chores/${chore!.id}`),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['chores'] }); onClose(); },
+  });
+
+  const handleSubmit = () => {
+    if (!form.title.trim()) { setError('Title is required'); return; }
+    saveMutation.mutate({
+      title:       form.title.trim(),
+      description: form.description || null,
+      member_id:   form.member_id ? Number(form.member_id) : null,
+      recurrence:  form.recurrence,
+      due_date:    form.due_date || null,
+    });
+  };
+
+  return (
+    <Modal open={open} onClose={onClose} title={isEdit ? 'Edit Chore' : 'New Chore'}>
+      <div className="space-y-4">
+        <Input
+          label="Title"
+          value={form.title}
+          onChange={(e) => set('title', e.target.value)}
+          placeholder="What needs to be done?"
+          autoFocus
+        />
+        <div className="grid grid-cols-2 gap-4">
+          <Select
+            label="Assigned To"
+            value={form.member_id}
+            onChange={(e) => set('member_id', e.target.value)}
+          >
+            <option value="">Unassigned</option>
+            {members.map((m) => (
+              <option key={m.id} value={m.id}>{m.name}</option>
+            ))}
+          </Select>
+          <Select
+            label="Repeats"
+            value={form.recurrence}
+            onChange={(e) => set('recurrence', e.target.value)}
+          >
+            {RECURRENCE.map((r) => (
+              <option key={r.value} value={r.value}>{r.label}</option>
+            ))}
+          </Select>
+        </div>
+        <div>
+          <label className="text-sm font-medium text-secondary block mb-1.5">Due Date</label>
+          <input
+            type="date"
+            value={form.due_date}
+            onChange={(e) => set('due_date', e.target.value)}
+            className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent transition-colors"
+          />
+        </div>
+        <Textarea
+          label="Notes"
+          value={form.description}
+          onChange={(e) => set('description', e.target.value)}
+          placeholder="Optional details…"
+          rows={2}
+        />
+        {error && <p className="text-sm text-red-500">{error}</p>}
+        <div className="flex items-center gap-2 pt-1">
+          {isEdit && (
+            <Button
+              variant="ghost"
+              onClick={() => deleteMutation.mutate()}
+              loading={deleteMutation.isPending}
+              className="text-red-500 hover:bg-red-50 dark:hover:bg-red-950"
+            >
+              <Trash2 size={16} />
+            </Button>
+          )}
+          <div className="flex gap-2 ml-auto">
+            <Button variant="secondary" onClick={onClose}>Cancel</Button>
+            <Button onClick={handleSubmit} loading={saveMutation.isPending}>
+              {isEdit ? 'Save Changes' : 'Add Chore'}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </Modal>
+  );
+}

apps/client/src/features/shopping/ShoppingItemRow.tsx

@@ -0,0 +1,152 @@
+import { useState } from 'react';
+import { motion } from 'framer-motion';
+import { Trash2, UserCircle } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { clsx } from 'clsx';
+import { api, type ShoppingItem, type Member } from '@/lib/api';
+import { Avatar } from '@/components/ui/Avatar';
+
+interface Props {
+  item: ShoppingItem;
+  members: Member[];
+  listId: number;
+}
+
+export function ShoppingItemRow({ item, members, listId }: Props) {
+  const qc = useQueryClient();
+  const [showAssign, setShowAssign] = useState(false);
+
+  const toggleMutation = useMutation({
+    mutationFn: () => api.patch(`/shopping/items/${item.id}`, { checked: !item.checked }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['shopping-items', listId] }),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: () => api.delete(`/shopping/items/${item.id}`),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['shopping-items', listId] }),
+  });
+
+  const assignMutation = useMutation({
+    mutationFn: (member_id: number | null) =>
+      api.patch(`/shopping/items/${item.id}`, { member_id }),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['shopping-items', listId] });
+      setShowAssign(false);
+    },
+  });
+
+  const assignedMember = members.find((m) => m.id === item.member_id);
+  const isChecked = !!item.checked;
+
+  return (
+    <motion.li
+      layout
+      initial={{ opacity: 0, height: 0 }}
+      animate={{ opacity: 1, height: 'auto' }}
+      exit={{ opacity: 0, height: 0 }}
+      transition={{ duration: 0.18 }}
+      className="overflow-hidden"
+    >
+      <div className={clsx(
+        'group flex items-center gap-3 px-4 py-3 border-b border-theme last:border-b-0',
+        'hover:bg-surface-raised transition-colors duration-100',
+      )}>
+        {/* Checkbox */}
+        <button
+          onClick={() => toggleMutation.mutate()}
+          className="shrink-0 h-5 w-5 rounded border-2 flex items-center justify-center transition-all duration-200"
+          style={{
+            borderColor:     isChecked ? 'var(--color-accent)' : 'var(--color-border)',
+            backgroundColor: isChecked ? 'var(--color-accent)' : 'transparent',
+          }}
+          aria-label={isChecked ? 'Uncheck' : 'Check'}
+        >
+          {isChecked && (
+            <motion.svg
+              initial={{ scale: 0 }}
+              animate={{ scale: 1 }}
+              className="h-3 w-3 text-white"
+              fill="none"
+              viewBox="0 0 12 10"
+            >
+              <path d="M1 5l3.5 3.5L11 1" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+            </motion.svg>
+          )}
+        </button>
+
+        {/* Name + quantity */}
+        <div className="flex-1 min-w-0">
+          <span className={clsx(
+            'text-sm transition-all duration-300',
+            isChecked ? 'line-through text-muted' : 'text-primary font-medium'
+          )}>
+            {item.name}
+          </span>
+          {item.quantity && (
+            <span className="ml-2 text-xs text-muted">{item.quantity}</span>
+          )}
+        </div>
+
+        {/* Assign button */}
+        <div className="relative">
+          <button
+            onClick={() => setShowAssign((s) => !s)}
+            className={clsx(
+              'p-1 rounded-lg transition-colors',
+              assignedMember
+                ? 'opacity-100'
+                : 'opacity-0 group-hover:opacity-100 text-muted hover:text-secondary'
+            )}
+            aria-label="Assign to member"
+          >
+            {assignedMember ? (
+              <Avatar name={assignedMember.name} color={assignedMember.color} size="xs" />
+            ) : (
+              <UserCircle size={16} />
+            )}
+          </button>
+
+          {showAssign && (
+            <motion.div
+              initial={{ opacity: 0, scale: 0.9, y: -4 }}
+              animate={{ opacity: 1, scale: 1, y: 0 }}
+              className="absolute right-0 top-8 z-20 bg-surface border border-theme rounded-xl shadow-xl p-1.5 min-w-[140px]"
+            >
+              <button
+                onClick={() => assignMutation.mutate(null)}
+                className="w-full flex items-center gap-2 px-2 py-1.5 rounded-lg text-xs text-secondary hover:bg-surface-raised hover:text-primary transition-colors"
+              >
+                <UserCircle size={14} /> Unassign
+              </button>
+              {members.map((m) => (
+                <button
+                  key={m.id}
+                  onClick={() => assignMutation.mutate(m.id)}
+                  className="w-full flex items-center gap-2 px-2 py-1.5 rounded-lg text-xs hover:bg-surface-raised transition-colors"
+                >
+                  <Avatar name={m.name} color={m.color} size="xs" />
+                  <span className="text-primary">{m.name}</span>
+                  {item.member_id === m.id && <span className="ml-auto text-accent text-xs">✓</span>}
+                </button>
+              ))}
+            </motion.div>
+          )}
+        </div>
+
+        {/* Delete */}
+        <button
+          onClick={() => deleteMutation.mutate()}
+          className="shrink-0 p-1 rounded-lg opacity-0 group-hover:opacity-100 text-muted hover:text-red-500 transition-all"
+          aria-label="Delete item"
+        >
+          <Trash2 size={15} />
+        </button>
+      </div>
+
+      {/* Backdrop to close assign menu */}
+      {showAssign && (
+        <div className="fixed inset-0 z-10" onClick={() => setShowAssign(false)} />
+      )}
+    </motion.li>
+  );
+}

apps/client/src/hooks/useMembers.ts

@@ -0,0 +1,16 @@
+import { useQuery } from '@tanstack/react-query';
+import { api, type Member } from '@/lib/api';
+
+export function useMembers() {
+  return useQuery<Member[]>({
+    queryKey: ['members'],
+    queryFn: () => api.get('/members').then((r) => r.data),
+    staleTime: 60_000,
+  });
+}
+
+/** Returns a lookup map of id → member for O(1) access */
+export function useMembersMap() {
+  const { data = [] } = useMembers();
+  return Object.fromEntries(data.map((m) => [m.id, m])) as Record<number, Member>;
+}

apps/client/src/index.css

@@ -0,0 +1,65 @@
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap');
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ─── Base token defaults (light) — overridden by JS applyTheme() ──── */
+:root {
+  --color-bg:             #f8fafc;
+  --color-surface:        #ffffff;
+  --color-surface-raised: #f1f5f9;
+  --color-border:         #e2e8f0;
+  --color-text-primary:   #0f172a;
+  --color-text-secondary: #475569;
+  --color-text-muted:     #94a3b8;
+  --color-accent:         #6366f1;
+  --color-accent-light:   #e0e7ff;
+}
+
+/* ─── Smooth theme transitions on every surface ───────────────────── */
+*, *::before, *::after {
+  transition-property: background-color, color, border-color;
+  transition-duration: 200ms;
+  transition-timing-function: ease;
+}
+
+/* But NOT on animations / transforms */
+[data-no-transition], [data-no-transition] * {
+  transition: none !important;
+}
+
+/* ─── Base body ───────────────────────────────────────────────────── */
+body {
+  background-color: var(--color-bg);
+  color: var(--color-text-primary);
+  font-family: 'Inter', system-ui, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* ─── Scrollbar styling ────────────────────────────────────────────── */
+::-webkit-scrollbar { width: 6px; height: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--color-border); border-radius: 3px; }
+::-webkit-scrollbar-thumb:hover { background: var(--color-text-muted); }
+
+/* ─── Focus ring ───────────────────────────────────────────────────── */
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+
+/* ─── Utility layer ────────────────────────────────────────────────── */
+@layer utilities {
+  .bg-surface        { background-color: var(--color-surface); }
+  .bg-surface-raised { background-color: var(--color-surface-raised); }
+  .bg-app            { background-color: var(--color-bg); }
+  .border-theme      { border-color: var(--color-border); }
+  .text-primary      { color: var(--color-text-primary); }
+  .text-secondary    { color: var(--color-text-secondary); }
+  .text-muted        { color: var(--color-text-muted); }
+  .text-accent       { color: var(--color-accent); }
+  .bg-accent         { background-color: var(--color-accent); }
+  .bg-accent-light   { background-color: var(--color-accent-light); }
+  .ring-accent       { --tw-ring-color: var(--color-accent); }
+}

apps/client/src/lib/api.ts

@@ -0,0 +1,103 @@
+import axios from 'axios';
+
+export const api = axios.create({ baseURL: '/api' });
+
+// ── Types ─────────────────────────────────────────────────────────────────
+export interface Member {
+  id: number;
+  name: string;
+  color: string;
+  avatar: string | null;
+  created_at: string;
+}
+
+export interface CalendarEvent {
+  id: number;
+  title: string;
+  description: string | null;
+  start_at: string;
+  end_at: string;
+  all_day: number;
+  recurrence: string | null;
+  member_id: number | null;
+  color: string | null;
+  created_at: string;
+}
+
+export interface ShoppingList {
+  id: number;
+  name: string;
+  created_at: string;
+}
+
+export interface ShoppingItem {
+  id: number;
+  list_id: number;
+  name: string;
+  quantity: string | null;
+  checked: number;
+  member_id: number | null;
+  sort_order: number;
+  created_at: string;
+}
+
+export interface Chore {
+  id: number;
+  title: string;
+  description: string | null;
+  member_id: number | null;
+  member_name: string | null;
+  member_color: string | null;
+  recurrence: string;
+  status: string;
+  due_date: string | null;
+  completion_count: number;
+  created_at: string;
+}
+
+export interface Meal {
+  id: number;
+  date: string;
+  title: string;
+  description: string | null;
+  recipe_url: string | null;
+  created_at: string;
+}
+
+export interface Message {
+  id: number;
+  member_id: number | null;
+  member_name: string | null;
+  member_color: string | null;
+  body: string;
+  color: string;
+  emoji: string | null;
+  pinned: number;
+  expires_at: string | null;
+  created_at: string;
+}
+
+export interface Countdown {
+  id: number;
+  title: string;
+  target_date: string;
+  emoji: string | null;
+  color: string;
+  show_on_dashboard: number;
+  event_id: number | null;
+  created_at: string;
+}
+
+export interface AppSettings {
+  theme: string;
+  accent: string;
+  photo_folder: string;
+  slideshow_speed: string;
+  slideshow_order: string;
+  idle_timeout: string;
+  time_format: string;
+  date_format: string;
+  weather_api_key: string;
+  weather_location: string;
+  weather_units: string;
+}

apps/client/src/main.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import App from './App';
+import './index.css';
+import { initTheme } from './store/themeStore';
+
+// Apply persisted theme tokens before first render
+initTheme();
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { staleTime: 30_000, retry: 1 } },
+});
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  </React.StrictMode>
+);

apps/client/src/pages/Board.tsx

@@ -0,0 +1,3 @@
+export default function BoardPage() {
+  return <div className="p-6"><h1 className="text-2xl font-bold text-primary">Message Board</h1><p className="text-secondary mt-2">Phase 4</p></div>;
+}

apps/client/src/pages/Calendar.tsx

@@ -0,0 +1,224 @@
+import { useState, useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { motion, AnimatePresence } from 'framer-motion';
+import {
+  addMonths, subMonths, format, isSameDay,
+  startOfMonth, endOfMonth,
+} from 'date-fns';
+import { ChevronLeft, ChevronRight, Plus, CalendarDays } from 'lucide-react';
+import { api, type CalendarEvent } from '@/lib/api';
+import { useMembers } from '@/hooks/useMembers';
+import { CalendarGrid } from '@/features/calendar/CalendarGrid';
+import { EventModal } from '@/features/calendar/EventModal';
+import { DayEventsModal } from '@/features/calendar/DayEventsModal';
+import { Button } from '@/components/ui/Button';
+import { Avatar } from '@/components/ui/Avatar';
+
+export default function CalendarPage() {
+  const [month, setMonth] = useState(new Date());
+  const [direction, setDirection] = useState(0);
+
+  const [dayModal, setDayModal]   = useState<Date | null>(null);
+  const [editEvent, setEditEvent] = useState<CalendarEvent | null>(null);
+  const [addDate, setAddDate]     = useState<Date | null>(null);
+  const [addOpen, setAddOpen]     = useState(false);
+
+  const { data: members = [] } = useMembers();
+
+  const { data: events = [] } = useQuery<CalendarEvent[]>({
+    queryKey: ['events', format(month, 'yyyy-MM')],
+    queryFn: () => {
+      const start = startOfMonth(month).toISOString();
+      const end   = endOfMonth(month).toISOString();
+      return api.get('/events', { params: { start, end } }).then((r) => r.data);
+    },
+  });
+
+  function navigate(dir: number) {
+    setDirection(dir);
+    setMonth((m) => dir > 0 ? addMonths(m, 1) : subMonths(m, 1));
+  }
+
+  function handleDayClick(date: Date) {
+    setDayModal(date);
+  }
+
+  function handleAddFromDay() {
+    setAddDate(dayModal);
+    setAddOpen(true);
+  }
+
+  function handleAddNew() {
+    setAddDate(null);
+    setAddOpen(true);
+  }
+
+  const dayEvents = useMemo(() => {
+    if (!dayModal) return [];
+    return events.filter((e) => isSameDay(new Date(e.start_at), dayModal));
+  }, [dayModal, events]);
+
+  // Upcoming events strip (next 5 from today)
+  const upcoming = useMemo(() => {
+    const now = new Date();
+    return [...events]
+      .filter((e) => new Date(e.start_at) >= now)
+      .sort((a, b) => +new Date(a.start_at) - +new Date(b.start_at))
+      .slice(0, 5);
+  }, [events]);
+
+  const variants = {
+    enter: (d: number) => ({ x: d > 0 ? 40 : -40, opacity: 0 }),
+    center: { x: 0, opacity: 1 },
+    exit:  (d: number) => ({ x: d > 0 ? -40 : 40, opacity: 0 }),
+  };
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      {/* ── Header ────────────────────────────────────────────────── */}
+      <div className="flex items-center justify-between px-6 py-4 border-b border-theme bg-surface shrink-0">
+        <div className="flex items-center gap-3">
+          <CalendarDays size={22} className="text-accent" />
+          <AnimatePresence mode="wait" custom={direction}>
+            <motion.h1
+              key={format(month, 'yyyy-MM')}
+              custom={direction}
+              variants={variants}
+              initial="enter"
+              animate="center"
+              exit="exit"
+              transition={{ duration: 0.18 }}
+              className="text-xl font-bold text-primary w-44"
+            >
+              {format(month, 'MMMM yyyy')}
+            </motion.h1>
+          </AnimatePresence>
+          <div className="flex gap-1">
+            <button
+              onClick={() => navigate(-1)}
+              className="p-1.5 rounded-lg text-secondary hover:bg-surface-raised hover:text-primary transition-colors"
+            >
+              <ChevronLeft size={18} />
+            </button>
+            <button
+              onClick={() => { setDirection(0); setMonth(new Date()); }}
+              className="px-3 py-1 rounded-lg text-xs font-medium text-secondary hover:bg-surface-raised hover:text-primary transition-colors"
+            >
+              Today
+            </button>
+            <button
+              onClick={() => navigate(1)}
+              className="p-1.5 rounded-lg text-secondary hover:bg-surface-raised hover:text-primary transition-colors"
+            >
+              <ChevronRight size={18} />
+            </button>
+          </div>
+        </div>
+
+        <div className="flex items-center gap-3">
+          {/* Member legend */}
+          <div className="hidden md:flex items-center gap-2">
+            {members.map((m) => (
+              <div key={m.id} className="flex items-center gap-1.5">
+                <span className="h-2.5 w-2.5 rounded-full" style={{ backgroundColor: m.color }} />
+                <span className="text-xs text-secondary">{m.name}</span>
+              </div>
+            ))}
+          </div>
+          <Button size="sm" onClick={handleAddNew}>
+            <Plus size={15} /> Event
+          </Button>
+        </div>
+      </div>
+
+      {/* ── Main: grid + sidebar ──────────────────────────────────── */}
+      <div className="flex flex-1 min-h-0 overflow-hidden">
+        {/* Calendar grid */}
+        <div className="flex-1 overflow-auto">
+          <AnimatePresence mode="wait" custom={direction}>
+            <motion.div
+              key={format(month, 'yyyy-MM')}
+              custom={direction}
+              variants={variants}
+              initial="enter"
+              animate="center"
+              exit="exit"
+              transition={{ duration: 0.2 }}
+              className="h-full"
+            >
+              <CalendarGrid
+                month={month}
+                events={events}
+                members={members}
+                onDayClick={handleDayClick}
+                onEventClick={(ev) => setEditEvent(ev)}
+              />
+            </motion.div>
+          </AnimatePresence>
+        </div>
+
+        {/* Upcoming sidebar */}
+        {upcoming.length > 0 && (
+          <aside className="hidden lg:flex flex-col w-64 shrink-0 border-l border-theme bg-surface overflow-y-auto">
+            <div className="px-4 py-3 border-b border-theme">
+              <p className="text-xs font-semibold text-muted uppercase tracking-wide">Upcoming</p>
+            </div>
+            <div className="p-3 flex flex-col gap-2">
+              {upcoming.map((ev) => {
+                const color = ev.color ?? members.find((m) => m.id === ev.member_id)?.color ?? '#6366f1';
+                const member = members.find((m) => m.id === ev.member_id);
+                return (
+                  <button
+                    key={ev.id}
+                    onClick={() => setEditEvent(ev)}
+                    className="w-full text-left p-3 rounded-xl border border-theme hover:border-accent/40 hover:bg-surface-raised transition-colors"
+                  >
+                    <div className="flex items-start gap-2">
+                      <span className="mt-1.5 h-2 w-2 rounded-full shrink-0" style={{ backgroundColor: color }} />
+                      <div className="min-w-0">
+                        <p className="text-sm font-medium text-primary truncate">{ev.title}</p>
+                        <p className="text-xs text-muted mt-0.5">
+                          {format(new Date(ev.start_at), 'MMM d')}
+                          {!ev.all_day && ` · ${format(new Date(ev.start_at), 'h:mm a')}`}
+                        </p>
+                        {member && (
+                          <div className="flex items-center gap-1.5 mt-1">
+                            <Avatar name={member.name} color={member.color} size="xs" />
+                            <span className="text-xs text-secondary">{member.name}</span>
+                          </div>
+                        )}
+                      </div>
+                    </div>
+                  </button>
+                );
+              })}
+            </div>
+          </aside>
+        )}
+      </div>
+
+      {/* ── Modals ─────────────────────────────────────────────────── */}
+      <DayEventsModal
+        open={!!dayModal}
+        onClose={() => setDayModal(null)}
+        date={dayModal}
+        events={dayEvents}
+        members={members}
+        onAdd={handleAddFromDay}
+        onEdit={(ev) => { setDayModal(null); setEditEvent(ev); }}
+      />
+
+      <EventModal
+        open={addOpen}
+        onClose={() => { setAddOpen(false); setAddDate(null); }}
+        defaultDate={addDate ?? undefined}
+      />
+
+      <EventModal
+        open={!!editEvent}
+        onClose={() => setEditEvent(null)}
+        event={editEvent}
+      />
+    </div>
+  );
+}

apps/client/src/pages/Chores.tsx

@@ -0,0 +1,155 @@
+import { useState, useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { AnimatePresence, motion } from 'framer-motion';
+import { Plus, CheckSquare, ListFilter } from 'lucide-react';
+import { api, type Chore } from '@/lib/api';
+import { useMembers } from '@/hooks/useMembers';
+import { ChoreCard } from '@/features/chores/ChoreCard';
+import { ChoreModal } from '@/features/chores/ChoreModal';
+import { Button } from '@/components/ui/Button';
+import { Avatar } from '@/components/ui/Avatar';
+import { clsx } from 'clsx';
+
+type Filter = 'all' | 'pending' | 'done' | number; // number = member_id
+
+export default function ChoresPage() {
+  const [filter, setFilter]   = useState<Filter>('pending');
+  const [modalOpen, setModalOpen] = useState(false);
+  const [editChore, setEditChore] = useState<Chore | null>(null);
+
+  const { data: members = [] } = useMembers();
+
+  const { data: chores = [], isLoading } = useQuery<Chore[]>({
+    queryKey: ['chores'],
+    queryFn: () => api.get('/chores').then((r) => r.data),
+  });
+
+  const filtered = useMemo(() => {
+    if (filter === 'all')     return chores;
+    if (filter === 'pending') return chores.filter((c) => c.status !== 'done');
+    if (filter === 'done')    return chores.filter((c) => c.status === 'done');
+    return chores.filter((c) => c.member_id === filter);
+  }, [chores, filter]);
+
+  const pendingCount = chores.filter((c) => c.status !== 'done').length;
+  const doneCount    = chores.filter((c) => c.status === 'done').length;
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      {/* ── Header ──────────────────────────────────────────────── */}
+      <div className="flex items-center justify-between px-6 py-4 border-b border-theme bg-surface shrink-0">
+        <div className="flex items-center gap-3">
+          <CheckSquare size={22} className="text-accent" />
+          <div>
+            <h1 className="text-xl font-bold text-primary leading-tight">Chores</h1>
+            <p className="text-xs text-muted">
+              {pendingCount} pending · {doneCount} done
+            </p>
+          </div>
+        </div>
+        <Button size="sm" onClick={() => setModalOpen(true)}>
+          <Plus size={15} /> Add Chore
+        </Button>
+      </div>
+
+      {/* ── Filter bar ──────────────────────────────────────────── */}
+      <div className="flex items-center gap-2 px-6 py-3 border-b border-theme bg-surface shrink-0 overflow-x-auto">
+        <ListFilter size={15} className="text-muted shrink-0" />
+        {(
+          [
+            { key: 'pending', label: 'Pending' },
+            { key: 'all',     label: 'All' },
+            { key: 'done',    label: 'Done' },
+          ] as { key: Filter; label: string }[]
+        ).map(({ key, label }) => (
+          <button
+            key={String(key)}
+            onClick={() => setFilter(key)}
+            className={clsx(
+              'px-3 py-1.5 rounded-full text-sm font-medium transition-colors whitespace-nowrap',
+              filter === key
+                ? 'bg-accent text-white'
+                : 'text-secondary hover:bg-surface-raised hover:text-primary'
+            )}
+          >
+            {label}
+          </button>
+        ))}
+        {members.length > 0 && <span className="text-muted text-xs mx-1">|</span>}
+        {members.map((m) => (
+          <button
+            key={m.id}
+            onClick={() => setFilter(filter === m.id ? 'all' : m.id)}
+            className={clsx(
+              'flex items-center gap-1.5 px-3 py-1.5 rounded-full text-sm font-medium transition-all whitespace-nowrap',
+              filter === m.id
+                ? 'text-white'
+                : 'text-secondary hover:bg-surface-raised hover:text-primary'
+            )}
+            style={filter === m.id ? { backgroundColor: m.color } : {}}
+          >
+            <Avatar name={m.name} color={m.color} size="xs" />
+            {m.name}
+          </button>
+        ))}
+      </div>
+
+      {/* ── List ────────────────────────────────────────────────── */}
+      <div className="flex-1 overflow-y-auto p-6">
+        {isLoading ? (
+          <div className="space-y-3">
+            {[1, 2, 3, 4].map((i) => (
+              <div key={i} className="h-20 rounded-2xl bg-surface-raised animate-pulse" />
+            ))}
+          </div>
+        ) : filtered.length === 0 ? (
+          <motion.div
+            initial={{ opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            className="flex flex-col items-center justify-center py-20 text-center"
+          >
+            <div className="text-5xl mb-4">
+              {filter === 'done' ? '🎉' : '✅'}
+            </div>
+            <p className="text-lg font-semibold text-primary mb-1">
+              {filter === 'done' ? 'Nothing completed yet' : 'All caught up!'}
+            </p>
+            <p className="text-secondary text-sm mb-6">
+              {filter === 'done'
+                ? 'Complete a chore and it will appear here.'
+                : 'No chores match this filter.'}
+            </p>
+            {filter === 'pending' && (
+              <Button onClick={() => setModalOpen(true)}>
+                <Plus size={16} /> Add First Chore
+              </Button>
+            )}
+          </motion.div>
+        ) : (
+          <AnimatePresence initial={false}>
+            <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-3">
+              {filtered.map((chore) => (
+                <ChoreCard
+                  key={chore.id}
+                  chore={chore}
+                  onEdit={(c) => setEditChore(c)}
+                />
+              ))}
+            </div>
+          </AnimatePresence>
+        )}
+      </div>
+
+      {/* ── Modals ──────────────────────────────────────────────── */}
+      <ChoreModal
+        open={modalOpen}
+        onClose={() => setModalOpen(false)}
+      />
+      <ChoreModal
+        open={!!editChore}
+        onClose={() => setEditChore(null)}
+        chore={editChore}
+      />
+    </div>
+  );
+}

apps/client/src/pages/Countdowns.tsx

@@ -0,0 +1,3 @@
+export default function CountdownsPage() {
+  return <div className="p-6"><h1 className="text-2xl font-bold text-primary">Countdowns</h1><p className="text-secondary mt-2">Phase 4</p></div>;
+}

apps/client/src/pages/Dashboard.tsx

@@ -0,0 +1,8 @@
+export default function Dashboard() {
+  return (
+    <div className="p-6">
+      <h1 className="text-2xl font-bold text-primary mb-2">Good morning 👋</h1>
+      <p className="text-secondary">Your family dashboard is coming together. More widgets arriving in Phase 2.</p>
+    </div>
+  );
+}

apps/client/src/pages/Meals.tsx

@@ -0,0 +1,3 @@
+export default function MealsPage() {
+  return <div className="p-6"><h1 className="text-2xl font-bold text-primary">Meal Planner</h1><p className="text-secondary mt-2">Phase 2</p></div>;
+}

apps/client/src/pages/Members.tsx

@@ -0,0 +1,234 @@
+import { useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { motion, AnimatePresence } from 'framer-motion';
+import { Plus, Pencil, Trash2, ArrowLeft } from 'lucide-react';
+import { Link } from 'react-router-dom';
+import { api, type Member } from '@/lib/api';
+import { Button } from '@/components/ui/Button';
+import { Input } from '@/components/ui/Input';
+import { Modal } from '@/components/ui/Modal';
+import { Avatar } from '@/components/ui/Avatar';
+
+const PRESET_COLORS = [
+  '#6366f1', '#14b8a6', '#f43f5e', '#f59e0b', '#64748b',
+  '#8b5cf6', '#ec4899', '#10b981', '#f97316', '#06b6d4',
+];
+
+interface MemberFormData {
+  name: string;
+  color: string;
+}
+
+function MemberForm({
+  initial,
+  onSubmit,
+  onCancel,
+  loading,
+}: {
+  initial?: MemberFormData;
+  onSubmit: (data: MemberFormData) => void;
+  onCancel: () => void;
+  loading: boolean;
+}) {
+  const [name, setName] = useState(initial?.name ?? '');
+  const [color, setColor] = useState(initial?.color ?? PRESET_COLORS[0]);
+
+  return (
+    <div className="space-y-5">
+      <Input
+        label="Name"
+        value={name}
+        onChange={(e) => setName(e.target.value)}
+        placeholder="Family member's name"
+        autoFocus
+      />
+      <div>
+        <p className="text-sm font-medium text-secondary mb-3">Color</p>
+        <div className="flex flex-wrap gap-2.5">
+          {PRESET_COLORS.map((c) => (
+            <button
+              key={c}
+              onClick={() => setColor(c)}
+              className="h-8 w-8 rounded-full ring-offset-2 ring-offset-surface transition-all duration-150"
+              style={{
+                backgroundColor: c,
+                boxShadow: color === c ? `0 0 0 2px white, 0 0 0 4px ${c}` : undefined,
+              }}
+              aria-label={c}
+            />
+          ))}
+        </div>
+        <div className="mt-3 flex items-center gap-3">
+          <input
+            type="color"
+            value={color}
+            onChange={(e) => setColor(e.target.value)}
+            className="h-8 w-12 cursor-pointer rounded border border-theme bg-transparent"
+          />
+          <span className="text-sm text-muted font-mono">{color}</span>
+        </div>
+      </div>
+
+      {/* Preview */}
+      {name && (
+        <div className="flex items-center gap-3 p-3 rounded-xl bg-surface-raised">
+          <Avatar name={name} color={color} size="md" />
+          <span className="font-medium text-primary">{name}</span>
+        </div>
+      )}
+
+      <div className="flex gap-3 pt-1">
+        <Button variant="secondary" onClick={onCancel} className="flex-1">Cancel</Button>
+        <Button onClick={() => onSubmit({ name, color })} loading={loading} disabled={!name.trim()} className="flex-1">
+          Save
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export default function MembersPage() {
+  const qc = useQueryClient();
+  const [addOpen, setAddOpen] = useState(false);
+  const [editTarget, setEditTarget] = useState<Member | null>(null);
+  const [deleteTarget, setDeleteTarget] = useState<Member | null>(null);
+
+  const { data: members = [], isLoading } = useQuery<Member[]>({
+    queryKey: ['members'],
+    queryFn: () => api.get('/members').then((r) => r.data),
+  });
+
+  const createMutation = useMutation({
+    mutationFn: (data: MemberFormData) => api.post('/members', data).then((r) => r.data),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['members'] }); setAddOpen(false); },
+  });
+
+  const updateMutation = useMutation({
+    mutationFn: ({ id, data }: { id: number; data: MemberFormData }) =>
+      api.put(`/members/${id}`, data).then((r) => r.data),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['members'] }); setEditTarget(null); },
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (id: number) => api.delete(`/members/${id}`),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['members'] }); setDeleteTarget(null); },
+  });
+
+  return (
+    <div className="p-6 max-w-2xl mx-auto">
+      {/* Header */}
+      <div className="flex items-center gap-4 mb-6">
+        <Link to="/settings" className="p-2 rounded-xl text-secondary hover:bg-surface-raised hover:text-primary transition-colors">
+          <ArrowLeft size={20} />
+        </Link>
+        <div className="flex-1">
+          <h1 className="text-2xl font-bold text-primary">Family Members</h1>
+          <p className="text-secondary text-sm">{members.length} member{members.length !== 1 ? 's' : ''}</p>
+        </div>
+        <Button onClick={() => setAddOpen(true)}>
+          <Plus size={16} /> Add Member
+        </Button>
+      </div>
+
+      {/* Member list */}
+      {isLoading ? (
+        <div className="space-y-3">
+          {[1, 2, 3].map((i) => (
+            <div key={i} className="h-20 rounded-2xl bg-surface-raised animate-pulse" />
+          ))}
+        </div>
+      ) : members.length === 0 ? (
+        <div className="text-center py-16">
+          <div className="text-5xl mb-4">👨‍👩‍👧‍👦</div>
+          <p className="text-primary font-semibold text-lg mb-1">No family members yet</p>
+          <p className="text-secondary text-sm mb-6">Add your family members to assign chores, events, and more.</p>
+          <Button onClick={() => setAddOpen(true)}>
+            <Plus size={16} /> Add First Member
+          </Button>
+        </div>
+      ) : (
+        <div className="space-y-3">
+          <AnimatePresence initial={false}>
+            {members.map((member) => (
+              <motion.div
+                key={member.id}
+                layout
+                initial={{ opacity: 0, y: 8 }}
+                animate={{ opacity: 1, y: 0 }}
+                exit={{ opacity: 0, scale: 0.95 }}
+                className="flex items-center gap-4 p-4 rounded-2xl bg-surface border border-theme hover:border-accent/40 transition-colors group"
+              >
+                <Avatar name={member.name} color={member.color} size="lg" />
+                <div className="flex-1 min-w-0">
+                  <p className="font-semibold text-primary truncate">{member.name}</p>
+                  <p className="text-xs font-mono text-muted">{member.color}</p>
+                </div>
+                <div className="flex gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+                  <button
+                    onClick={() => setEditTarget(member)}
+                    className="p-2 rounded-lg text-secondary hover:bg-surface-raised hover:text-accent transition-colors"
+                  >
+                    <Pencil size={16} />
+                  </button>
+                  <button
+                    onClick={() => setDeleteTarget(member)}
+                    className="p-2 rounded-lg text-secondary hover:bg-surface-raised hover:text-red-500 transition-colors"
+                  >
+                    <Trash2 size={16} />
+                  </button>
+                </div>
+              </motion.div>
+            ))}
+          </AnimatePresence>
+        </div>
+      )}
+
+      {/* Add modal */}
+      <Modal open={addOpen} onClose={() => setAddOpen(false)} title="Add Family Member">
+        <MemberForm
+          onSubmit={(data) => createMutation.mutate(data)}
+          onCancel={() => setAddOpen(false)}
+          loading={createMutation.isPending}
+        />
+      </Modal>
+
+      {/* Edit modal */}
+      <Modal open={!!editTarget} onClose={() => setEditTarget(null)} title="Edit Family Member">
+        {editTarget && (
+          <MemberForm
+            initial={{ name: editTarget.name, color: editTarget.color }}
+            onSubmit={(data) => updateMutation.mutate({ id: editTarget.id, data })}
+            onCancel={() => setEditTarget(null)}
+            loading={updateMutation.isPending}
+          />
+        )}
+      </Modal>
+
+      {/* Delete confirm modal */}
+      <Modal open={!!deleteTarget} onClose={() => setDeleteTarget(null)} title="Remove Member" size="sm">
+        {deleteTarget && (
+          <div className="space-y-4">
+            <div className="flex items-center gap-3 p-3 rounded-xl bg-surface-raised">
+              <Avatar name={deleteTarget.name} color={deleteTarget.color} />
+              <span className="font-medium text-primary">{deleteTarget.name}</span>
+            </div>
+            <p className="text-secondary text-sm">
+              Removing this member won't delete their assigned chores or events — those will simply become unassigned.
+            </p>
+            <div className="flex gap-3">
+              <Button variant="secondary" onClick={() => setDeleteTarget(null)} className="flex-1">Cancel</Button>
+              <Button
+                variant="danger"
+                loading={deleteMutation.isPending}
+                onClick={() => deleteMutation.mutate(deleteTarget.id)}
+                className="flex-1"
+              >
+                Remove
+              </Button>
+            </div>
+          </div>
+        )}
+      </Modal>
+    </div>
+  );
+}

apps/client/src/pages/Photos.tsx

@@ -0,0 +1,3 @@
+export default function PhotosPage() {
+  return <div className="p-6"><h1 className="text-2xl font-bold text-primary">Photo Slideshow</h1><p className="text-secondary mt-2">Phase 3</p></div>;
+}

apps/client/src/pages/Settings.tsx

@@ -0,0 +1,208 @@
+import { useEffect, useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { Save, Folder, Clock, Image, Cloud, Users } from 'lucide-react';
+import { api, type AppSettings } from '@/lib/api';
+import { Button } from '@/components/ui/Button';
+import { Input } from '@/components/ui/Input';
+import { ThemeToggle } from '@/components/ui/ThemeToggle';
+import { useThemeStore, ACCENT_TOKENS, type AccentColor } from '@/store/themeStore';
+import { clsx } from 'clsx';
+import { Link } from 'react-router-dom';
+
+function Section({ title, icon, children }: { title: string; icon: React.ReactNode; children: React.ReactNode }) {
+  return (
+    <div className="bg-surface rounded-2xl border border-theme p-6">
+      <div className="flex items-center gap-3 mb-5">
+        <span className="text-accent">{icon}</span>
+        <h2 className="text-base font-semibold text-primary">{title}</h2>
+      </div>
+      <div className="space-y-4">{children}</div>
+    </div>
+  );
+}
+
+export default function SettingsPage() {
+  const qc = useQueryClient();
+  const { accent, setAccent } = useThemeStore();
+
+  const { data: settings } = useQuery<AppSettings>({
+    queryKey: ['settings'],
+    queryFn: () => api.get('/settings').then((r) => r.data),
+  });
+
+  const [form, setForm] = useState<Partial<AppSettings>>({});
+  useEffect(() => { if (settings) setForm(settings); }, [settings]);
+
+  const mutation = useMutation({
+    mutationFn: (patch: Partial<AppSettings>) => api.patch('/settings', patch).then((r) => r.data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['settings'] }),
+  });
+
+  const set = (key: keyof AppSettings, value: string) => setForm((f) => ({ ...f, [key]: value }));
+  const save = () => mutation.mutate(form as AppSettings);
+
+  return (
+    <div className="p-6 max-w-3xl mx-auto space-y-6">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-2xl font-bold text-primary">Settings</h1>
+          <p className="text-secondary text-sm mt-1">Configure your family dashboard</p>
+        </div>
+        <Button onClick={save} loading={mutation.isPending}>
+          <Save size={16} /> Save Changes
+        </Button>
+      </div>
+
+      {/* ── Appearance ─────────────────────────────────────────────── */}
+      <Section title="Appearance" icon={<Image size={20} />}>
+        <div>
+          <p className="text-sm font-medium text-secondary mb-3">Theme Mode</p>
+          <ThemeToggle showLabel />
+        </div>
+        <div>
+          <p className="text-sm font-medium text-secondary mb-3">Accent Color</p>
+          <div className="flex gap-3 flex-wrap">
+            {(Object.keys(ACCENT_TOKENS) as AccentColor[]).map((key) => {
+              const { base, label } = ACCENT_TOKENS[key];
+              return (
+                <button
+                  key={key}
+                  onClick={() => { setAccent(key); set('accent', key); }}
+                  className={clsx(
+                    'flex items-center gap-2 px-4 py-2 rounded-xl border-2 text-sm font-medium transition-all',
+                    accent === key
+                      ? 'border-accent text-accent bg-accent-light'
+                      : 'border-theme text-secondary hover:border-accent/50'
+                  )}
+                >
+                  <span className="h-3.5 w-3.5 rounded-full shrink-0" style={{ backgroundColor: base }} />
+                  {label}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      </Section>
+
+      {/* ── Family Members ─────────────────────────────────────────── */}
+      <Section title="Family Members" icon={<Users size={20} />}>
+        <p className="text-sm text-secondary">
+          Add, edit, or remove family members. Members are used throughout the app to assign chores, events, and shopping items.
+        </p>
+        <Link to="/settings/members">
+          <Button variant="secondary">
+            <Users size={16} /> Manage Family Members
+          </Button>
+        </Link>
+      </Section>
+
+      {/* ── Photo Slideshow ────────────────────────────────────────── */}
+      <Section title="Photo Slideshow" icon={<Folder size={20} />}>
+        <Input
+          label="Photo Folder Path"
+          value={form.photo_folder ?? ''}
+          onChange={(e) => set('photo_folder', e.target.value)}
+          placeholder="C:\Users\YourName\Pictures\Family"
+          hint="Absolute path to the folder containing your photos. Subfolders are included."
+        />
+        <div className="grid grid-cols-2 gap-4">
+          <div>
+            <label className="text-sm font-medium text-secondary block mb-1.5">Transition Speed (ms)</label>
+            <select
+              className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent"
+              value={form.slideshow_speed ?? '6000'}
+              onChange={(e) => set('slideshow_speed', e.target.value)}
+            >
+              {[3000, 5000, 6000, 8000, 10000, 15000].map((v) => (
+                <option key={v} value={v}>{v / 1000}s</option>
+              ))}
+            </select>
+          </div>
+          <div>
+            <label className="text-sm font-medium text-secondary block mb-1.5">Photo Order</label>
+            <select
+              className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent"
+              value={form.slideshow_order ?? 'random'}
+              onChange={(e) => set('slideshow_order', e.target.value)}
+            >
+              <option value="random">Random</option>
+              <option value="sequential">Sequential</option>
+              <option value="newest">Newest First</option>
+            </select>
+          </div>
+        </div>
+        <div>
+          <label className="text-sm font-medium text-secondary block mb-1.5">Idle Timeout (before screensaver)</label>
+          <select
+            className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent"
+            value={form.idle_timeout ?? '120000'}
+            onChange={(e) => set('idle_timeout', e.target.value)}
+          >
+            <option value="60000">1 minute</option>
+            <option value="120000">2 minutes</option>
+            <option value="300000">5 minutes</option>
+            <option value="600000">10 minutes</option>
+            <option value="0">Disabled</option>
+          </select>
+        </div>
+      </Section>
+
+      {/* ── Date & Time ────────────────────────────────────────────── */}
+      <Section title="Date & Time" icon={<Clock size={20} />}>
+        <div className="grid grid-cols-2 gap-4">
+          <div>
+            <label className="text-sm font-medium text-secondary block mb-1.5">Time Format</label>
+            <select
+              className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent"
+              value={form.time_format ?? '12h'}
+              onChange={(e) => set('time_format', e.target.value)}
+            >
+              <option value="12h">12-hour (3:30 PM)</option>
+              <option value="24h">24-hour (15:30)</option>
+            </select>
+          </div>
+          <div>
+            <label className="text-sm font-medium text-secondary block mb-1.5">Date Format</label>
+            <select
+              className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent"
+              value={form.date_format ?? 'MM/DD/YYYY'}
+              onChange={(e) => set('date_format', e.target.value)}
+            >
+              <option value="MM/DD/YYYY">MM/DD/YYYY</option>
+              <option value="DD/MM/YYYY">DD/MM/YYYY</option>
+              <option value="YYYY-MM-DD">YYYY-MM-DD</option>
+            </select>
+          </div>
+        </div>
+      </Section>
+
+      {/* ── Weather ────────────────────────────────────────────────── */}
+      <Section title="Weather Widget" icon={<Cloud size={20} />}>
+        <Input
+          label="OpenWeatherMap API Key"
+          value={form.weather_api_key ?? ''}
+          onChange={(e) => set('weather_api_key', e.target.value)}
+          placeholder="Your free API key from openweathermap.org"
+          type="password"
+        />
+        <Input
+          label="Location (city name or zip)"
+          value={form.weather_location ?? ''}
+          onChange={(e) => set('weather_location', e.target.value)}
+          placeholder="New York, US"
+        />
+        <div>
+          <label className="text-sm font-medium text-secondary block mb-1.5">Units</label>
+          <select
+            className="w-full rounded-lg border border-theme bg-surface-raised px-3 py-2 text-sm text-primary focus:outline-none focus:ring-2 ring-accent"
+            value={form.weather_units ?? 'imperial'}
+            onChange={(e) => set('weather_units', e.target.value)}
+          >
+            <option value="imperial">Imperial (°F)</option>
+            <option value="metric">Metric (°C)</option>
+          </select>
+        </div>
+      </Section>
+    </div>
+  );
+}

apps/client/src/pages/Shopping.tsx

@@ -0,0 +1,292 @@
+import { useState, useRef, useEffect } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { AnimatePresence, motion } from 'framer-motion';
+import { Plus, ShoppingCart, Trash2, ListPlus, X } from 'lucide-react';
+import { api, type ShoppingList, type ShoppingItem } from '@/lib/api';
+import { useMembers } from '@/hooks/useMembers';
+import { ShoppingItemRow } from '@/features/shopping/ShoppingItemRow';
+import { Button } from '@/components/ui/Button';
+import { Modal } from '@/components/ui/Modal';
+import { Input } from '@/components/ui/Input';
+import { clsx } from 'clsx';
+
+export default function ShoppingPage() {
+  const qc = useQueryClient();
+  const { data: members = [] } = useMembers();
+
+  const [activeListId, setActiveListId] = useState<number | null>(null);
+  const [newItemText, setNewItemText]   = useState('');
+  const [newItemQty, setNewItemQty]     = useState('');
+  const [newListOpen, setNewListOpen]   = useState(false);
+  const [newListName, setNewListName]   = useState('');
+  const [deleteListOpen, setDeleteListOpen] = useState(false);
+
+  const addInputRef = useRef<HTMLInputElement>(null);
+
+  // ── Lists ──────────────────────────────────────────────────────
+  const { data: lists = [] } = useQuery<ShoppingList[]>({
+    queryKey: ['shopping-lists'],
+    queryFn: () => api.get('/shopping/lists').then((r) => r.data),
+  });
+
+  // Auto-select first list
+  useEffect(() => {
+    if (lists.length > 0 && activeListId === null) {
+      setActiveListId(lists[0].id);
+    }
+  }, [lists, activeListId]);
+
+  const createListMutation = useMutation({
+    mutationFn: (name: string) => api.post('/shopping/lists', { name }).then((r) => r.data),
+    onSuccess: (list: ShoppingList) => {
+      qc.invalidateQueries({ queryKey: ['shopping-lists'] });
+      setActiveListId(list.id);
+      setNewListOpen(false);
+      setNewListName('');
+    },
+  });
+
+  const deleteListMutation = useMutation({
+    mutationFn: (id: number) => api.delete(`/shopping/lists/${id}`),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['shopping-lists'] });
+      setActiveListId(null);
+      setDeleteListOpen(false);
+    },
+  });
+
+  // ── Items ──────────────────────────────────────────────────────
+  const { data: items = [], isLoading: itemsLoading } = useQuery<ShoppingItem[]>({
+    queryKey: ['shopping-items', activeListId],
+    queryFn: () =>
+      activeListId
+        ? api.get(`/shopping/lists/${activeListId}/items`).then((r) => r.data)
+        : Promise.resolve([]),
+    enabled: !!activeListId,
+  });
+
+  const addItemMutation = useMutation({
+    mutationFn: (body: { name: string; quantity?: string }) =>
+      api.post(`/shopping/lists/${activeListId}/items`, body).then((r) => r.data),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['shopping-items', activeListId] });
+      setNewItemText('');
+      setNewItemQty('');
+      addInputRef.current?.focus();
+    },
+  });
+
+  const clearCheckedMutation = useMutation({
+    mutationFn: () => api.delete(`/shopping/lists/${activeListId}/items/checked`),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['shopping-items', activeListId] }),
+  });
+
+  const handleAddItem = () => {
+    if (!newItemText.trim() || !activeListId) return;
+    addItemMutation.mutate({
+      name:     newItemText.trim(),
+      quantity: newItemQty.trim() || undefined,
+    });
+  };
+
+  const checkedCount  = items.filter((i) => i.checked).length;
+  const pendingCount  = items.length - checkedCount;
+  const currentList   = lists.find((l) => l.id === activeListId);
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      {/* ── Header ──────────────────────────────────────────────── */}
+      <div className="flex items-center justify-between px-6 py-4 border-b border-theme bg-surface shrink-0">
+        <div className="flex items-center gap-3">
+          <ShoppingCart size={22} className="text-accent" />
+          <div>
+            <h1 className="text-xl font-bold text-primary leading-tight">Shopping</h1>
+            {currentList && (
+              <p className="text-xs text-muted">
+                {pendingCount} item{pendingCount !== 1 ? 's' : ''} remaining
+                {checkedCount > 0 && ` · ${checkedCount} checked`}
+              </p>
+            )}
+          </div>
+        </div>
+        <div className="flex items-center gap-2">
+          {checkedCount > 0 && (
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => clearCheckedMutation.mutate()}
+              loading={clearCheckedMutation.isPending}
+              className="text-muted hover:text-red-500"
+            >
+              <Trash2 size={14} /> Clear checked
+            </Button>
+          )}
+          <Button variant="secondary" size="sm" onClick={() => setNewListOpen(true)}>
+            <ListPlus size={15} /> New List
+          </Button>
+        </div>
+      </div>
+
+      {/* ── List tabs ────────────────────────────────────────────── */}
+      {lists.length > 0 && (
+        <div className="flex items-center gap-1 px-6 py-2 border-b border-theme bg-surface shrink-0 overflow-x-auto">
+          {lists.map((list) => (
+            <button
+              key={list.id}
+              onClick={() => setActiveListId(list.id)}
+              className={clsx(
+                'px-4 py-1.5 rounded-full text-sm font-medium transition-all whitespace-nowrap',
+                activeListId === list.id
+                  ? 'bg-accent text-white shadow-sm'
+                  : 'text-secondary hover:bg-surface-raised hover:text-primary'
+              )}
+            >
+              {list.name}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {/* ── Items ────────────────────────────────────────────────── */}
+      <div className="flex-1 overflow-y-auto">
+        {lists.length === 0 ? (
+          <div className="flex flex-col items-center justify-center h-full text-center p-8">
+            <div className="text-5xl mb-4">🛒</div>
+            <p className="text-lg font-semibold text-primary mb-1">No shopping lists yet</p>
+            <p className="text-secondary text-sm mb-6">Create a list to start adding items.</p>
+            <Button onClick={() => setNewListOpen(true)}>
+              <Plus size={16} /> Create List
+            </Button>
+          </div>
+        ) : itemsLoading ? (
+          <div className="p-6 space-y-2">
+            {[1, 2, 3, 4, 5].map((i) => (
+              <div key={i} className="h-12 rounded-xl bg-surface-raised animate-pulse" />
+            ))}
+          </div>
+        ) : items.length === 0 ? (
+          <div className="flex flex-col items-center justify-center py-16 text-center px-6">
+            <div className="text-4xl mb-3">📝</div>
+            <p className="text-primary font-semibold mb-1">List is empty</p>
+            <p className="text-secondary text-sm">Add items using the field below.</p>
+          </div>
+        ) : (
+          <ul className="bg-surface mx-4 my-4 rounded-2xl border border-theme overflow-hidden">
+            {/* Unchecked items first */}
+            <AnimatePresence initial={false}>
+              {items
+                .filter((i) => !i.checked)
+                .map((item) => (
+                  <ShoppingItemRow
+                    key={item.id}
+                    item={item}
+                    members={members}
+                    listId={activeListId!}
+                  />
+                ))}
+            </AnimatePresence>
+
+            {/* Checked items section */}
+            {checkedCount > 0 && (
+              <>
+                <li className="px-4 py-2 bg-surface-raised border-t border-theme">
+                  <span className="text-xs font-semibold text-muted uppercase tracking-wide">
+                    In cart ({checkedCount})
+                  </span>
+                </li>
+                <AnimatePresence initial={false}>
+                  {items
+                    .filter((i) => i.checked)
+                    .map((item) => (
+                      <ShoppingItemRow
+                        key={item.id}
+                        item={item}
+                        members={members}
+                        listId={activeListId!}
+                      />
+                    ))}
+                </AnimatePresence>
+              </>
+            )}
+          </ul>
+        )}
+      </div>
+
+      {/* ── Quick-add bar (pinned to bottom) ──────────────────────── */}
+      {activeListId && (
+        <div className="shrink-0 bg-surface border-t border-theme px-4 py-3">
+          <div className="flex gap-2 max-w-2xl mx-auto">
+            <input
+              ref={addInputRef}
+              type="text"
+              value={newItemText}
+              onChange={(e) => setNewItemText(e.target.value)}
+              onKeyDown={(e) => e.key === 'Enter' && handleAddItem()}
+              placeholder="Add item…"
+              className="flex-1 rounded-xl border border-theme bg-surface-raised px-4 py-2.5 text-sm text-primary placeholder:text-muted focus:outline-none focus:ring-2 ring-accent transition-colors"
+            />
+            <input
+              type="text"
+              value={newItemQty}
+              onChange={(e) => setNewItemQty(e.target.value)}
+              onKeyDown={(e) => e.key === 'Enter' && handleAddItem()}
+              placeholder="Qty"
+              className="w-20 rounded-xl border border-theme bg-surface-raised px-3 py-2.5 text-sm text-primary placeholder:text-muted focus:outline-none focus:ring-2 ring-accent transition-colors"
+            />
+            <Button
+              onClick={handleAddItem}
+              disabled={!newItemText.trim()}
+              loading={addItemMutation.isPending}
+            >
+              <Plus size={16} />
+            </Button>
+          </div>
+        </div>
+      )}
+
+      {/* ── New list modal ─────────────────────────────────────────── */}
+      <Modal open={newListOpen} onClose={() => setNewListOpen(false)} title="New Shopping List" size="sm">
+        <div className="space-y-4">
+          <Input
+            label="List Name"
+            value={newListName}
+            onChange={(e) => setNewListName(e.target.value)}
+            onKeyDown={(e) => e.key === 'Enter' && newListName.trim() && createListMutation.mutate(newListName.trim())}
+            placeholder="e.g. Groceries, Hardware Store…"
+            autoFocus
+          />
+          <div className="flex gap-2 justify-end">
+            <Button variant="secondary" onClick={() => setNewListOpen(false)}>Cancel</Button>
+            <Button
+              onClick={() => createListMutation.mutate(newListName.trim())}
+              disabled={!newListName.trim()}
+              loading={createListMutation.isPending}
+            >
+              Create
+            </Button>
+          </div>
+        </div>
+      </Modal>
+
+      {/* ── Delete list confirmation ───────────────────────────────── */}
+      <Modal open={deleteListOpen} onClose={() => setDeleteListOpen(false)} title="Delete List?" size="sm">
+        <div className="space-y-4">
+          <p className="text-secondary text-sm">
+            This will permanently delete <strong className="text-primary">{currentList?.name}</strong> and all
+            its items. This cannot be undone.
+          </p>
+          <div className="flex gap-2 justify-end">
+            <Button variant="secondary" onClick={() => setDeleteListOpen(false)}>Cancel</Button>
+            <Button
+              variant="danger"
+              loading={deleteListMutation.isPending}
+              onClick={() => activeListId && deleteListMutation.mutate(activeListId)}
+            >
+              Delete List
+            </Button>
+          </div>
+        </div>
+      </Modal>
+    </div>
+  );
+}

apps/client/src/store/settingsStore.ts

@@ -0,0 +1,43 @@
+import { create } from 'zustand';
+import axios from 'axios';
+
+export interface AppSettings {
+  theme: string;
+  accent: string;
+  photo_folder: string;
+  slideshow_speed: string;
+  slideshow_order: string;
+  idle_timeout: string;
+  time_format: string;
+  date_format: string;
+  weather_api_key: string;
+  weather_location: string;
+  weather_units: string;
+}
+
+interface SettingsState {
+  settings: AppSettings | null;
+  loading: boolean;
+  fetch: () => Promise<void>;
+  update: (patch: Partial<AppSettings>) => Promise<void>;
+}
+
+export const useSettingsStore = create<SettingsState>((set, get) => ({
+  settings: null,
+  loading: false,
+  fetch: async () => {
+    set({ loading: true });
+    const { data } = await axios.get<AppSettings>('/api/settings');
+    set({ settings: data, loading: false });
+  },
+  update: async (patch) => {
+    const { data } = await axios.patch<AppSettings>('/api/settings', patch);
+    set({ settings: data });
+    // Sync theme/accent to theme store
+    if (patch.theme || patch.accent) {
+      const { useThemeStore } = await import('./themeStore');
+      if (patch.theme) useThemeStore.getState().setMode(patch.theme as any);
+      if (patch.accent) useThemeStore.getState().setAccent(patch.accent as any);
+    }
+  },
+}));

apps/client/src/store/themeStore.ts

@@ -0,0 +1,81 @@
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+export type ThemeMode = 'light' | 'dark';
+export type AccentColor = 'indigo' | 'teal' | 'rose' | 'amber' | 'slate';
+
+interface ThemeState {
+  mode: ThemeMode;
+  accent: AccentColor;
+  setMode: (mode: ThemeMode) => void;
+  setAccent: (accent: AccentColor) => void;
+  toggleMode: () => void;
+}
+
+export const ACCENT_TOKENS: Record<AccentColor, { base: string; light: string; label: string }> = {
+  indigo: { base: '#6366f1', light: '#e0e7ff', label: 'Indigo' },
+  teal:   { base: '#14b8a6', light: '#ccfbf1', label: 'Teal'   },
+  rose:   { base: '#f43f5e', light: '#ffe4e6', label: 'Rose'   },
+  amber:  { base: '#f59e0b', light: '#fef3c7', label: 'Amber'  },
+  slate:  { base: '#64748b', light: '#f1f5f9', label: 'Slate'  },
+};
+
+function applyTheme(mode: ThemeMode, accent: AccentColor) {
+  const root = document.documentElement;
+  const { base, light } = ACCENT_TOKENS[accent];
+
+  // Toggle dark class on <html>
+  root.classList.toggle('dark', mode === 'dark');
+
+  // Accent tokens (same in both modes)
+  root.style.setProperty('--color-accent', base);
+  root.style.setProperty('--color-accent-light', light);
+
+  // Surface tokens
+  if (mode === 'dark') {
+    root.style.setProperty('--color-bg',             '#0f172a');
+    root.style.setProperty('--color-surface',        '#1e293b');
+    root.style.setProperty('--color-surface-raised', '#263548');
+    root.style.setProperty('--color-border',         '#334155');
+    root.style.setProperty('--color-text-primary',   '#f1f5f9');
+    root.style.setProperty('--color-text-secondary', '#94a3b8');
+    root.style.setProperty('--color-text-muted',     '#64748b');
+  } else {
+    root.style.setProperty('--color-bg',             '#f8fafc');
+    root.style.setProperty('--color-surface',        '#ffffff');
+    root.style.setProperty('--color-surface-raised', '#f1f5f9');
+    root.style.setProperty('--color-border',         '#e2e8f0');
+    root.style.setProperty('--color-text-primary',   '#0f172a');
+    root.style.setProperty('--color-text-secondary', '#475569');
+    root.style.setProperty('--color-text-muted',     '#94a3b8');
+  }
+}
+
+export const useThemeStore = create<ThemeState>()(
+  persist(
+    (set, get) => ({
+      mode: 'light',
+      accent: 'indigo',
+      setMode: (mode) => {
+        set({ mode });
+        applyTheme(mode, get().accent);
+      },
+      setAccent: (accent) => {
+        set({ accent });
+        applyTheme(get().mode, accent);
+      },
+      toggleMode: () => {
+        const next = get().mode === 'light' ? 'dark' : 'light';
+        set({ mode: next });
+        applyTheme(next, get().accent);
+      },
+    }),
+    { name: 'fp-theme' }
+  )
+);
+
+/** Call once at app boot to hydrate CSS tokens from persisted state */
+export function initTheme() {
+  const { mode, accent } = useThemeStore.getState();
+  applyTheme(mode, accent);
+}

apps/client/tailwind.config.ts

@@ -0,0 +1,35 @@
+import type { Config } from 'tailwindcss';
+
+export default {
+  darkMode: 'class',
+  content: ['./index.html', './src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        // Map CSS custom properties → Tailwind utilities
+        bg:      'var(--color-bg)',
+        surface: 'var(--color-surface)',
+        border:  'var(--color-border)',
+        'text-primary':   'var(--color-text-primary)',
+        'text-secondary': 'var(--color-text-secondary)',
+        accent:  'var(--color-accent)',
+        'accent-light': 'var(--color-accent-light)',
+      },
+      fontFamily: {
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+      },
+      transitionProperty: {
+        theme: 'background-color, color, border-color, fill, stroke',
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.3s ease-out',
+        'slide-up': 'slideUp 0.3s ease-out',
+      },
+      keyframes: {
+        fadeIn:  { '0%': { opacity: '0' }, '100%': { opacity: '1' } },
+        slideUp: { '0%': { opacity: '0', transform: 'translateY(8px)' }, '100%': { opacity: '1', transform: 'translateY(0)' } },
+      },
+    },
+  },
+  plugins: [],
+} satisfies Config;

apps/client/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  },
+  "include": ["src"]
+}

apps/client/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: { '@': path.resolve(__dirname, './src') },
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': { target: 'http://localhost:3001', changeOrigin: true },
+    },
+  },
+});

apps/server/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "server",
+  "private": true,
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.3",
+    "multer": "^1.4.5-lts.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/multer": "^1.4.11",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3"
+  }
+}

apps/server/src/db/db.ts

@@ -0,0 +1,39 @@
+import { DatabaseSync, type StatementSync } from 'node:sqlite';
+import path from 'path';
+import fs from 'fs';
+
+const DATA_DIR = process.env.DATA_DIR ?? path.join(__dirname, '../../data');
+if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+
+const _db = new DatabaseSync(path.join(DATA_DIR, 'family.db'));
+
+_db.exec('PRAGMA journal_mode = WAL');
+_db.exec('PRAGMA foreign_keys = ON');
+
+/**
+ * Transaction wrapper matching better-sqlite3's API:
+ *   const fn = db.transaction((args) => { ... });
+ *   fn(args);  // runs inside BEGIN / COMMIT, rolls back on throw
+ */
+function transaction<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => TReturn
+): (...args: TArgs) => TReturn {
+  return (...args: TArgs): TReturn => {
+    _db.exec('BEGIN');
+    try {
+      const result = fn(...args);
+      _db.exec('COMMIT');
+      return result;
+    } catch (err) {
+      try { _db.exec('ROLLBACK'); } catch { /* ignore rollback errors */ }
+      throw err;
+    }
+  };
+}
+
+// Re-export db with the transaction helper attached, preserving full DatabaseSync interface
+const db = Object.assign(_db, { transaction });
+
+export type Db = typeof db;
+export type Statement = StatementSync;
+export default db;

apps/server/src/db/migrations/001_initial.ts

@@ -0,0 +1,120 @@
+export const id = '001_initial';
+
+export const up = `
+  -- ─── Family Members ───────────────────────────────────────────────
+  CREATE TABLE IF NOT EXISTS members (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    name       TEXT    NOT NULL,
+    color      TEXT    NOT NULL DEFAULT '#6366f1',
+    avatar     TEXT,
+    created_at TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  -- ─── App Settings (key/value store) ───────────────────────────────
+  CREATE TABLE IF NOT EXISTS settings (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+
+  -- ─── Calendar Events ──────────────────────────────────────────────
+  CREATE TABLE IF NOT EXISTS events (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    title       TEXT    NOT NULL,
+    description TEXT,
+    start_at    TEXT    NOT NULL,
+    end_at      TEXT    NOT NULL,
+    all_day     INTEGER NOT NULL DEFAULT 0,
+    recurrence  TEXT,
+    member_id   INTEGER REFERENCES members(id) ON DELETE SET NULL,
+    color       TEXT,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  -- ─── Shopping Lists ───────────────────────────────────────────────
+  CREATE TABLE IF NOT EXISTS shopping_lists (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    name       TEXT    NOT NULL,
+    created_at TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS shopping_items (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    list_id    INTEGER NOT NULL REFERENCES shopping_lists(id) ON DELETE CASCADE,
+    name       TEXT    NOT NULL,
+    quantity   TEXT,
+    checked    INTEGER NOT NULL DEFAULT 0,
+    member_id  INTEGER REFERENCES members(id) ON DELETE SET NULL,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  -- ─── Chores ───────────────────────────────────────────────────────
+  CREATE TABLE IF NOT EXISTS chores (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    title       TEXT    NOT NULL,
+    description TEXT,
+    member_id   INTEGER REFERENCES members(id) ON DELETE SET NULL,
+    recurrence  TEXT    NOT NULL DEFAULT 'none',
+    status      TEXT    NOT NULL DEFAULT 'pending',
+    due_date    TEXT,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS chore_completions (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    chore_id     INTEGER NOT NULL REFERENCES chores(id) ON DELETE CASCADE,
+    member_id    INTEGER REFERENCES members(id) ON DELETE SET NULL,
+    completed_at TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  -- ─── Meal Planner (one meal per day — dinner) ─────────────────────
+  CREATE TABLE IF NOT EXISTS meals (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    date        TEXT    NOT NULL,
+    title       TEXT    NOT NULL,
+    description TEXT,
+    recipe_url  TEXT,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(date)
+  );
+
+  -- ─── Message Board ────────────────────────────────────────────────
+  CREATE TABLE IF NOT EXISTS messages (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    member_id  INTEGER REFERENCES members(id) ON DELETE SET NULL,
+    body       TEXT    NOT NULL,
+    color      TEXT    NOT NULL DEFAULT '#fef08a',
+    emoji      TEXT,
+    pinned     INTEGER NOT NULL DEFAULT 0,
+    expires_at TEXT,
+    created_at TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  -- ─── Countdowns ───────────────────────────────────────────────────
+  CREATE TABLE IF NOT EXISTS countdowns (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    title             TEXT    NOT NULL,
+    target_date       TEXT    NOT NULL,
+    emoji             TEXT,
+    color             TEXT    NOT NULL DEFAULT '#6366f1',
+    show_on_dashboard INTEGER NOT NULL DEFAULT 1,
+    event_id          INTEGER REFERENCES events(id) ON DELETE CASCADE,
+    created_at        TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+
+  -- ─── Seed default settings ────────────────────────────────────────
+  INSERT OR IGNORE INTO settings (key, value) VALUES
+    ('theme',           'light'),
+    ('accent',          'indigo'),
+    ('photo_folder',    ''),
+    ('slideshow_speed', '6000'),
+    ('slideshow_order', 'random'),
+    ('idle_timeout',    '120000'),
+    ('time_format',     '12h'),
+    ('date_format',     'MM/DD/YYYY'),
+    ('weather_api_key', ''),
+    ('weather_location',''),
+    ('weather_units',   'imperial');
+
+  INSERT OR IGNORE INTO shopping_lists (id, name) VALUES (1, 'Groceries');
+`;

apps/server/src/db/runner.ts

@@ -0,0 +1,123 @@
+/**
+ * Migration runner
+ *
+ * How it works:
+ *  1. Creates a `_migrations` table on first run.
+ *  2. Loads all migration modules from ./migrations/ in filename order.
+ *  3. Skips any migration whose `id` is already recorded in `_migrations`.
+ *  4. Executes pending migrations inside individual transactions.
+ *  5. Records each successful migration with a timestamp.
+ *
+ * Adding a new migration:
+ *  - Create `apps/server/src/db/migrations/NNN_description.ts`
+ *  - Export `id` (string, matches filename) and `up` (SQL string).
+ *  - Optionally export `down` (SQL string) for rollback support.
+ *  - The runner picks it up automatically on next startup.
+ */
+
+import db from './db';
+import path from 'path';
+import fs from 'fs';
+
+interface Migration {
+  id: string;
+  up: string;
+  down?: string;
+}
+
+function bootstrap() {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      id         TEXT    PRIMARY KEY,
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+
+function loadMigrations(): Migration[] {
+  const dir = path.join(__dirname, 'migrations');
+  if (!fs.existsSync(dir)) return [];
+
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.ts') || f.endsWith('.js'))
+    .sort()
+    .map((file) => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const mod = require(path.join(dir, file)) as Migration;
+      if (!mod.id || !mod.up) {
+        throw new Error(`Migration ${file} must export 'id' and 'up'`);
+      }
+      return mod;
+    });
+}
+
+function getApplied(): Set<string> {
+  const rows = db.prepare('SELECT id FROM _migrations').all() as { id: string }[];
+  return new Set(rows.map((r) => r.id));
+}
+
+export function runMigrations() {
+  bootstrap();
+
+  const migrations = loadMigrations();
+  const applied = getApplied();
+  const pending = migrations.filter((m) => !applied.has(m.id));
+
+  if (pending.length === 0) {
+    console.log('[db] All migrations up to date.');
+    return;
+  }
+
+  console.log(`[db] Running ${pending.length} pending migration(s)...`);
+
+  for (const migration of pending) {
+    const apply = db.transaction(() => {
+      db.exec(migration.up);
+      db.prepare('INSERT INTO _migrations (id) VALUES (?)').run(migration.id);
+    });
+
+    try {
+      apply();
+      console.log(`[db]  ✓ Applied: ${migration.id}`);
+    } catch (err) {
+      console.error(`[db]  ✗ Failed:  ${migration.id}`, err);
+      throw err; // Abort startup on migration failure
+    }
+  }
+
+  console.log('[db] Migrations complete.');
+}
+
+export function rollback(targetId: string) {
+  const migrations = loadMigrations();
+  const applied = getApplied();
+
+  // Find all applied migrations after targetId in reverse order
+  const toRollback = migrations
+    .filter((m) => applied.has(m.id) && m.id > targetId)
+    .reverse();
+
+  if (toRollback.length === 0) {
+    console.log('[db] Nothing to roll back.');
+    return;
+  }
+
+  for (const migration of toRollback) {
+    if (!migration.down) {
+      console.warn(`[db]  ⚠ No down migration for: ${migration.id} — skipping`);
+      continue;
+    }
+    const revert = db.transaction(() => {
+      db.exec(migration.down!);
+      db.prepare('DELETE FROM _migrations WHERE id = ?').run(migration.id);
+    });
+    try {
+      revert();
+      console.log(`[db]  ✓ Rolled back: ${migration.id}`);
+    } catch (err) {
+      console.error(`[db]  ✗ Rollback failed: ${migration.id}`, err);
+      throw err;
+    }
+  }
+}

apps/server/src/index.ts

@@ -0,0 +1,45 @@
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import { runMigrations } from './db/runner';
+
+import membersRouter from './routes/members';
+import settingsRouter from './routes/settings';
+import eventsRouter from './routes/events';
+import shoppingRouter from './routes/shopping';
+import choresRouter from './routes/chores';
+import mealsRouter from './routes/meals';
+import messagesRouter from './routes/messages';
+import countdownsRouter from './routes/countdowns';
+import photosRouter from './routes/photos';
+
+// Run DB migrations on startup — aborts if any migration fails
+runMigrations();
+
+const app = express();
+const PORT = process.env.PORT ?? 3001;
+const CLIENT_ORIGIN = process.env.CLIENT_ORIGIN ?? 'http://localhost:5173';
+
+app.use(cors({ origin: CLIENT_ORIGIN }));
+app.use(express.json());
+
+app.use('/api/members',    membersRouter);
+app.use('/api/settings',   settingsRouter);
+app.use('/api/events',     eventsRouter);
+app.use('/api/shopping',   shoppingRouter);
+app.use('/api/chores',     choresRouter);
+app.use('/api/meals',      mealsRouter);
+app.use('/api/messages',   messagesRouter);
+app.use('/api/countdowns', countdownsRouter);
+app.use('/api/photos',     photosRouter);
+
+// Serve built client — in Docker the client dist is copied here at build time
+const CLIENT_DIST = path.join(__dirname, '../../client/dist');
+app.use(express.static(CLIENT_DIST));
+app.get('*', (_req, res) => {
+  res.sendFile(path.join(CLIENT_DIST, 'index.html'));
+});
+
+app.listen(PORT, () => {
+  console.log(`Family Planner running on http://0.0.0.0:${PORT}`);
+});

apps/server/src/routes/chores.ts

@@ -0,0 +1,71 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+router.get('/', (req, res) => {
+  const { member_id } = req.query;
+  let query = `
+    SELECT c.*, m.name as member_name, m.color as member_color,
+      (SELECT COUNT(*) FROM chore_completions cc WHERE cc.chore_id = c.id) as completion_count
+    FROM chores c
+    LEFT JOIN members m ON c.member_id = m.id
+  `;
+  if (member_id) {
+    query += ' WHERE c.member_id = ?';
+    return res.json(db.prepare(query + ' ORDER BY c.due_date ASC').all(member_id as string));
+  }
+  res.json(db.prepare(query + ' ORDER BY c.due_date ASC').all());
+});
+
+router.post('/', (req, res) => {
+  const { title, description, member_id, recurrence, due_date } = req.body;
+  if (!title?.trim()) return res.status(400).json({ error: 'Title is required' });
+  const result = db
+    .prepare('INSERT INTO chores (title, description, member_id, recurrence, due_date) VALUES (?, ?, ?, ?, ?)')
+    .run(title.trim(), description ?? null, member_id ?? null, recurrence ?? 'none', due_date ?? null);
+  res.status(201).json(db.prepare('SELECT * FROM chores WHERE id = ?').get(result.lastInsertRowid));
+});
+
+router.put('/:id', (req, res) => {
+  const existing = db.prepare('SELECT * FROM chores WHERE id = ?').get(req.params.id) as any;
+  if (!existing) return res.status(404).json({ error: 'Chore not found' });
+  const { title, description, member_id, recurrence, status, due_date } = req.body;
+  db.prepare('UPDATE chores SET title=?, description=?, member_id=?, recurrence=?, status=?, due_date=? WHERE id=?').run(
+    title?.trim() ?? existing.title,
+    description !== undefined ? description : existing.description,
+    member_id !== undefined ? member_id : existing.member_id,
+    recurrence ?? existing.recurrence,
+    status ?? existing.status,
+    due_date !== undefined ? due_date : existing.due_date,
+    req.params.id
+  );
+  res.json(db.prepare('SELECT * FROM chores WHERE id = ?').get(req.params.id));
+});
+
+router.delete('/:id', (req, res) => {
+  const result = db.prepare('DELETE FROM chores WHERE id = ?').run(req.params.id);
+  if (result.changes === 0) return res.status(404).json({ error: 'Chore not found' });
+  res.status(204).end();
+});
+
+router.post('/:id/complete', (req, res) => {
+  const { member_id } = req.body;
+  const chore = db.prepare('SELECT * FROM chores WHERE id = ?').get(req.params.id) as any;
+  if (!chore) return res.status(404).json({ error: 'Chore not found' });
+  db.prepare('INSERT INTO chore_completions (chore_id, member_id) VALUES (?, ?)').run(req.params.id, member_id ?? chore.member_id);
+  db.prepare("UPDATE chores SET status = 'done' WHERE id = ?").run(req.params.id);
+  res.json({ success: true });
+});
+
+router.get('/:id/completions', (req, res) => {
+  res.json(
+    db.prepare(`
+      SELECT cc.*, m.name as member_name FROM chore_completions cc
+      LEFT JOIN members m ON cc.member_id = m.id
+      WHERE cc.chore_id = ? ORDER BY cc.completed_at DESC
+    `).all(req.params.id)
+  );
+});
+
+export default router;

apps/server/src/routes/countdowns.ts

@@ -0,0 +1,48 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+router.get('/', (_req, res) => {
+  res.json(
+    db.prepare(`
+      SELECT c.*, e.title as event_title
+      FROM countdowns c
+      LEFT JOIN events e ON c.event_id = e.id
+      WHERE c.target_date >= date('now')
+      ORDER BY c.target_date ASC
+    `).all()
+  );
+});
+
+router.post('/', (req, res) => {
+  const { title, target_date, emoji, color, show_on_dashboard, event_id } = req.body;
+  if (!title?.trim() || !target_date) return res.status(400).json({ error: 'title and target_date are required' });
+  const result = db
+    .prepare('INSERT INTO countdowns (title, target_date, emoji, color, show_on_dashboard, event_id) VALUES (?, ?, ?, ?, ?, ?)')
+    .run(title.trim(), target_date, emoji ?? null, color ?? '#6366f1', show_on_dashboard !== false ? 1 : 0, event_id ?? null);
+  res.status(201).json(db.prepare('SELECT * FROM countdowns WHERE id = ?').get(result.lastInsertRowid));
+});
+
+router.put('/:id', (req, res) => {
+  const existing = db.prepare('SELECT * FROM countdowns WHERE id = ?').get(req.params.id) as any;
+  if (!existing) return res.status(404).json({ error: 'Countdown not found' });
+  const { title, target_date, emoji, color, show_on_dashboard } = req.body;
+  db.prepare('UPDATE countdowns SET title=?, target_date=?, emoji=?, color=?, show_on_dashboard=? WHERE id=?').run(
+    title?.trim() ?? existing.title,
+    target_date ?? existing.target_date,
+    emoji !== undefined ? emoji : existing.emoji,
+    color ?? existing.color,
+    show_on_dashboard !== undefined ? (show_on_dashboard ? 1 : 0) : existing.show_on_dashboard,
+    req.params.id
+  );
+  res.json(db.prepare('SELECT * FROM countdowns WHERE id = ?').get(req.params.id));
+});
+
+router.delete('/:id', (req, res) => {
+  const result = db.prepare('DELETE FROM countdowns WHERE id = ?').run(req.params.id);
+  if (result.changes === 0) return res.status(404).json({ error: 'Countdown not found' });
+  res.status(204).end();
+});
+
+export default router;

apps/server/src/routes/events.ts

@@ -0,0 +1,60 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+router.get('/', (req, res) => {
+  const { start, end } = req.query as { start?: string; end?: string };
+  let query = 'SELECT * FROM events';
+  const params: string[] = [];
+  if (start && end) {
+    query += ' WHERE start_at >= ? AND start_at <= ?';
+    params.push(start, end);
+  }
+  query += ' ORDER BY start_at ASC';
+  res.json(db.prepare(query).all(...params));
+});
+
+router.get('/:id', (req, res) => {
+  const row = db.prepare('SELECT * FROM events WHERE id = ?').get(req.params.id);
+  if (!row) return res.status(404).json({ error: 'Event not found' });
+  res.json(row);
+});
+
+router.post('/', (req, res) => {
+  const { title, description, start_at, end_at, all_day, recurrence, member_id, color } = req.body;
+  if (!title?.trim() || !start_at || !end_at)
+    return res.status(400).json({ error: 'title, start_at, and end_at are required' });
+  const result = db
+    .prepare(`INSERT INTO events (title, description, start_at, end_at, all_day, recurrence, member_id, color)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+    .run(title.trim(), description ?? null, start_at, end_at, all_day ? 1 : 0, recurrence ?? null, member_id ?? null, color ?? null);
+  res.status(201).json(db.prepare('SELECT * FROM events WHERE id = ?').get(result.lastInsertRowid));
+});
+
+router.put('/:id', (req, res) => {
+  const existing = db.prepare('SELECT * FROM events WHERE id = ?').get(req.params.id) as any;
+  if (!existing) return res.status(404).json({ error: 'Event not found' });
+  const { title, description, start_at, end_at, all_day, recurrence, member_id, color } = req.body;
+  db.prepare(`UPDATE events SET title=?, description=?, start_at=?, end_at=?, all_day=?, recurrence=?, member_id=?, color=? WHERE id=?`)
+    .run(
+      title?.trim() ?? existing.title,
+      description !== undefined ? description : existing.description,
+      start_at ?? existing.start_at,
+      end_at ?? existing.end_at,
+      all_day !== undefined ? (all_day ? 1 : 0) : existing.all_day,
+      recurrence !== undefined ? recurrence : existing.recurrence,
+      member_id !== undefined ? member_id : existing.member_id,
+      color !== undefined ? color : existing.color,
+      req.params.id
+    );
+  res.json(db.prepare('SELECT * FROM events WHERE id = ?').get(req.params.id));
+});
+
+router.delete('/:id', (req, res) => {
+  const result = db.prepare('DELETE FROM events WHERE id = ?').run(req.params.id);
+  if (result.changes === 0) return res.status(404).json({ error: 'Event not found' });
+  res.status(204).end();
+});
+
+export default router;

apps/server/src/routes/meals.ts

@@ -0,0 +1,37 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+// Get meals for a date range (e.g. ?start=2024-01-01&end=2024-01-31)
+router.get('/', (req, res) => {
+  const { start, end } = req.query as { start?: string; end?: string };
+  if (start && end) {
+    return res.json(db.prepare('SELECT * FROM meals WHERE date >= ? AND date <= ? ORDER BY date ASC').all(start, end));
+  }
+  res.json(db.prepare('SELECT * FROM meals ORDER BY date ASC').all());
+});
+
+router.get('/:date', (req, res) => {
+  const row = db.prepare('SELECT * FROM meals WHERE date = ?').get(req.params.date);
+  if (!row) return res.status(404).json({ error: 'No meal for this date' });
+  res.json(row);
+});
+
+router.put('/:date', (req, res) => {
+  const { title, description, recipe_url } = req.body as { title: string; description?: string; recipe_url?: string };
+  if (!title?.trim()) return res.status(400).json({ error: 'Title is required' });
+  db.prepare(`
+    INSERT INTO meals (date, title, description, recipe_url) VALUES (?, ?, ?, ?)
+    ON CONFLICT(date) DO UPDATE SET title=excluded.title, description=excluded.description, recipe_url=excluded.recipe_url
+  `).run(req.params.date, title.trim(), description ?? null, recipe_url ?? null);
+  res.json(db.prepare('SELECT * FROM meals WHERE date = ?').get(req.params.date));
+});
+
+router.delete('/:date', (req, res) => {
+  const result = db.prepare('DELETE FROM meals WHERE date = ?').run(req.params.date);
+  if (result.changes === 0) return res.status(404).json({ error: 'No meal for this date' });
+  res.status(204).end();
+});
+
+export default router;

apps/server/src/routes/members.ts

@@ -0,0 +1,47 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+router.get('/', (_req, res) => {
+  const rows = db.prepare('SELECT * FROM members ORDER BY name ASC').all();
+  res.json(rows);
+});
+
+router.get('/:id', (req, res) => {
+  const row = db.prepare('SELECT * FROM members WHERE id = ?').get(req.params.id);
+  if (!row) return res.status(404).json({ error: 'Member not found' });
+  res.json(row);
+});
+
+router.post('/', (req, res) => {
+  const { name, color, avatar } = req.body as { name: string; color?: string; avatar?: string };
+  if (!name?.trim()) return res.status(400).json({ error: 'Name is required' });
+  const result = db
+    .prepare('INSERT INTO members (name, color, avatar) VALUES (?, ?, ?)')
+    .run(name.trim(), color ?? '#6366f1', avatar ?? null);
+  const created = db.prepare('SELECT * FROM members WHERE id = ?').get(result.lastInsertRowid);
+  res.status(201).json(created);
+});
+
+router.put('/:id', (req, res) => {
+  const { name, color, avatar } = req.body as { name?: string; color?: string; avatar?: string };
+  const existing = db.prepare('SELECT * FROM members WHERE id = ?').get(req.params.id) as any;
+  if (!existing) return res.status(404).json({ error: 'Member not found' });
+  db.prepare('UPDATE members SET name = ?, color = ?, avatar = ? WHERE id = ?').run(
+    name?.trim() ?? existing.name,
+    color ?? existing.color,
+    avatar !== undefined ? avatar : existing.avatar,
+    req.params.id
+  );
+  const updated = db.prepare('SELECT * FROM members WHERE id = ?').get(req.params.id);
+  res.json(updated);
+});
+
+router.delete('/:id', (req, res) => {
+  const result = db.prepare('DELETE FROM members WHERE id = ?').run(req.params.id);
+  if (result.changes === 0) return res.status(404).json({ error: 'Member not found' });
+  res.status(204).end();
+});
+
+export default router;

apps/server/src/routes/messages.ts

@@ -0,0 +1,48 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+router.get('/', (_req, res) => {
+  res.json(
+    db.prepare(`
+      SELECT msg.*, m.name as member_name, m.color as member_color
+      FROM messages msg
+      LEFT JOIN members m ON msg.member_id = m.id
+      WHERE msg.expires_at IS NULL OR msg.expires_at > datetime('now')
+      ORDER BY msg.pinned DESC, msg.created_at DESC
+    `).all()
+  );
+});
+
+router.post('/', (req, res) => {
+  const { member_id, body, color, emoji, pinned, expires_at } = req.body;
+  if (!body?.trim()) return res.status(400).json({ error: 'Body is required' });
+  const result = db
+    .prepare('INSERT INTO messages (member_id, body, color, emoji, pinned, expires_at) VALUES (?, ?, ?, ?, ?, ?)')
+    .run(member_id ?? null, body.trim(), color ?? '#fef08a', emoji ?? null, pinned ? 1 : 0, expires_at ?? null);
+  res.status(201).json(db.prepare('SELECT * FROM messages WHERE id = ?').get(result.lastInsertRowid));
+});
+
+router.patch('/:id', (req, res) => {
+  const existing = db.prepare('SELECT * FROM messages WHERE id = ?').get(req.params.id) as any;
+  if (!existing) return res.status(404).json({ error: 'Message not found' });
+  const { body, color, emoji, pinned, expires_at } = req.body;
+  db.prepare('UPDATE messages SET body=?, color=?, emoji=?, pinned=?, expires_at=? WHERE id=?').run(
+    body?.trim() ?? existing.body,
+    color ?? existing.color,
+    emoji !== undefined ? emoji : existing.emoji,
+    pinned !== undefined ? (pinned ? 1 : 0) : existing.pinned,
+    expires_at !== undefined ? expires_at : existing.expires_at,
+    req.params.id
+  );
+  res.json(db.prepare('SELECT * FROM messages WHERE id = ?').get(req.params.id));
+});
+
+router.delete('/:id', (req, res) => {
+  const result = db.prepare('DELETE FROM messages WHERE id = ?').run(req.params.id);
+  if (result.changes === 0) return res.status(404).json({ error: 'Message not found' });
+  res.status(204).end();
+});
+
+export default router;

apps/server/src/routes/photos.ts

@@ -0,0 +1,61 @@
+import { Router } from 'express';
+import db from '../db/db';
+import fs from 'fs';
+import path from 'path';
+
+const router = Router();
+
+const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif', '.bmp']);
+
+function scanDir(dir: string): string[] {
+  if (!dir || !fs.existsSync(dir)) return [];
+  const results: string[] = [];
+  function recurse(current: string) {
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) recurse(full);
+      else if (IMAGE_EXTS.has(path.extname(entry.name).toLowerCase())) results.push(full);
+    }
+  }
+  recurse(dir);
+  return results;
+}
+
+// PHOTOS_DIR env var (set in Docker) overrides the DB setting.
+// This lets Unraid users bind-mount their photo library to /photos
+// without having to change the settings in the UI.
+function resolvePhotoFolder(): string {
+  if (process.env.PHOTOS_DIR) return process.env.PHOTOS_DIR;
+  const row = db.prepare("SELECT value FROM settings WHERE key = 'photo_folder'").get() as any;
+  return row?.value ?? '';
+}
+
+router.get('/', (_req, res) => {
+  const folder = resolvePhotoFolder();
+  const files = scanDir(folder);
+  res.json({ folder, count: files.length, files: files.map((f) => path.basename(f)) });
+});
+
+router.get('/file/:filename', (req, res) => {
+  const folder = resolvePhotoFolder();
+  if (!folder) return res.status(404).json({ error: 'Photo folder not configured' });
+
+  // Security: prevent path traversal
+  const filename = path.basename(req.params.filename);
+  const filepath = path.join(folder, filename);
+  if (!filepath.startsWith(folder)) return res.status(403).json({ error: 'Forbidden' });
+  if (!fs.existsSync(filepath)) return res.status(404).json({ error: 'File not found' });
+  res.sendFile(filepath);
+});
+
+// Return all photos as a flat list with their relative paths for the slideshow
+router.get('/slideshow', (_req, res) => {
+  const folder = resolvePhotoFolder();
+  const files = scanDir(folder);
+  const urls = files.map((f) => `/api/photos/file/${encodeURIComponent(path.relative(folder, f).replace(/\\/g, '/'))}`);
+  res.json({ count: urls.length, urls });
+});
+
+export default router;

apps/server/src/routes/settings.ts

@@ -0,0 +1,23 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+router.get('/', (_req, res) => {
+  const rows = db.prepare('SELECT key, value FROM settings').all() as { key: string; value: string }[];
+  const settings = Object.fromEntries(rows.map((r) => [r.key, r.value]));
+  res.json(settings);
+});
+
+router.patch('/', (req, res) => {
+  const updates = req.body as Record<string, string>;
+  const upsert = db.prepare('INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');
+  const updateMany = db.transaction((pairs: [string, string][]) => {
+    for (const [k, v] of pairs) upsert.run(k, String(v));
+  });
+  updateMany(Object.entries(updates));
+  const rows = db.prepare('SELECT key, value FROM settings').all() as { key: string; value: string }[];
+  res.json(Object.fromEntries(rows.map((r) => [r.key, r.value])));
+});
+
+export default router;

apps/server/src/routes/shopping.ts

@@ -0,0 +1,67 @@
+import { Router } from 'express';
+import db from '../db/db';
+
+const router = Router();
+
+// ── Lists ──────────────────────────────────────────────────────────────────
+router.get('/lists', (_req, res) => {
+  res.json(db.prepare('SELECT * FROM shopping_lists ORDER BY name ASC').all());
+});
+
+router.post('/lists', (req, res) => {
+  const { name } = req.body as { name: string };
+  if (!name?.trim()) return res.status(400).json({ error: 'Name is required' });
+  const result = db.prepare('INSERT INTO shopping_lists (name) VALUES (?)').run(name.trim());
+  res.status(201).json(db.prepare('SELECT * FROM shopping_lists WHERE id = ?').get(result.lastInsertRowid));
+});
+
+router.delete('/lists/:id', (req, res) => {
+  const result = db.prepare('DELETE FROM shopping_lists WHERE id = ?').run(req.params.id);
+  if (result.changes === 0) return res.status(404).json({ error: 'List not found' });
+  res.status(204).end();
+});
+
+// ── Items ──────────────────────────────────────────────────────────────────
+router.get('/lists/:listId/items', (req, res) => {
+  res.json(
+    db.prepare('SELECT * FROM shopping_items WHERE list_id = ? ORDER BY sort_order ASC, id ASC').all(req.params.listId)
+  );
+});
+
+router.post('/lists/:listId/items', (req, res) => {
+  const { name, quantity, member_id } = req.body as { name: string; quantity?: string; member_id?: number };
+  if (!name?.trim()) return res.status(400).json({ error: 'Name is required' });
+  const maxOrder = (db.prepare('SELECT MAX(sort_order) as m FROM shopping_items WHERE list_id = ?').get(req.params.listId) as any)?.m ?? 0;
+  const result = db
+    .prepare('INSERT INTO shopping_items (list_id, name, quantity, member_id, sort_order) VALUES (?, ?, ?, ?, ?)')
+    .run(req.params.listId, name.trim(), quantity ?? null, member_id ?? null, maxOrder + 1);
+  res.status(201).json(db.prepare('SELECT * FROM shopping_items WHERE id = ?').get(result.lastInsertRowid));
+});
+
+router.patch('/items/:id', (req, res) => {
+  const existing = db.prepare('SELECT * FROM shopping_items WHERE id = ?').get(req.params.id) as any;
+  if (!existing) return res.status(404).json({ error: 'Item not found' });
+  const { name, quantity, checked, member_id, sort_order } = req.body;
+  db.prepare('UPDATE shopping_items SET name=?, quantity=?, checked=?, member_id=?, sort_order=? WHERE id=?').run(
+    name?.trim() ?? existing.name,
+    quantity !== undefined ? quantity : existing.quantity,
+    checked !== undefined ? (checked ? 1 : 0) : existing.checked,
+    member_id !== undefined ? member_id : existing.member_id,
+    sort_order !== undefined ? sort_order : existing.sort_order,
+    req.params.id
+  );
+  res.json(db.prepare('SELECT * FROM shopping_items WHERE id = ?').get(req.params.id));
+});
+
+router.delete('/items/:id', (req, res) => {
+  const result = db.prepare('DELETE FROM shopping_items WHERE id = ?').run(req.params.id);
+  if (result.changes === 0) return res.status(404).json({ error: 'Item not found' });
+  res.status(204).end();
+});
+
+router.delete('/lists/:listId/items/checked', (req, res) => {
+  db.prepare('DELETE FROM shopping_items WHERE list_id = ? AND checked = 1').run(req.params.listId);
+  res.status(204).end();
+});
+
+export default router;

apps/server/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

docker-compose.yml

@@ -0,0 +1,38 @@
+services:
+  family-planner:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: family-planner
+    restart: unless-stopped
+
+    ports:
+      - "${PORT:-3001}:3001"
+
+    environment:
+      # App
+      PORT: 3001
+      TZ: ${TZ:-America/New_York}
+
+      # File paths inside the container
+      DATA_DIR: /data
+      PHOTOS_DIR: /photos
+
+      # Drop privileges to this UID/GID (Unraid: nobody=99, users=100)
+      PUID: ${PUID:-99}
+      PGID: ${PGID:-100}
+
+    volumes:
+      # Persistent database storage — map to wherever you keep appdata
+      - ${DATA_PATH:-./data}:/data
+
+      # Your photo library — mount read-only
+      # Change the left side to your actual photos folder path
+      - ${PHOTOS_PATH:-./photos}:/photos:ro
+
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3001/api/settings"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s

docker-entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+set -e
+
+# Resolve PUID/PGID (Unraid default: nobody=99, users=100)
+PUID=${PUID:-99}
+PGID=${PGID:-100}
+
+echo "[entrypoint] Starting Family Planner (PUID=${PUID}, PGID=${PGID})"
+
+# Create the app user/group if they don't already exist at the requested IDs
+if ! getent group appgroup > /dev/null 2>&1; then
+  addgroup -g "${PGID}" appgroup
+fi
+if ! getent passwd appuser > /dev/null 2>&1; then
+  adduser -D -u "${PUID}" -G appgroup appuser
+fi
+
+# Ensure /data is owned by the app user so SQLite can write
+mkdir -p /data
+chown -R "${PUID}:${PGID}" /data
+
+# Drop privileges and exec the CMD
+exec su-exec "${PUID}:${PGID}" "$@"

package.json

@@ -0,0 +1,16 @@
+{
+  "name": "family-planner",
+  "private": true,
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "concurrently \"pnpm --filter server dev\" \"pnpm --filter client dev\"",
+    "build": "pnpm --filter server build && pnpm --filter client build",
+    "start": "pnpm --filter server start"
+  },
+  "devDependencies": {
+    "concurrently": "^8.2.2"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  }
+}

pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - 'apps/*'

tsconfig.base.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  }
+}

unraid/family-planner.xml

@@ -0,0 +1,113 @@
+<?xml version="1.0"?>
+<Container version="2">
+  <!--
+    Unraid Community Applications Template
+    Family Planner — self-hosted family dashboard
+
+    To use: place this file in /boot/config/plugins/dockerMan/templates-user/
+    Then open the Docker tab → Add Container and select "Family Planner".
+  -->
+
+  <Name>family-planner</Name>
+  <Repository>ghcr.io/your-username/family-planner:latest</Repository>
+  <Registry>https://ghcr.io/your-username/family-planner</Registry>
+  <Network>bridge</Network>
+  <Shell>sh</Shell>
+  <Privileged>false</Privileged>
+
+  <Overview>
+    A sleek, modern family dashboard with a shared calendar, chore assignments,
+    shopping lists, dinner meal planner, message board, countdown timers,
+    and a full-screen photo slideshow screensaver.
+    Includes dark/light mode with accent color selection.
+  </Overview>
+
+  <Category>Productivity: Tools:</Category>
+  <WebUI>http://[IP]:[PORT:3001]/</WebUI>
+
+  <!-- Update this once you have a real icon hosted somewhere -->
+  <Icon>https://raw.githubusercontent.com/your-username/family-planner/main/unraid/icon.png</Icon>
+
+  <ExtraParams>--restart=unless-stopped</ExtraParams>
+
+  <!-- ── Ports ──────────────────────────────────────────────────────── -->
+  <Config
+    Name="Web UI Port"
+    Target="3001"
+    Default="3001"
+    Mode="tcp"
+    Description="Port the Family Planner web interface is served on."
+    Type="Port"
+    Display="always"
+    Required="true"
+    Mask="false">3001</Config>
+
+  <!-- ── Volumes ────────────────────────────────────────────────────── -->
+  <Config
+    Name="App Data"
+    Target="/data"
+    Default="/mnt/user/appdata/family-planner"
+    Mode="rw"
+    Description="Persistent storage for the SQLite database and app configuration. Must be writable."
+    Type="Path"
+    Display="always"
+    Required="true"
+    Mask="false">/mnt/user/appdata/family-planner</Config>
+
+  <Config
+    Name="Photos Path"
+    Target="/photos"
+    Default="/mnt/user/Photos"
+    Mode="ro"
+    Description="Path to your photo library. Subfolders are scanned automatically. Mounted read-only."
+    Type="Path"
+    Display="always"
+    Required="false"
+    Mask="false">/mnt/user/Photos</Config>
+
+  <!-- ── Environment variables ──────────────────────────────────────── -->
+  <Config
+    Name="PUID"
+    Target="PUID"
+    Default="99"
+    Mode=""
+    Description="User ID the container process runs as. Use 'id username' in the Unraid terminal to find your UID. Unraid default nobody=99."
+    Type="Variable"
+    Display="advanced"
+    Required="false"
+    Mask="false">99</Config>
+
+  <Config
+    Name="PGID"
+    Target="PGID"
+    Default="100"
+    Mode=""
+    Description="Group ID the container process runs as. Unraid default users=100."
+    Type="Variable"
+    Display="advanced"
+    Required="false"
+    Mask="false">100</Config>
+
+  <Config
+    Name="TZ"
+    Target="TZ"
+    Default="America/New_York"
+    Mode=""
+    Description="Your timezone. Used for correct date and time display. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"
+    Type="Variable"
+    Display="advanced"
+    Required="false"
+    Mask="false">America/New_York</Config>
+
+  <Config
+    Name="PORT"
+    Target="PORT"
+    Default="3001"
+    Mode=""
+    Description="Internal application port. Only change this if you have a port conflict and know what you are doing."
+    Type="Variable"
+    Display="advanced"
+    Required="false"
+    Mask="false">3001</Config>
+
+</Container>

unraid/install.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# ─────────────────────────────────────────────────────────────────────────────
+# Family Planner — Unraid CLI Install Script
+#
+# Run from the Unraid terminal:
+#   bash /path/to/install.sh
+#
+# Or pipe directly (once the image is published):
+#   curl -fsSL https://raw.githubusercontent.com/your-username/family-planner/main/unraid/install.sh | bash
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# ── Configurable defaults (edit these or they will be prompted) ───────────────
+IMAGE="${IMAGE:-ghcr.io/your-username/family-planner:latest}"
+CONTAINER_NAME="${CONTAINER_NAME:-family-planner}"
+HOST_PORT="${HOST_PORT:-3001}"
+DATA_PATH="${DATA_PATH:-/mnt/user/appdata/family-planner}"
+PHOTOS_PATH="${PHOTOS_PATH:-/mnt/user/Photos}"
+PUID="${PUID:-99}"
+PGID="${PGID:-100}"
+TZ="${TZ:-America/New_York}"
+
+# ── Helper ────────────────────────────────────────────────────────────────────
+info()    { echo -e "\033[1;34m[INFO]\033[0m  $*"; }
+success() { echo -e "\033[1;32m[OK]\033[0m    $*"; }
+warn()    { echo -e "\033[1;33m[WARN]\033[0m  $*"; }
+error()   { echo -e "\033[1;31m[ERROR]\033[0m $*" >&2; exit 1; }
+
+# ── Preflight ─────────────────────────────────────────────────────────────────
+command -v docker &>/dev/null || error "Docker is not installed or not in PATH."
+
+info "Family Planner — Unraid Installer"
+echo ""
+echo "  Container : $CONTAINER_NAME"
+echo "  Image     : $IMAGE"
+echo "  Port      : $HOST_PORT → 3001"
+echo "  Data path : $DATA_PATH"
+echo "  Photos    : $PHOTOS_PATH  (read-only)"
+echo "  PUID/PGID : $PUID/$PGID"
+echo "  TZ        : $TZ"
+echo ""
+read -rp "Proceed with these settings? [Y/n] " confirm
+confirm="${confirm:-Y}"
+[[ "$confirm" =~ ^[Yy]$ ]] || { info "Aborted."; exit 0; }
+
+# ── Stop and remove existing container if present ─────────────────────────────
+if docker inspect "$CONTAINER_NAME" &>/dev/null; then
+  warn "Container '$CONTAINER_NAME' already exists — stopping and removing it."
+  docker stop "$CONTAINER_NAME"  &>/dev/null || true
+  docker rm   "$CONTAINER_NAME"  &>/dev/null || true
+fi
+
+# ── Ensure data directory exists ──────────────────────────────────────────────
+mkdir -p "$DATA_PATH"
+success "Data directory ready: $DATA_PATH"
+
+# ── Pull the latest image ─────────────────────────────────────────────────────
+info "Pulling image: $IMAGE"
+docker pull "$IMAGE"
+
+# ── Run the container ─────────────────────────────────────────────────────────
+info "Starting container..."
+docker run -d \
+  --name "$CONTAINER_NAME" \
+  --restart unless-stopped \
+  -p "${HOST_PORT}:3001" \
+  -v "${DATA_PATH}:/data" \
+  -v "${PHOTOS_PATH}:/photos:ro" \
+  -e "PUID=${PUID}" \
+  -e "PGID=${PGID}" \
+  -e "TZ=${TZ}" \
+  -e "PORT=3001" \
+  -e "DATA_DIR=/data" \
+  -e "PHOTOS_DIR=/photos" \
+  "$IMAGE"
+
+# ── Verify startup ────────────────────────────────────────────────────────────
+info "Waiting for container to become healthy..."
+for i in $(seq 1 15); do
+  if docker exec "$CONTAINER_NAME" wget -qO- http://localhost:3001/api/settings &>/dev/null; then
+    success "Family Planner is up!"
+    break
+  fi
+  sleep 2
+  if [ "$i" -eq 15 ]; then
+    warn "Health check timed out. Check logs with: docker logs $CONTAINER_NAME"
+  fi
+done
+
+echo ""
+success "Installation complete."
+echo ""
+echo "  Open in browser : http://$(hostname -I | awk '{print $1}'):${HOST_PORT}"
+echo "  View logs       : docker logs -f $CONTAINER_NAME"
+echo "  Stop            : docker stop $CONTAINER_NAME"
+echo "  Update image    : docker pull $IMAGE && docker stop $CONTAINER_NAME && bash $(realpath "$0")"
+echo ""