# Family Planner — Project Reference

A self-hosted family dashboard designed for always-on display (wall tablet, TV, Unraid server). Manages calendars, chores, shopping, meals, a message board, countdowns, and a photo screensaver — all in one Docker container with zero external services required.

---

## Tech Stack

| Layer | Technology |
|---|---|
| **Runtime** | Node.js 22, Docker (Alpine) |
| **Backend** | Express 4, TypeScript 5 |
| **Database** | Node.js built-in SQLite (`node:sqlite`), WAL mode |
| **File uploads** | Multer |
| **Frontend** | React 18, TypeScript 5, Vite 5 |
| **Styling** | Tailwind CSS 3, CSS custom properties (theme tokens) |
| **Animation** | Framer Motion 11 |
| **State / data** | TanStack Query 5, Zustand 4 |
| **Routing** | React Router 6 |
| **Icons** | Lucide React |
| **Date utils** | date-fns 3 |
| **Package manager** | pnpm (workspaces monorepo) |
| **CI/CD** | Gitea Actions → Docker build & push to private registry |
| **Deployment target** | Unraid (Community Applications / CLI install) |

---

## Repository Structure

```
family-planner/
├── apps/
│   ├── client/                     # React frontend
│   │   └── src/
│   │       ├── components/
│   │       │   ├── layout/
│   │       │   │   └── AppShell.tsx        # Sidebar, mobile drawer, page wrapper
│   │       │   ├── screensaver/
│   │       │   │   └── Screensaver.tsx     # Idle screensaver w/ Ken Burns slideshow
│   │       │   └── ui/                     # Design-system primitives
│   │       │       ├── Avatar.tsx
│   │       │       ├── Badge.tsx
│   │       │       ├── Button.tsx
│   │       │       ├── Input.tsx
│   │       │       ├── Modal.tsx
│   │       │       ├── Select.tsx
│   │       │       ├── Textarea.tsx
│   │       │       └── ThemeToggle.tsx
│   │       ├── features/                   # Feature-scoped sub-components
│   │       │   ├── calendar/
│   │       │   ├── chores/
│   │       │   └── shopping/
│   │       ├── hooks/
│   │       │   └── useMembers.ts
│   │       ├── lib/
│   │       │   └── api.ts                  # Axios instance + all API types
│   │       ├── pages/                      # One file per route
│   │       │   ├── Calendar.tsx            ✅ complete
│   │       │   ├── Chores.tsx              ✅ complete
│   │       │   ├── Photos.tsx              ✅ complete
│   │       │   ├── Settings.tsx            ✅ complete
│   │       │   ├── Members.tsx             ✅ complete
│   │       │   ├── Shopping.tsx            ✅ complete
│   │       │   ├── Dashboard.tsx           🔲 stub
│   │       │   ├── Meals.tsx               🔲 stub
│   │       │   ├── Board.tsx               🔲 stub
│   │       │   └── Countdowns.tsx          🔲 stub
│   │       └── store/
│   │           ├── settingsStore.ts        # Zustand settings (synced from DB)
│   │           └── themeStore.ts           # Zustand theme + CSS token application
│   └── server/
│       └── src/
│           ├── db/
│           │   ├── db.ts                   # node:sqlite wrapper + transaction helper
│           │   ├── runner.ts               # Sequential migration runner
│           │   └── migrations/
│           │       └── 001_initial.ts      # Full schema + seed data
│           ├── routes/                     # One router file per domain
│           │   ├── members.ts              ✅ full CRUD
│           │   ├── settings.ts             ✅ key/value GET + PATCH
│           │   ├── events.ts               ✅ full CRUD + date-range filter
│           │   ├── shopping.ts             ✅ full CRUD (lists + items)
│           │   ├── chores.ts               ✅ full CRUD + completions
│           │   ├── meals.ts                ✅ full CRUD (upsert by date)
│           │   ├── messages.ts             ✅ full CRUD + pin/expiry
│           │   ├── countdowns.ts           ✅ full CRUD + event link
│           │   └── photos.ts               ✅ list, upload, serve, delete, slideshow
│           └── index.ts                    # Express app + static client serve
├── .gitea/workflows/
│   └── docker-build.yml            # Push to main → build + push Docker image
├── Dockerfile                      # Multi-stage: client build → server build → runtime
├── docker-compose.yml
├── docker-entrypoint.sh            # PUID/PGID ownership fix + app start
├── UNRAID.md                       # Full Unraid install guide (GUI + CLI)
├── INSTALL.md
└── PROJECT.md                      # ← this file
```

