Patient Visit Advocate architecture MVP-01
architecture artifact · for Patient Visit Advocate · phase MVP-01 · status approved
Identity and consent settings; no health content in analytics identifiers.
Appointment-level containers for prep, brief, questions, debrief, and memory writes.
Imported Pocket Advocate Q&A records with source file, sheet, source row id, wave, cluster, category, question, what_to_know, questions_to_ask_provider, what_to_watch_for, revised flag, lint status, review status, and timestamps.
Cluster metadata including wave, specialty/navigation domain, coverage_content flag, disclaimer policy, and recency caveat requirement.
Generated brief versions tied to confirmed intake.
Generated and user-edited clinician question list.
Explicit, scoped, revocable access grants for shared advocacy.
Editable structured extraction plus optional raw-input reference with short retention.
Self and family/caregiver profiles; supports paid caregiver plan later.
Per-item compliance findings for directive language, clinical thresholds, drug recommendations, emergency triage specificity, diagnosis implication, comparative claim, and missing required UI tags.
Source ingestion audit metadata: filename, checksum if available, observed sheet row counts, importer version, discrepancy notes, and import timestamp.
Structured visit outcome and follow-up items from user notes.
User-confirmed longitudinal facts, unresolved questions, patterns, and context.
Human review decisions for imported or generated Q&A content before publishing.
User acknowledgement timestamp/version for the exact onboarding disclaimer; accessible for Settings > Legal display.
| id | question |
|---|---|
| ARCH-OQ-QNA-001 | Is the Q&A library the MVP primary surface, or a seed layer for the AI visit-prep/question-generation workflow? |
| ARCH-OQ-QNA-002 | Are additional workbook rows hidden, external, or represented outside the extracted sheetData? Verify before estimating ingestion. |
architecture artifact · for Patient Visit Advocate · phase MVP-01 · status approved
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
- ARCH-OQ-QNA-001: id: string, question: string
- ARCH-OQ-QNA-002: id: string, question: string
Machine-readable source fields
| id | boundaries | responsibility |
|---|---|---|
| intake-agent | - No diagnosis - No treatment recommendations | Ask adaptive pre-visit questions and extract structured intake fields from messy user input. |
| clinical-guardrail-layer | - Does not produce diagnosis categories as facts | Classify seriousness signals conservatively, enforce medical-safety language, and decide whether escalation copy is required. |
| question-generator | - Questions are framed for clinician discussion | Generate a short prioritized question plan tied to intake fields and user concerns. |
| translator | - Does not simplify away important qualifiers | Convert medical language and visit notes into plain English with uncertainty preserved. |
| memory-writer | - User can correct/delete; raw chat is not the primary memory | Persist structured visit history, unresolved questions, medications/context, and user-corrected facts. |
Identity and consent settings; no health content in analytics identifiers.
Appointment-level containers for prep, brief, questions, debrief, and memory writes.
Imported Pocket Advocate Q&A records with source file, sheet, source row id, wave, cluster, category, question, what_to_know, questions_to_ask_provider, what_to_watch_for, revised flag, lint status, review status, and timestamps.
Cluster metadata including wave, specialty/navigation domain, coverage_content flag, disclaimer policy, and recency caveat requirement.
Generated brief versions tied to confirmed intake.
Generated and user-edited clinician question list.
Explicit, scoped, revocable access grants for shared advocacy.
Editable structured extraction plus optional raw-input reference with short retention.
Self and family/caregiver profiles; supports paid caregiver plan later.
Per-item compliance findings for directive language, clinical thresholds, drug recommendations, emergency triage specificity, diagnosis implication, comparative claim, and missing required UI tags.
Source ingestion audit metadata: filename, checksum if available, observed sheet row counts, importer version, discrepancy notes, and import timestamp.
Structured visit outcome and follow-up items from user notes.
| id | question |
|---|---|
| ARCH-OQ-QNA-001 | Is the Q&A library the MVP primary surface, or a seed layer for the AI visit-prep/question-generation workflow? |
| ARCH-OQ-QNA-002 | Are additional workbook rows hidden, external, or represented outside the extracted sheetData? Verify before estimating ingestion. |
1.0
| id | blocker |
|---|---|
| ARCH-BLOCK-QNA-001 | Do not implement public Q&A surfaces until data model includes provider-question field, disclaimer rendering, coverage tags, import provenance, lint status, and review status. |
| ARCH-BLOCK-QNA-002 | Resolve workbook 1,000+ summary vs 253 observed master rows before full corpus import planning. |
| id | boundary |
|---|---|
| qna-generator-boundary | Any generated advocacy question must be a question for a qualified provider or system navigation step, never a clinical directive. |
| qna-library-boundary | Static Q&A seed content supports patient education and advocacy; it is not diagnosis, treatment planning, or emergency triage. |
| id | role | artifact id |
|---|---|---|
| client-source-reference | client Q&A and compliance source | fb647c16-c6de-412b-a46f-56746971cf25 |
AI-first orchestrated workflow with structured artifacts, not a single chatbot transcript.
- capture raw intake
- extract structure
- run guardrail review
- user edits extracted structure
- generate visit brief
- generate question plan
- post-visit debrief writes memory
Do not start with realtime room mode. Build the prepared-visit loop and memory contract first.
| id | responsibility |
|---|---|
| qna-card | Render Q&A sections and exact persistent non-dismissible footer disclaimer on every expanded Q&A card. |
| onboarding-legal-gate | Require first-launch acknowledgement of exact client disclaimer text before content access. |
| coverage-caveat-banner | Render exact recency caveat for coverage-tagged clusters; collapsible only after reading. |
| qna-importer | Normalize workbook rows into Q&A data model while preserving provenance and row-count evidence. |
| content-compliance-linter | Flag risky content patterns before publishing or generated-use approval. |
| qna-review-queue | Expose lint findings and review state so flagged rows cannot silently ship. |
- Treat all health content as sensitive
- Encrypt at rest where supported
- Minimize raw transcript retention
- Separate user-corrected facts from generated inferences
- Require explicit user action before exporting/sharing
- Generated memory is not used in future prompts until user-confirmed.
- Caregiver access is explicit, scoped, revocable, and auditable.
- Analytics events must never include health text, doctor/location names, question text, brief content, debrief content, or memory content.