module-spec · supabase_json
Patient Visit Advocate module-spec M-01
module-spec artifact · for Patient Visit Advocate · phase M-01 · status approved
Agent Handoff
Start Here
module-spec artifact · for Patient Visit Advocate · phase M-01 · status approved
Completion Evidence
- Every MVP entity has purpose, ownership, privacy classification, required fields, user controls, and monetization support documented.
- Structured user-confirmed memory is separated from generated inferences and raw chat.
- Caregiver access is represented as a first-class permission object even if UI ships later.
- Analytics boundary explicitly forbids health text and appointment details.
- M-01 supports the free, paid individual, caregiver/family, and appointment-pack monetization paths without requiring schema redesign.
Goal
Define the structured data contracts that turn Patient Visit Advocate from a one-off chat experience into a memory-backed appointment preparation system.
Structured Payload
Machine-readable source fields
goal
Define the structured data contracts that turn Patient Visit Advocate from a one-off chat experience into a memory-backed appointment preparation system.
module
id
M-01
name
Visit Data Model
status
draft
entities
| name | fields | purpose | ownership | user controls | monetization support |
|---|---|---|---|---|---|
| PatientProfile | - id: name: string, type: string, notes: string, required: boolean - owner_user_id: name: string, type: string, notes: string, required: boolean - display_name: name: string, type: string, notes: string, required: boolean - relationship_to_owner: name: string, type: string, notes: string, required: boolean - birth_year_optional: name: string, type: string, notes: string, required: boolean - baseline_context: name: string, type: string, notes: string, required: boolean - medications_context: name: string, type: string, notes: string, required: boolean - created_at: name: string, type: string, n | Represents the person whose appointments and memory are being prepared, including self and family/caregiver profiles. | Owned by account user; may be shared through CaregiverAccess. | - edit display/context fields - delete profile and associated visits - export profile memory - revoke caregiver access | - family/caregiver plan - personal memory plan |
| Visit | - id: name: string, type: string, notes: string, required: boolean - patient_profile_id: name: string, type: string, notes: string, required: boolean - status: name: string, type: string, notes: string, required: boolean - appointment_type: name: string, type: string, notes: string, required: boolean - appointment_at_optional: name: string, type: string, notes: string, required: boolean - clinician_or_location_optional: name: string, type: string, notes: string, required: boolean - reason_label: name: string, type: string, notes: string, required: boolean - created_at: name: string, type: stri | Appointment-level container for intake, brief, questions, debrief, and memory writes. | Belongs to one PatientProfile. | - archive visit - delete visit - edit appointment metadata - export visit packet | - appointment packs - personal memory plan usage tracking without health-content analytics |
| IntakeSummary | - id: name: string, type: string, notes: string, required: boolean - visit_id: name: string, type: string, notes: string, required: boolean - raw_input_ref: name: string, type: string, notes: string, required: boolean - symptoms: name: string, type: string, notes: string, required: boolean - timeline: name: string, type: string, notes: string, required: boolean - concerns: name: string, type: string, notes: string, required: boolean - current_context: name: string, type: string, notes: string, required: boolean - tried_already: name: string, type: string, notes: string, required: boolean - unk | Editable structured extraction from messy user input before brief generation. | Belongs to one Visit. | - edit every structured item - delete raw input - confirm extraction - mark item as user-confirmed or generated | - core free value - memory quality for paid plan |
| VisitBrief | - id: name: string, type: string, notes: string, required: boolean - visit_id: name: string, type: string, notes: string, required: boolean - intake_summary_id: name: string, type: string, notes: string, required: boolean - reason_for_visit: name: string, type: string, notes: string, required: boolean - key_symptoms: name: string, type: string, notes: string, required: boolean - timeline_summary: name: string, type: string, notes: string, required: boolean - context_summary: name: string, type: string, notes: string, required: boolean - top_concerns: name: string, type: string, notes: string, | One-page appointment preparation artifact generated from confirmed intake. | Belongs to one Visit and references one IntakeSummary version. | - edit brief sections - print/export - delete generated brief - regenerate from corrected intake | - free single-visit prep - appointment packs |
| QuestionPlan | - id: name: string, type: string, notes: string, required: boolean - visit_id: name: string, type: string, notes: string, required: boolean - visit_brief_id: name: string, type: string, notes: string, required: boolean - primary_questions: name: string, type: string, notes: string, required: boolean - optional_questions: name: string, type: string, notes: string, required: boolean - question_header_copy_id: name: string, type: string, notes: string, required: boolean | Short prioritized questions for the user to ask the clinician. | Belongs to one VisitBrief. | - reorder questions - hide questions - add personal question - mark asked after visit | - core free value - specialist appointment packs |
| PostVisitDebrief | - id: name: string, type: string, notes: string, required: boolean - visit_id: name: string, type: string, notes: string, required: boolean - raw_notes_ref: name: string, type: string, notes: string, required: boolean - what_happened: name: string, type: string, notes: string, required: boolean - decisions: name: string, type: string, notes: string, required: boolean - tests_or_referrals: name: string, type: string, notes: string, required: boolean - next_steps: name: string, type: string, notes: string, required: boolean - monitor_items: name: string, type: string, notes: string, required: bo | Organizes rough post-visit notes into decisions, next steps, tests/referrals, monitoring items, and unanswered questions. | Belongs to one Visit. | - edit every debrief field - mark follow-up complete - promote item to memory - delete raw notes | - paid personal memory - family/caregiver plan |
| PatientMemoryItem | - id: name: string, type: string, notes: string, required: boolean - patient_profile_id: name: string, type: string, notes: string, required: boolean - source_visit_id_optional: name: string, type: string, notes: string, required: boolean - category: name: string, type: string, notes: string, required: boolean - content: name: string, type: string, notes: string, required: boolean - confidence_source: name: string, type: string, notes: string, required: boolean - active: name: string, type: string, notes: string, required: boolean - created_at: name: string, type: string, notes: string, requir | Durable user-corrected memory unit that can inform future visit prep. | Belongs to one PatientProfile and may reference source visits. | - edit memory - delete memory - mark inactive - see source visit - exclude from future brief generation | - primary paid individual plan value - longitudinal moat |
| CaregiverAccess | - id: name: string, type: string, notes: string, required: boolean - patient_profile_id: name: string, type: string, notes: string, required: boolean - granted_to_user_id: name: string, type: string, notes: string, required: boolean - role: name: string, type: string, notes: string, required: boolean - permissions: name: string, type: string, notes: string, required: boolean - status: name: string, type: string, notes: string, required: boolean - created_at: name: string, type: string, notes: string, required: boolean - revoked_at_optional: name: string, type: string, notes: string, required: | Permission record allowing another account to help manage a PatientProfile. | Created by profile owner or legal guardian flow; revocable. | - grant access - revoke access - view access log - set role | - paid family/caregiver plan |
created at
2026-05-05T14:09:48.733Z
depends on
- M-00 Safety and Product Boundary
next module
M-02 Conversational Intake Prototype
shared types
| name | fields |
|---|---|
| StructuredItem | - id - label - details_optional - source=user_entered|generated|user_confirmed - created_at |
| TimelineItem | - id - when_label - description - source - sort_order |
| SafetyFlag | - id - flag_type - trigger_text_optional - escalation_copy_id - created_at |
| QuestionItem | - id - question - why_it_matters - category=clarifying|decision|timing|referral|monitoring|follow_up - priority - user_added |
| FollowUpItem | - id - label - details_optional - due_at_optional - status=open|done|dismissed - source |
| MedicationContext | - id - name_or_label - notes_optional - source - active |
schema version
1.0
data principles
- Structured user-corrected records are the source of truth, not raw chat logs.
- Generated inferences must be stored separately from user-confirmed facts.
- Every health object must support user correction and deletion.
- Analytics may count non-health metadata events but must not receive health text or symptoms.
- Caregiver access must be explicit, scoped, revocable, and auditable from the beginning even if caregiver UI ships later.
analytics boundary
allowed events
- visit_created
- brief_generated
- question_plan_generated
- debrief_created
- memory_item_saved
- caregiver_invited
allowed properties
- event_id
- user_id_hash
- profile_count_bucket
- visit_count_bucket
- plan_tier
- timestamp
forbidden properties
- symptom text
- medication text
- appointment reason text
- doctor/location names
- question text
- brief content
- debrief content
- memory content
retention defaults
- Anonymous local drafts expire automatically and are not synced.
- Raw intake and raw post-visit notes should be deletable independently from structured summaries.
- Generated memory items must require user confirmation before future use.
- Deleted profiles cascade delete or irreversibly detach visits/memory according to the final legal retention policy.
acceptance criteria
- Every MVP entity has purpose, ownership, privacy classification, required fields, user controls, and monetization support documented.
- Structured user-confirmed memory is separated from generated inferences and raw chat.
- Caregiver access is represented as a first-class permission object even if UI ships later.
- Analytics boundary explicitly forbids health text and appointment details.
- M-01 supports the free, paid individual, caregiver/family, and appointment-pack monetization paths without requiring schema redesign.
monetization mapping
| product | required entities | note |
|---|---|---|
| Free single-visit prep | - Visit - IntakeSummary - VisitBrief - QuestionPlan | |
| Paid personal memory | - PatientProfile - Visit - PostVisitDebrief - PatientMemoryItem | |
| Paid family/caregiver plan | - PatientProfile - CaregiverAccess - Visit - PatientMemoryItem | |
| Appointment packs | - Visit - VisitBrief - QuestionPlan | Usage counts only; no health content in billing analytics. |
product decisions inherited
- V1 is mobile-first responsive web/PWA.
- Anonymous drafts are local-only before server/model processing.
- Account plus affirmative consent is required before storing health history or using server-side AI on health text.
- Outputs are appointment preparation, clarification, summarization, and follow-up organization only.