01 Product Overview

HealthBook AI is "your private family health workspace": a personal health record in which a family keeps original medical documents, turns them into structured, human-verified history, and records daily care. The internal code name is BabyCare (environment variables BABYCARE_*, package names babycare-*). The API describes itself as a personal health record and explicitly not a medical device (GET /api/health returns medical_device: false), and it never prescribes.

Purpose

The product answers one practical question for a family: what is actually documented about this person's health, and where is the original that proves it? It does that by:

• storing every original document (PDF, PNG, JPEG, HEIC) encrypted, with a SHA-256 fingerprint for duplicate detection;
• producing a candidate transcription with local OCR, which a guardian checks field by field before anything becomes a structured record;
• keeping a daily journal (fluids, diapers, stool and stool photos, medicines given, symptoms, sleep, activity, vitals);
• deriving reminders only from confirmed plans, and delivering them as a fixed generic sentence;
• producing designed PDF exports and scoped, expiring doctor links that carry a provenance label on every statement.

Users

User	How they reach the system	What they can do
Primary guardian (account owner)	Web app or Android app, email + password	Owns profiles; uploads documents; reviews and confirms transcriptions; manages sharing, cameras and account deletion. Only the primary guardian can manage sharing or account settings (guardian() in api/workflows.py).
Invited caregiver	Same apps, own account, invitation accepted	Access is granted per profile through caregiver_access. Role editor can write; any other role is read-only (own_patient() in api/security.py returns HTTP 403 "Read-only caregiver access" on writes).
Family profiles	Not a login; one patients row each	Each person (infant, toddler, child, teen, adult, senior) is a separate profile with its own timezone, modules and records. Disabling a module hides it; it never deletes or merges data between profiles (api/profiles.py).
Clinician receiving a share	Browser, doctor.html, no account	Opens an expiring, revocable link (optional PIN) that exposes only the explicitly selected records, view-only or with download as configured (api/share.py).

Example data used throughout this wiki is synthetic: profile "Alex Example", account demo@example.invalid, dates such as 2026-01-15.

Capability map

Capability	What the code implements	Wiki page
Overall structure	Web and Android clients, FastAPI API, PostgreSQL or SQLite, encrypted object store	System Architecture
Hosting	Render (Docker), Firebase Hosting, Supabase PostgreSQL and private bucket, pg_cron wake-up	Deployment Architecture
Backend structure	FastAPI app, routers, startup sequence	Backend Architecture
Web client	No-build vanilla JavaScript, service worker shell	Web Application Architecture
Android client	Expo / React Native, SecureStore token, offline queue	Android Application Architecture
Data model	Tables, encrypted columns, Alembic migrations	Database and Data Model
Accounts and sessions	PBKDF2 passwords, hashed session tokens, cookie (web) or bearer (mobile), CSRF header	Authentication and Session Security
Family workspace	Profiles, age groups, module switches, caregiver invitations	Family Profile Isolation
Document upload	Magic-byte type check, 12 MB / 35-page / 25-megapixel limits, encrypt-then-store	Medical Document Ingestion
OCR and review	PyMuPDF text layer, local Tesseract fallback, field-level review, explicit confirmation	OCR and Human Verification Workflow
Daily journal and calendar	Day, week and month views, unified timeline, observational analytics	Daily Health and Care Calendar
Medicines	Draft and verified prescriptions, revisions, administration events	Medicines and Administration Model
Vaccinations	Card entries, reference chart (never auto-activated), due versus given	Vaccination Model
Labs, growth, vitals	Observations, cultures, lab series and trends, growth entries, vitals journal	Labs, Growth and Longitudinal Health
Illness and lifetime history	Episodes, fever episodes, antibiotic courses and administrations, evidence links	Illness History and Lifetime Health
Stool photos	Timestamp recovery, descriptive colour observation with a fixed disclaimer	Stool Photo Pipeline
PDF export	ReportLab body plus PyMuPDF appendix of originals with source links	PDF Export Architecture
Share with doctor	Preview, ZIP package, clinician PDF, expiring links with access log	Share With Doctor Architecture
Reminders	Confirmed plans to notifications; Expo push and Web Push (VAPID)	Notifications and Reminder Architecture
Password reset	Generic response, 30-minute single-use token, HTTPS email API	Forgot Password and Email Architecture
Home camera	Local worker, derived events only, guardian review before the journal	Home Camera Architecture
Encryption	Fernet for clinical text columns and every stored file	Encryption and Private Storage
API	Route families and conventions	API Design
Security model	Headers, rate limits, origin checks, RLS lock-down	Security and Privacy Model
Tests	pytest on SQLite and PostgreSQL, Playwright browser specs	Testing and Validation
CI/CD	GitHub Actions, Docker, Android APK	Deployment and CI/CD
Stack	Libraries and pinned versions	Technology Stack
Rationale	ADR-style decisions	Design Decisions

Clinical safety rules

These rules are enforced in code, not only in interface copy. Every page that touches clinical data repeats the relevant subset.

Rule	Where it is enforced (examples)
Prescribed ≠ Scheduled ≠ Given/Administered. A prescription (medicines), a schedule (schedule_times, reminders) and an administration (medication_events, medication_administrations, antibiotic_administrations) live in separate tables. An administration row is never created from a schedule.	api/models.py, api/care_models.py, api/reminders.py
OCR extracted ≠ clinically verified. Extraction always sets needs_review; only rows the guardian includes and marks as checked against the original become history.	api/main.py (document_extract), api/workflows.py (review_confirm), api/review_validation.py
Vaccination due date ≠ vaccination administered. An undated row is never treated as given; the reference chart never activates reminders by itself.	api/review_validation.py, api/vaccination.py
Appointment/attendance ≠ treatment administered. A visit has its own status (planned, attended, postponed, cancelled); treatment administrations are recorded separately against a source document.	api/main.py (VisitUpdate), api/models.py (treatment_administrations)
Culture susceptibility ≠ antibiotic actually received. An antibiotic that appears only in a susceptibility table is not counted as an exposure; culture panels never become medicines.	api/lifetime.py, api/export_model.py
AI never prescribes or changes doses. OCR medication candidates carry dose_and_frequency: not_parsed; the opt-in vision prompt forbids inferring administration, diagnosing or prescribing.	api/extract.py, api/providers.py
Stool-image interpretation is observational only, not a diagnosis. Output describes colour families with a fixed disclaimer; a forbidden-word check blocks organism or disease terms.	api/care_vision.py, api/stool_intake.py
Parent-entered and clinician-documented records stay distinguishable. origin is clinician_document or parent_report; administration source is caregiver_report, nursing_chart, discharge_summary or copied_from_hospital_document.	api/lifetime_models.py, api/models.py
Structured records keep provenance to original documents. source_document_id and source_page are validated against the owning profile and the document's page count.	api/main.py (safe_doc)
A notification/reminder is never proof a dose was given. Push text is one generic sentence; delivery status lives in notifications, never in administration tables.	api/push_web.py, api/worker.py, api/reminders.py

Implementation

api/main.py, api/profiles.py, api/security.py, api/workflows.py, api/share.py, web/, mobile/.

Related pages

Home · System Architecture · Security and Privacy Model · Design Decisions · Limitations · Roadmap