---

## Database Schema

All tables live in a single SQLite file at `$DATA_DIR/family.db`.

| Table | Purpose |
|---|---|
| `members` | Family member profiles (name, color, avatar) |
| `settings` | Key/value app configuration store |
| `events` | Calendar events (all-day, timed, recurrence field) |
| `shopping_lists` | Named shopping lists |
| `shopping_items` | Line items (quantity, checked state, member assignment) |
| `chores` | Chore definitions (recurrence, due date, status) |
| `chore_completions` | Completion history per chore per member |
| `meals` | One dinner entry per calendar date (upsert pattern) |
| `messages` | Board messages (color, emoji, pin, optional expiry) |
| `countdowns` | Countdown timers (linked to calendar event or standalone) |

Photos are stored as files on disk — no database table. The configured folder path lives in `settings.photo_folder` (or `$PHOTOS_DIR` env var in Docker).

---

## Completed Features

### Infrastructure
- [x] pnpm monorepo (`apps/client` + `apps/server`)
- [x] Multi-stage Dockerfile — client build, server build, minimal Alpine runtime
- [x] Sequential migration runner — aborts startup on failure
- [x] Gitea Actions CI — builds and pushes Docker image on push to `main`
- [x] Unraid install guide (GUI template + CLI script)
- [x] PUID/PGID support via `docker-entrypoint.sh`
- [x] `tini` for correct PID 1 signal handling

### Design System
- [x] CSS custom property token system (surface, border, text, accent)
- [x] Light / dark mode with smooth transitions
- [x] 5 accent colours (Indigo, Teal, Rose, Amber, Slate)
- [x] Collapsible sidebar with animated labels
- [x] Mobile overlay drawer
- [x] Primitive component library: `Button`, `Input`, `Textarea`, `Select`, `Modal`, `Avatar`, `Badge`, `ThemeToggle`
- [x] Page entry/exit animations via Framer Motion

### Members
- [x] Create, edit, delete family members
- [x] Custom display colour per member
- [x] Avatar field
- [x] Member assignment used throughout app (events, chores, shopping items)

### Settings
- [x] Theme mode + accent colour (persisted to DB and applied via CSS tokens)
- [x] Photo folder path (absolute path or Docker bind-mount override)
- [x] Slideshow speed (3 s – 15 s)
- [x] Slideshow order (random / sequential / newest first)
- [x] Idle timeout (1 min – 10 min, or disabled)
- [x] Time format (12h / 24h)
- [x] Date format (MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD)
- [x] Weather API key, location, units (stored — widget pending)

### Calendar
- [x] Month grid view with event dots
- [x] Per-day event list modal
- [x] Create / edit / delete events
- [x] All-day events
- [x] Member colour coding
- [x] Custom event colour override
- [x] Recurrence field (stored, display only)
- [x] Month navigation with slide animation

### Shopping
- [x] Multiple named lists
- [x] Add / edit / delete items with optional quantity
- [x] Check / uncheck items (checked items grouped separately)
- [x] Clear all checked items
- [x] Member assignment per item
- [x] Keyboard shortcut: Enter to add
- [x] Create / delete lists

### Chores
- [x] Create / edit / delete chores
- [x] Title, description, due date, recurrence label, member assignment
- [x] Status: pending / done
- [x] Filter by status or by member
- [x] Completion count badge
- [x] Completion history recorded in `chore_completions`

### Photos
- [x] Batch upload via browser (drag & drop anywhere on page, or file picker)
- [x] Multi-file selection — up to 200 files per upload, 50 MB each
- [x] Server saves to configured photo folder root (multer disk storage)
- [x] Filenames sanitised + timestamp-suffixed to prevent collisions
- [x] Responsive photo grid (2 – 6 columns)
- [x] Hover overlay: filename label + delete button
- [x] Click to open full-screen lightbox
- [x] Lightbox: prev / next navigation, keyboard arrows, Esc to close, photo counter
- [x] Permanent delete with confirmation modal
- [x] Graceful "not configured" state with link to Settings
- [x] Empty state with prominent upload drop zone
- [x] Recursive folder scan (pre-existing subdirectory photos appear in slideshow)
- [x] Path traversal protection on all file-serving and delete endpoints

