Files
parentcalendar/docs/SPEC.md
T
2026-11-05 12:40:38 -06:00

341 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ParentCalendar — Product & Technical Spec
Nov 5, 2026 · @Dan
## Overview
ParentCalendar turns a photo of a paper calendar into events you can trust, in under two minutes, every month. A vision model reads the page, you check and fix the results side by side with the photo, and the app exports a standard .ics file or keeps a subscribed feed up to date. Apple's iCloud Calendar is the primary target, and Google Calendar is also supported.
**The problem.** Every month brings several paper calendars: the school district calendar, the lunch menu, the classroom newsletter, sports and activity schedules. Each has a different layout, and typing them in by hand takes 20–40 minutes and is easy to get wrong.
**Goals**
- Capture to calendar in under 2 minutes for a typical one-page month grid.
- Extraction accurate enough that most months need only a few edits, and every guess is flagged.
- Works with Apple's iCloud Calendar first, and with Google Calendar, without a native app or calendar API login.
- Gets faster each month: the app remembers each source's layout, children and defaults.
- Self-hosted only, run directly with Python or as a Docker image. Your household comes first; other parents can get invited accounts in Phase 3: phone-first, nothing to install.
**Non-goals for v1**
- Two-way sync or editing events back from Apple or Google.
- Reading handwriting reliably (best effort, always flagged).
- Shared family accounts and permissions (planned for later).
- Native iOS and Android apps; a PWA comes first.
- Live edge detection in the browser and an offline capture queue. The phone's camera plus server-side cleanup covers capture.
- Calendars that aren't in English, until a real one turns up.
- A hosted service or a database server. This won't be sold as a service, so SQLite is the only backend.
**Users**
- Primary: a parent with one to four children, scanning three to six calendars a month on an iPhone.
- Secondary: a co-parent or grandparent who only subscribes to the resulting calendar.
## User flow
The monthly loop has six steps, and on a return visit steps 2 and 5 are mostly pre-filled from the source's saved profile.
1. **Capture.** Take a photo with the phone's camera or upload an image, PDF, or screenshot. The server handles crop and perspective correction. Multi-page capture is supported for two-sided sheets.
2. **Tag the source.** Pick a saved source ("Lincoln Elem — District", "Soccer U10") or create one, and pick the child or children it applies to. The source sets the date hint, children, relevance filter ("Grade 3", "Team Blue"), default category, and default times.
3. **Parse.** The server cleans up the image and sends it to the extraction model with the source's hints. The parsed result streams back in 10–30 seconds.
4. **Review and edit.** A split view shows the photo beside an editable event list. Low-confidence items come first and are highlighted on the photo. Events that don't match the relevance filter appear unchecked. You can edit, delete, merge, or add events, and bulk-apply changes (for example "all 'Early Release' events end at 1:30 PM").
5. **Choose a calendar.** Pick the calendar to export: a filtered view of events by child and, optionally, source. Set options such as alerts.
6. **Export.** Publishing confirms the checked events. Then either download an .ics file to import once, or publish to a subscribed feed that Apple and Google refresh on their own. On iPhone, opening the .ics shows "Add All" directly.
After the first month, the target is: open app, photo, confirm source, glance at the flagged items, publish.
To change an event later, such as a game that moved, open the calendar screen rather than the original scan (see Review and edit UI).
Lunch menus follow a different path. A scanned menu doesn't become calendar events. You go through it with your kids, each child picks the days to pack, and only those days reach the calendar (see Lunch menus).
## Architecture
Recommendation: a PWA front end, a small API with a background job queue, a vision LLM for extraction, and SQLite plus local disk. It runs as one process on one box, directly with Python or as a Docker image. There is no hosted version, and SQLite is the only backend.
```mermaid
flowchart LR
PWA["PWA client<br/>capture + review"] <--> API["API<br/>sources, export"]
API --> W["Job worker<br/>in the API process"]
W <--> M["Vision model<br/>Claude, JSON schema"]
W -->|raw events| V["Validators<br/>weekday, match existing"]
V --> DB[("Database<br/>SQLite + images")]
API <-->|read / write| DB
DB -->|confirmed events| ICS["ICS + feeds<br/>RFC 5545, webcal"]
ICS --> AC["Apple Calendar<br/>subscribe or import"]
ICS --> GC["Google Calendar<br/>From URL or import"]
```
The worker makes one extraction call per page, plus at most one retry if the response fails schema validation. The validators score what comes back, and only events you confirm in review reach the ICS service and the feeds.
| Component | Responsibility | Suggested tech |
| --- | --- | --- |
| PWA client | Photo capture and upload, review UI, lunch screen, calendar screen | TypeScript with SvelteKit or React + Vite, built to static files that the API serves; `<input type="file" accept="image/*,application/pdf">` for the camera and file picker |
| API | Uploads, sources, events, menus, export, feed endpoints; login from Phase 3 | Python with FastAPI |
| Job worker | Preprocess image, call extraction model, validate, store draft | A background task in the API process, driven by a simple `job` table |
| Extraction model | Image → structured events JSON | Claude (vision + structured output) as primary; model kept behind an interface so it can be swapped |
| Storage | Users, sources, scans, events, menus; original images | SQLite (WAL mode) through Python's `sqlite3`, with nightly backups; images on local disk |
| ICS service | Builds .ics files and serves per-calendar feeds | `icalendar` |
**Why a vision LLM rather than OCR + rules.** Paper calendars are month grids with merged cells, clip art, and items spilling across days. Plain OCR returns text without knowing which cell it belongs to, so you would need a grid detector and many per-layout rules. A vision model reads the layout and the text together and can return typed events directly. Classic OCR stays useful as a cross-check (see Parsing pipeline).
**Why a PWA.** One codebase covers iPhone and Android, the camera works from the browser, and there is no app store step for other parents. It can become a native app later through Capacitor if push notifications or share-sheet import become important.
**Packaging.** The repo can run two ways, using the same code and the same configuration:
- **Front-end build.** The source lives in `frontend/`, and `cd frontend && npm ci && npm run build` writes the built PWA to `static/`, which is gitignored. Re-run it after any front-end change. Node is needed only for this step, not to run the app.
- **Plain Python.** From a clone, build the front end once, then run `pip install -r requirements.txt && python main.py`. If `static/` is missing, `python main.py` exits with a message giving the build command. Prefer dependencies that ship binary wheels (Pillow, `opencv-python-headless`, `pypdfium2`) so no system packages are required. The Tesseract cross-check stays optional because it needs one.
- **Docker image.** A multi-stage Dockerfile builds the front end in a Node stage and copies `static/` into a Python image, which runs the same `pip install` and starts `python main.py`. Node isn't in the final image. The repo includes an example Compose file that mounts a data volume.
Both include `python main.py backup <destination>`, which runs SQLite's online backup and copies the images folder. Schema migrations are numbered SQL files applied at startup and tracked with `PRAGMA user_version`.
**Configuration.** All settings come from environment variables or a `.env` file:
| Variable | Purpose | Default or example |
| --- | --- | --- |
| `PUBLIC_URL` | Base URL for feed links, and the domain used in new event UIDs | Required; for example `https://calendar.example.com` |
| `DATA_DIR` | Database and images; must be a local disk | `./data` when run directly, `/data` in Docker |
| `ANTHROPIC_API_KEY` | Extraction model access | Required |
| `HOST`, `PORT` | Bind address | `127.0.0.1`, `8000` |
| `IMAGE_RETENTION_DAYS` | Days to keep images after publish | `90` |
**Deployment on the home server**
- The Docker image runs from one Compose file and binds to 127.0.0.1, and nginx proxies it on a subdomain set by `PUBLIC_URL`. Split the worker out only if parsing starts slowing the API.
- Keep the database and images on a local disk. SQLite's WAL mode isn't reliable on a network share.
- HTTPS is required. PWA features need a secure origin, and Google's servers fetch feeds over the public internet. Assume iCloud-synced subscriptions do too.
- Only `/feed/*` is public. Through Phases 1 and 2 the rest of the app is limited to your LAN and WireGuard, with no login code. Phase 3 adds login for invited parents.
- Put the feed path under the same CrowdSec bans and nginx rate limits as your other sites, and add an Uptime Kuma check for it.
- Back up nightly by scheduling `python main.py backup`.
**Repository.** The code lives in its own git repo, which can be public. The golden set holds real school calendars that could identify your family, so it stays out of that repo, either on the server or in a separate private repo.
## Parsing pipeline
The extraction step is one model call per page that returns strict JSON. Deterministic checks then run on that JSON, so the model never decides on its own that its output is correct.
1. **Preprocess.** Fix EXIF rotation, deskew and crop to the page, normalize contrast, and downscale to the model's best input size (long edge about 1500–2000 px). Render PDFs per page. Keep both the original and the processed image. The review screen shows the processed image, so `cell_bbox` lines up with it.
2. **Extract.** Send the image plus a prompt that includes any date hint, timezone, the source's relevance filter, known patterns, and few-shot corrections from earlier months. Require output that matches a JSON schema (below). The same response classifies the page: month grid, multi-month or year grid, list or table schedule, weekly planner, or menu. The source profile can pin the type after the first month.
3. **Validate.** Run code-level checks:
- The date exists, and in a grid, the weekday column matches the date's real weekday. This catches most off-by-one-row mistakes.
- Times parse, and any end time is after the start time. A missing end time is allowed.
- The dates fall inside the range on the page header and agree with any hint.
- Duplicates inside the scan are found.
4. **Match existing events.** Compare each event with the source's existing events on overlapping dates and a fuzzy title. Winter Break can appear on both the December and January pages, and a revised calendar can be scanned mid-month. A match keeps its `uid` and shows in review as unchanged or updated, and an uncertain match asks you.
5. **Score.** Combine the model's own confidence with any failed checks into a per-event score: high, review, or likely wrong. Optional cross-check: run Tesseract or a cloud OCR and flag events whose title text is not found on the page (a hallucination guard).
6. **Store a draft.** Save events as a draft scan, never straight to a calendar.
Example of the extraction schema the model must fill:
```json
{
"layout": "month_grid",
"date_range": { "start": "2026-12-01", "end": "2026-12-31" },
"events": [
{
"date": "2026-12-18",
"end_date": null,
"all_day": false,
"start_time": "13:30", "end_time": null,
"title": "Early Release",
"notes": "Dismissal 1:30 PM",
"kind": "no_school | early_release | event | game | practice | deadline",
"applies": true,
"page": 1,
"cell_bbox": [x, y, w, h],
"source_text": "EARLY RELEASE 1:30",
"confidence": 0.82
}
],
"menu_items": [
{
"date": "2026-12-18",
"items": ["Pizza", "Apple slices"],
"no_lunch": false,
"page": 1,
"cell_bbox": [x, y, w, h],
"confidence": 0.9
}
]
}
```
`source_text`, `page` and `cell_bbox` drive the review screen: tapping an event highlights where it came from on the photo. `cell_bbox` uses values from 0 to 1, relative to the processed page image. `date_range` covers whatever the page shows, from one month to a full school year. `applies` is false when an event doesn't match the source's relevance filter, and those events are still returned. Multi-day items such as "Winter Break Dec 21–Jan 2" become one event with `end_date`. Food goes in `menu_items`, never `events`, and a page that mixes both, such as a newsletter with a menu, fills both lists.
## Data model
The key decision is that every event has a permanent `uid`, created once and reused in every export, so refreshing a feed updates events instead of duplicating them. The second is that events are tagged with children, and a calendar is a filtered view of those tags, so one edit reaches every feed.
| Table | Key fields | Notes |
| --- | --- | --- |
| `user` | id, email, timezone, created\_at | Timezone defaults from the browser |
| `child` | id, user\_id, display\_name, color | A nickname or initials is enough; no birthdate |
| `source` | id, user\_id, name, layout\_type, default\_kind, default\_times (by kind), keep\_kinds\[\], applies\_filter, prompt\_notes, default\_calendar\_id | The per-source profile reused each month. Phase 1 uses name, children, applies\_filter and default\_calendar\_id; the rest fill in during Phase 2 |
| `scan` | id, source\_id, date\_start, date\_end, image\_keys\[\], image\_hash, status (queued, parsed, failed, abandoned, reviewed, published), error, model, cost\_tokens, created\_at | One upload of one or more pages. The date range is optional and can span many months |
| `event` | id, uid, scan\_id, source\_id, date, end\_date, all\_day, start, end, title, notes, location, kind, applies, page, cell\_bbox, source\_text, confidence, status (draft, confirmed, deleted), sequence, updated\_at | `sequence` increments on every change after publishing |
| `calendar` | id, user\_id, name, color, source\_ids\[\], feed\_token, alarm\_minutes, last\_exported\_at | A view by child and, optionally, by source. An empty `source_ids` means all sources. `feed_token` is the secret in the feed URL |
| `source_child`, `event_child`, `calendar_child` | Parent id, child\_id | One event, source or calendar can link to several children. A family calendar links all of them |
| `correction` | id, event\_id, field, before, after, created\_at | One row per edit. Powers undo in Phase 1 and few-shot examples in Phase 2 |
| `menu_item` | id, scan\_id, source\_id, date, items\[\], no\_lunch, page, cell\_bbox, confidence | One row per source and date. Never exported |
| `job` | id, scan\_id, status, attempts, run\_after | The background work queue |
More tables come later. Phase 2 adds `rule` (saved bulk rules) and `event_source` (links a merged event to each of its sources). Phase 3 adds `household` (shared access for a co-parent) and `invite` and `credential` for login. Recurring patterns would add `rrule` and `exdates` fields to `event`.
## Review and edit UI
The review screen is where trust is earned, so it shows the photo and the results together and puts the uncertain items first.
- **Layout.** On a phone, the photo sits above the event list, with a toggle to a month-grid preview. On desktop, they sit side by side. Tapping an event zooms the photo to its `cell_bbox`. Tapping a cell on the photo lists that day's events.
- **Ordering.** Sort events into five groups, by month within each group when a page spans several: "Needs a look" (low confidence or a failed check, each with the reason, such as "weekday mismatch"), "Updated" (matched an existing event, with the differences shown), "New", "Unchanged" (collapsed), and "Not for this child" (doesn't match the relevance filter; unchecked and collapsed, with a count, and one tap restores an event).
- **Editing.** Edit inline: title, date, all-day or timed, start and end, kind, children, notes. Swipe to delete. Add an event by long-pressing a date in the grid preview.
- **Bulk actions.** Select several events by kind or text and apply one change, such as setting times, changing kind, or deleting all `practice` items. From Phase 2, offer to save a bulk rule to the source ("always 1:30 PM for Early Release").
- **Preview.** A month grid shows the final result in the target calendar's color before export.
- **Keyboard and accessibility.** Full keyboard editing on desktop, 44 px touch targets, and confidence shown by an icon and label, not only by color.
- **Undo.** Every edit can be undone until publish. After publish, edits create a new `sequence` instead of a new event.
Each edit is saved as a `correction`, which powers undo and later becomes few-shot examples so the same source parses better next month.
**Calendar screen.** After publishing, browse events by child and calendar, and edit or delete them with the same form used in review. Feeds pick up the change on their next refresh, and the next .ics download includes it. The source photo stays available until the retention period ends.
## Lunch menus
A menu isn't a list of events. It's something you go through with your kids, and only their choices reach the calendar.
1. **Scan.** Capture the menu like any other page, using a source linked to the children who eat from it. Review corrects the items by date. Kids at different schools use separate menu sources.
2. **Pick.** The lunch screen shows the month with each day's menu, one child at a time. Each child taps the days to pack.
3. **Sync.** Each picked day creates a confirmed event titled "Pack lunch — <child>", with kind `pack_lunch`, tagged with that child. It's an all-day event on the school day, and it reaches every calendar that includes that child, by feed or .ics, like any other event.
**Rules**
- A pick is simply a `pack_lunch` event, one per child per date, so there's no separate picks table. The app creates these events and the model never returns them.
- Un-tapping a day marks its event deleted. Tapping it again restores the same `uid` with a new `sequence`.
- A day is greyed out and can't be picked when a confirmed `no_school` event tagged with that child covers it, or when the menu marks it `no_lunch`. If the greyed day is wrong, fix the `no_school` event on the calendar screen.
- If a `no_school` event arrives after a day was picked, the pick stays and is flagged on the lunch screen instead of being removed automatically.
- Scanning a revised menu replaces that source's items for those dates and keeps existing picks.
- Menu items never appear in a feed or .ics file.
## ICS export and import
Ship two export modes: a one-time .ics download in v1, and subscribed feeds in v2. For a monthly habit, feeds are the better default because you subscribe once and every later month and correction appears on its own, with no duplicates.
| | One-time .ics download | Subscribed feed (`webcal://`) |
| --- | --- | --- |
| Setup | None | Subscribe once per calendar |
| Corrections after export | Re-import may duplicate, depending on the client | Automatic on the next refresh |
| Apple Calendar | iPhone: open the file, tap "Add All". Mac: double-click or File → Import | iPhone: Settings → Calendar → Accounts → Add Subscribed Calendar. Mac: File → New Calendar Subscription (refresh interval can be set) |
| Google Calendar | Desktop web only: Settings → Import & export | Other calendars → From URL. Google sets the refresh rate and it can lag by hours |
| Best for | First release, people who want events copied in | Ongoing monthly use, co-parents and grandparents |
**Apple first.** iCloud Calendar is the main use case, so Apple behavior gets tested first and decides any tie. Three things need a real test on your devices in Phase 0:
- Whether a subscription reaches all your devices through iCloud, and from which device it has to be added.
- Whether re-importing an .ics with a matching `UID` updates the event or duplicates it, and whether `STATUS:CANCELLED` removes an imported event.
- What happens when one event, with one `UID`, is in both a child calendar and the family calendar on the same account.
**What a download contains.** By default, an .ics download holds events new or changed since that calendar's `last_exported_at`, including deletions as `STATUS:CANCELLED`. A "download everything" option covers a fresh start.
**ICS generation rules** (RFC 5545), handled by the library but tested explicitly:
- `VERSION:2.0`, a stable `PRODID`, and `X-WR-CALNAME` and `X-WR-TIMEZONE` for a readable calendar name.
- All-day events use `DTSTART;VALUE=DATE` with an **exclusive** `DTEND` (the day after). Multi-day breaks run through the day after the last day.
- Timed events use `TZID` with a matching `VTIMEZONE`, or UTC. Never use floating times.
- A timed event with no end time and no source default omits `DTEND`, which makes it zero-length. `DTEND` can't equal `DTSTART`, because RFC 5545 requires it to be later.
- A stable `UID` per event, in the form `<random id>@<domain from PUBLIC_URL>`, plus `DTSTAMP`, `SEQUENCE`, and `LAST-MODIFIED` on each change. The full `UID` is stored when the event is created, so changing `PUBLIC_URL` later never changes existing UIDs. It does change feed URLs, which means subscribing again.
- Feeds carry the past 12 months plus all future events. Deleted events stay in the feed as `STATUS:CANCELLED` for 30 days, then are dropped.
- `CATEGORIES` from `kind`, an optional `VALARM` from the calendar's alert default, CRLF line endings, 75-octet line folding, and escaped commas, semicolons, and newlines. Don't rely on `VALARM` in subscribed feeds: Google tends to ignore it and Apple can strip it, so test it on real devices.
**Feed endpoint.** `GET /feed/<feed_token>.ics` with no login. The token is long, random, and can be rotated. The response sets `ETag` and `Cache-Control` so clients that poll often stay cheap.
**Later option:** direct Google Calendar API and CalDAV writes for instant updates. These need OAuth and Google app verification, so they wait until feeds prove too slow.
## Built for monthly use
The second month should take half the effort of the first. These features are how that happens, roughly in priority order.
**Phase 2**
- **Source profiles.** Each source remembers its layout type, children, target calendar, default times by kind, which kinds to keep (for example, skip `deadline` items), and free-text prompt notes ("'A Day' and 'B Day' are rotation labels, not events").
- **Learning from corrections.** The last 5–10 corrections for a source go into the prompt as examples. Saved bulk rules ("Early Release → 13:30") run after extraction, before review.
- **Month-over-month diff.** Compare against the source's previous month: flag recurring items that disappeared ("Practice Tuesdays missing in December?") and new kinds of entries.
- **Smart dedupe across sources.** "No School — Thanksgiving" from the district calendar and the class newsletter merges into one event, linked to both sources.
- **Per-child calendars and colors.** One feed per child plus an optional combined family feed, so a co-parent can subscribe to just one child.
- **Mid-month corrections.** Re-scan a revised calendar and see only the differences, which then update existing events through their `UID`.
**After Phase 3**
- **Recurring patterns.** Detect weekly repeats ("every Tue and Thu practice 5:30") and offer an `RRULE` with exceptions instead of 9 separate events.
- **More ways to capture.** Batch capture of several sources at once, plus the share sheet (PWA Web Share Target) to send a PDF from email directly. As far as we know, iOS Safari doesn't support Web Share Target, so this may be Android-only. Later: a forwarding email address that parses attachments from the school.
- **Monthly nudge.** An optional reminder near the end of each month: "Your 4 sources usually publish around now." This needs email or web push.
## Privacy, security, and cost
These calendars reveal where children will be and when, so the defaults keep as little data as possible and keep it for as short a time as possible.
**Privacy**
- Store only a nickname for each child. No birthdates, schools, or photos of children are required.
- Delete images 90 days after publish by default (configurable), and delete abandoned scans' images on the same timer. Extracted events stay until the user deletes them, and feeds carry only the past 12 months plus future events.
- Use a model API whose terms rule out training on your inputs, and tell invited parents that their scans go to that provider.
- Account deletion removes everything and revokes all feeds right away.
**Security**
- Feed URLs are bearer secrets: at least 128 bits of randomness, one-tap rotation, rate limits, and no event details in server logs.
- Optional location stripping: leave `LOCATION` off events in shared feeds.
- LAN and WireGuard protect the app through Phase 2. Phase 3 adds login through passkeys or email magic links. Image uploads are always size-limited, type-checked, and re-encoded on the server.
- Treat model output as untrusted: validate against the schema and escape everything before rendering or writing ICS. Text printed on a flyer must not be able to change the prompt's instructions.
**Cost and limits**
- Main cost driver: one vision-model call per page, plus at most one retry. Measure real tokens per page in Phase 0 and store them on `scan.cost_tokens`.
- Keep cost down by downscaling images and caching by image hash, so an accidental re-upload costs nothing.
- Your API key pays for every scan, so once invited parents join in Phase 3, set a monthly page limit per user.
## Roadmap
Build in four phases, each ending with a gate, and prove extraction quality on real calendars before building any UI.
```mermaid
flowchart LR
P0["<b>Phase 0 - Prove extraction</b><br/>Start with 5-10 calendars<br/>Prompt + JSON schema<br/>Eval script, baseline<br/>Measure tokens per page<br/>Test Apple import + iCloud"]
P1["<b>Phase 1 - MVP for you</b><br/>Upload + parse<br/>Child + calendar pickers<br/>Review, highlights, bulk edits<br/>Match existing events<br/>Calendar + lunch screens<br/>.ics download<br/>Plain Python + Docker image"]
P2["<b>Phase 2 - Monthly loop</b><br/>Source profiles<br/>Webcal feeds<br/>Learn from edits<br/>Diff + dedupe"]
P3["<b>Phase 3 - Invite parents</b><br/>Passkeys + invites<br/>Per-user page limits<br/>Co-parent sharing<br/>Backups + monitoring"]
P0 -->|"Gate: accuracy targets met"| P1
P1 -->|"Gate: used for 2 real months"| P2
P2 -->|"Gate: repeat month under 2 min"| P3
```
Each arrow is the gate to the next phase. Phase 0 is only a script and a golden set, but it decides whether the rest is worth building. Phase 3 starts only when someone actually wants an account.
**Phase 0 gate.** Scored on clean printed pages:
| Measure | Target | What it protects |
| --- | --- | --- |
| No-edit rate | 85% or more | The under-2-minute goal |
| Events found (recall) | 95% or more | Missed events, which review can't flag |
| Errors that get flagged | 80% or more | Trust in events that aren't flagged |
These are starting points to adjust after the first baseline. With only 5–10 calendars, one bad page can swing them a lot, so treat them as a sanity check rather than a precise measurement.
## Testing strategy
Extraction quality is the product, so it gets an evaluation suite like any other critical component.
- **Golden set.** Start with 5–10 real calendars covering the main layouts, and add new ones each month until there are 20–30 of every layout type (grid, year grid, list, menu, sports, bad photos, PDFs), each with a hand-checked expected JSON. It stays outside the public repo.
- **Eval script.** Matches extracted events to expected ones by date and fuzzy title, then reports recall, precision, per-field accuracy (date, time, all-day, kind, applies), and the share of wrong events that were flagged. The no-edit rate is perfect events divided by expected events plus invented ones: 34 perfect out of 40 expected, plus 1 invented, is 34/41, or about 83%. Clean printed pages, bad photos, and menus are scored separately, with menus scored by date and items. Run it on every prompt or model change and fail on a regression. CI needs a secret to reach the private golden set, or the eval runs on the home server.
- **Validators.** Unit tests for the weekday check, multi-day ranges, multi-month pages, event matching, lunch-day greying and picks, timezone and DST edges, and month boundaries.
- **ICS.** Golden-file tests for generated output, an RFC 5545 validator in CI, and a manual import checklist per release: iPhone, Mac, sync across devices through iCloud, then Google web and Google on Android through a feed. The checklist includes how zero-length events display and whether alerts survive.
- **UI.** Playwright end-to-end tests for capture → review → export and menu → pick → export using fixture scans.
- **Packaging.** CI builds the front end, runs `pip install -r requirements.txt` in a clean virtual environment, and builds the Docker image, then starts both and checks that each serves the app.
## Open questions
- [x] Hosting: decided. Self-hosted only, run directly with Python or as a Docker image, with SQLite as the only backend.
- [x] Primary calendar: decided. Apple's iCloud Calendar comes first.
- [x] Server language: decided. Python with FastAPI; the PWA stays TypeScript.
- [x] Lunch menus: decided. They're kept separate, and only days a child picks become events.
- [x] Phase 0 accuracy gate: decided. See the targets under Roadmap.
- [x] Name and domain: decided. ParentCalendar, with the domain set through `PUBLIC_URL`.
- [ ] Do Apple's and Google's .ics imports update or duplicate events with a matching `UID`? Test in Phase 0, Apple first. The answer decides whether one-time import needs a warning.
- [ ] SvelteKit or React + Vite for the PWA? Decide at the start of Phase 1.