Homeroom — iOS MVP

Status: scope document for v1. The landing page + browser demo exist today (see site/); everything below is planned, not built.

1. Audience & job to be done

Primary user: a parent — often a mom or a solo parent — of K–5 children who acts as the family's "default logistics person." They already cope; the job is to stop the coping from depending on memory and a fridge door.

Job: when a school notice arrives (email, flyer, app post, paper), convert it into a small set of discrete, dated, priced, approved actions — and make sure whoever is doing pickup that day can see them.

Explicitly out of scope for v1: reading the whole inbox automatically, replacing school comms apps, messaging/chat inside Homeroom, payments processing, and school- or district-facing tooling. We are a parent-side tool.

2. The golden path (first-run experience)

1. First launch → add children (name, grade, school — all optional except a display name).
2. User taps "Add a notice" → share sheet from Mail/Photos, or in-app: forward-address card, paste text, or photograph a flyer.
3. Extraction runs → review screen shows proposed action cards (BRING / PAY / SIGN / ATTEND), each with its source sentence highlighted.
4. Ambiguous items are rendered as questions ("How much for the eWallet — the notice says $10–15?"), never silently resolved.
5. User taps Approve per item (or Approve all).
6. Approved items land on the This week list, grouped by child and date; optional reminders + calendar entries.
7. One tap generates the caregiver brief — plain text, shareable via the system share sheet to SMS/WhatsApp/etc. Recipients need no app.

Success looks like: a user forwards one Monday-morning school email and finishes the week with everything handled, including the parts Grandpa did.

3. Screens (v1 = 6 screens + sheet flows)

No feed, no inbox, no social features. The app is a queue, not a destination.

4. Feature acceptance criteria (MVP cut)

Ingest

• Paste text, share-text extension, and photo/screenshot import all create a notice draft. Mail auto-forwarding to a per-family address creates the same draft server-side.
• Manual import must not require granting contacts, photos library (uses the system picker), or any mail provider.

Extraction

• Each notice produces 0..n action cards; every card shows the sentence(s) it was extracted from (source preview is mandatory — trust depends on it).
• Extracts: action type, title, child (matched to the user's child list or "unassigned"), date/due date, cost, and confidence.
• Ambiguity → explicit confirmation UI, never a guess. Unmatched child names or unclear dates are flagged, not dropped.

Approve & act

• Approving an item adds it to This week; un-approving removes it. Edits are tracked per field.
• Per item: optional local reminder (UserNotifications), optional Calendar write (EventKit, one event, user confirms).

Caregiver handoff

• Brief = plain-text summary of approved items for a chosen period, filtered to the children that caregiver covers. Share = system share sheet; recipient needs nothing installed.
• Caregiver permissions are scoped: each caregiver has a child list and may receive briefs; only guardians approve/edit items. (Invited co-guardians post-MVP.)

Multi-child & households

• Every extracted item carries a child assignment (required, defaulting to a per-item chooser when ambiguous); the home list filters per child and "all kids".
• Designed-for but not blocking v1: two households sharing one family account.

5. Architecture & Apple frameworks

• SwiftUI + SwiftData. iOS 17+ target. MVVM-lite; the sync layer is the only cross-cutting service.
• Extraction: a hosted extraction API (single endpoint: notice text → structured actions + citations). v1 sends only the notice text the user explicitly submitted — no account data, no mailbox. Provider and model are an open decision (§9); the client is provider-agnostic.
• OCR for photos: Apple Vision (VNRecognizeTextRequest) on-device — the photo and its pixels never leave the phone. The recognized text is then treated like any other notice: only the extracted text the user explicitly submits is sent, with consent, to the hosted extraction endpoint.
• Reminders: UserNotifications (local, time-of-day + day-before presets).
• Calendar: EventKit, write-only to the user-selected calendar.
• Sync across devices/caregivers: the controversial bit. v1 keeps the action list on the device; caregiver briefs travel as text via share sheet — no accounts required to ship the core loop. Multi-device sync and shared family state are staged behind a second release (§8).
• Backend: minimal — one extraction endpoint + optional forward-address ingestion mailbox. No user database in v1 beyond a device-scoped token.

6. Permission UX

Ask late, ask in context, degrade gracefully:

• Notifications: prompted only when the user toggles a reminder on.
• Photos: system PHPickerViewController — zero photo-library permission.
• Camera: only when "Photograph a notice" is used.
• Calendar: write-access prompt on first calendar export.
• Email: none. We never request mail access; forwarding is user-initiated (Mail rules / Gmail forwarding the user configures) or paste.

7. Data & API dependencies

Privacy posture for v1: notices are processed and stored server-side only when the user forwards/pastes them; photos are OCR'd on-device (pixels stay local), and only the user-confirmed recognized text is sent for extraction; sample/demo data is never a real family's data.

8. Build sequence

1. Sprint 0 — skeleton: SwiftUI shell, SwiftData models (Child, Notice, ActionItem, Caregiver), This-week list with manual entry. Goal: the list is useful even before extraction.
2. Extraction spike: hosted endpoint, prompt+schema with source citations; paste-import → review screen end-to-end on device.
3. Ambiguity UX: question cards, edit flows, approve semantics.
4. Reminders + calendar: EventKit/UserNotifications.
5. Photo import: Vision OCR → same review screen.
6. Forward address + caregiver brief: inbound mail webhook, brief composer, share sheet. Ship pilot.
7. Post-pilot: family accounts, two-household sharing, school-portal/Gmail opt-in integrations, localization.

9. Key unresolved decisions

• Extraction provider/model + eval harness. Needs a small gold set of real (anonymized) school notices; measure per-field precision, not vibes.
• Sync model. Family sharing is the feature most likely to expand scope; v1 deliberately ships text-brief handoff first.
• Inbound mail service for @in.homeroom addresses (ops burden vs. paste).
• Whether "pay" actions should deep-link into school payment portals later (out of v1).
• Localization/translation of notices — likely high value, unproven in pilot.

10. What already exists vs. planned

• Exists: brand + landing page with a working notice→list demo (pattern matching), .ics export, caregiver-brief composer, approve flow.
• Planned: everything in §3–§8. The demo's extraction rules are a UX stand-in, not the shipping model.