### Screensaver
- [x] Activates automatically after configurable idle timeout
- [x] Idle detection: `mousemove`, `mousedown`, `keydown`, `touchstart`, `scroll`
- [x] Ken Burns effect — 8 presets alternating zoom-in / zoom-out with diagonal, vertical, and horizontal pan
- [x] Crossfade between photos (1.2 s, `AnimatePresence mode="sync"`)
- [x] Respects `slideshow_order` setting (random shuffled each cycle, sequential, newest first)
- [x] Respects `slideshow_speed` setting (3 s – 15 s)
- [x] Next photo preloaded while current is displayed
- [x] Live clock overlay — large thin numerals, responsive font size (`clamp`)
- [x] Clock respects `time_format` setting (12h with AM/PM, 24h)
- [x] Date line below clock
- [x] "Tap to dismiss" hint fades out after 3.5 s
- [x] Dismiss on click, touch, or any keypress
- [x] No-photo fallback: dark gradient + clock only
- [x] Gradient scrim over photos for clock legibility
- [x] `z-[200]` — renders above all modals and UI

---

## In Progress / Stubs

These pages have **complete backend APIs** but their frontend is a placeholder `<div>`.

### Meals `🔲`
**Backend:** `GET /api/meals`, `PUT /api/meals/:date` (upsert), `DELETE /api/meals/:date`
**Planned UI:**
- Weekly grid (Mon – Sun) showing the current week's dinner plan
- Click any day to open a quick-edit modal (title, description, recipe URL)
- Week navigation (prev / next)
- "No meal planned" empty state per day
- Recipe link button when `recipe_url` is set

### Message Board `🔲`
**Backend:** `GET /api/messages`, `POST`, `PATCH /:id`, `DELETE /:id`
**Planned UI:**
- Sticky-note card grid
- Custom card background colour + emoji
- Pin important messages to the top
- Optional expiry (auto-removed after date)
- Member attribution
- Quick compose at the bottom

### Countdowns `🔲`
**Backend:** `GET /api/countdowns`, `POST`, `PUT /:id`, `DELETE /:id`
**Planned UI:**
- Card grid showing days remaining to each target date
- Large number + label per card
- Custom colour and emoji per countdown
- Optional link to a calendar event
- Flag to show on Dashboard
- Completed countdowns hidden (target date in the past is filtered server-side)

### Dashboard `🔲`
**Planned UI (depends on all modules above being complete):**
- Today's date + time (respects `time_format` / `date_format`)
- Weather widget (OpenWeatherMap — API key + location already in Settings)
- Upcoming calendar events (next 3–5)
- Today's meal plan
- Active chore count / completion summary
- Shopping list item count
- Pinned messages preview
- Countdowns flagged `show_on_dashboard`
- Quick-action buttons to each module

---

## Roadmap

### Near-term (next sessions)
- [ ] **Meals page** — weekly dinner grid with modal editor
- [ ] **Message Board page** — sticky-note UI with compose, pin, expiry
- [ ] **Countdowns page** — day-count cards with create/edit/delete
- [ ] **Dashboard** — wire up all modules once the above are complete
- [ ] **Weather widget** — OpenWeatherMap fetch on the Dashboard using stored credentials

### Medium-term
- [ ] **Recurring chore automation** — auto-reset status to `pending` on schedule instead of just storing the recurrence label
- [ ] **Calendar recurrence expansion** — expand recurring events into visible instances on the grid
- [ ] **Meal recipe import** — paste a URL, scrape title from `<title>` or Open Graph
- [ ] **Shopping list reorder** — drag-and-drop reorder items (sort_order column already in schema)
- [ ] **Member avatar upload** — upload image instead of text initials
- [ ] **Screensaver burn-in mitigation** — slowly drift clock position across OLED panels

### Future / Nice-to-have
- [ ] **PWA manifest + service worker** — installable on tablet home screen, offline cache for static assets
- [ ] **Push notifications** — chore reminders, upcoming events (requires service worker)
- [ ] **Multi-user auth** — PIN-per-member or password gate (currently open LAN access only)
- [ ] **Backup / restore UI** — download `family.db` and restore from file in the app
- [ ] **Community Applications XML template** — publish official Unraid CA template
- [ ] **Dark mode auto-schedule** — switch theme at sunrise/sunset based on location
- [ ] **Grocery store integration** — import a shared list from a URL or barcode scan

---

## API Reference

All endpoints are under `/api`. The server also serves the built React client at `/` (catch-all `index.html`).

| Method | Path | Description |
|---|---|---|
| GET | `/api/members` | List all members |
| POST | `/api/members` | Create member |
| PUT | `/api/members/:id` | Update member |
| DELETE | `/api/members/:id` | Delete member |
| GET | `/api/settings` | Get all settings as flat object |
| PATCH | `/api/settings` | Update one or more settings keys |
| GET | `/api/events` | List events (optional `?start=&end=` ISO range) |
| POST | `/api/events` | Create event |
| PUT | `/api/events/:id` | Update event |
| DELETE | `/api/events/:id` | Delete event |
| GET | `/api/shopping/lists` | List all shopping lists |
| POST | `/api/shopping/lists` | Create list |
| DELETE | `/api/shopping/lists/:id` | Delete list + cascade items |
| GET | `/api/shopping/lists/:id/items` | List items for a list |
| POST | `/api/shopping/lists/:id/items` | Add item |
| PATCH | `/api/shopping/lists/:id/items/:itemId` | Update item (check, rename, etc.) |
| DELETE | `/api/shopping/lists/:id/items/:itemId` | Delete item |
| DELETE | `/api/shopping/lists/:id/items/checked` | Clear all checked items |
| GET | `/api/chores` | List chores with member info + completion count |
| POST | `/api/chores` | Create chore |
| PUT | `/api/chores/:id` | Update chore |
| PATCH | `/api/chores/:id/complete` | Record a completion |
| DELETE | `/api/chores/:id` | Delete chore |
| GET | `/api/meals` | List meals (optional `?start=&end=` date range) |
| PUT | `/api/meals/:date` | Upsert meal for a date (YYYY-MM-DD) |
| DELETE | `/api/meals/:date` | Remove meal for a date |
| GET | `/api/messages` | List non-expired messages (pinned first) |
| POST | `/api/messages` | Create message |
| PATCH | `/api/messages/:id` | Update message |
| DELETE | `/api/messages/:id` | Delete message |
| GET | `/api/countdowns` | List future countdowns (ordered by date) |
| POST | `/api/countdowns` | Create countdown |
| PUT | `/api/countdowns/:id` | Update countdown |
| DELETE | `/api/countdowns/:id` | Delete countdown |
| GET | `/api/photos` | List all photos recursively `{ configured, count, photos }` |
| GET | `/api/photos/slideshow` | Same list, optimised for screensaver use |
| GET | `/api/photos/file/*` | Serve a photo by relative path (path traversal protected) |
| POST | `/api/photos/upload` | Upload photos (`multipart/form-data`, field `photos`) |
| DELETE | `/api/photos/file/*` | Delete a photo by relative path |

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3001` | HTTP port the server listens on |
| `DATA_DIR` | `../../data` (dev) / `/data` (Docker) | SQLite database directory |
| `PHOTOS_DIR` | *(unset)* | Override photo folder path (ignores DB setting when set) |
| `CLIENT_ORIGIN` | `http://localhost:5173` | CORS allowed origin (dev only) |
| `PUID` | `99` | User ID for file ownership in container |
| `PGID` | `100` | Group ID for file ownership in container |
| `TZ` | `UTC` | Container timezone |
| `NODE_NO_WARNINGS` | `1` | Suppresses experimental SQLite API warning |

---

## Local Development

```bash
# Install deps
pnpm install

# Start both client (port 5173) and server (port 3001) with hot reload
pnpm dev

# Type-check client
pnpm --filter client exec tsc --noEmit

# Build for production
pnpm build
```

The Vite dev server proxies `/api/*` to `localhost:3001`, so you can develop against the live server without CORS issues.

---

## Docker Build

```bash
# Build image locally
docker build -t family-planner .

# Run locally
docker run -p 3001:3001 \
  -v $(pwd)/data:/data \
  -v /path/to/photos:/photos \
  family-planner
```

The Gitea Actions workflow builds and pushes automatically on every push to `main`.