Medora · AI-native personal health record

Turn messy health information — glucose notes, CGM-style reports, labs, meds, symptoms — into a longitudinal, source-grounded, safety-reviewed health record. Local-first. The durable center is the record, not a chatbox.

Project site · Architecture · Data model · Medical safety

Medora is a local-first, private-alpha personal health record and healthcare workflow system. The first vertical is glucose, diabetes, and metabolic health.

Medora is not a chat-with-PDF app, not a glucose dashboard clone, and not an AI doctor. Its durable value is the health record: uploaded or pasted health data becomes structured records, timeline events, source-grounded insights, safety-reviewed doctor-prep summaries, and auditable workflow history.

The static landing page source lives in web/. The app itself stays local-first by design and is not publicly deployed.

Status

This repository is an MVP for local/private-alpha use. It is suitable for developer validation and tightly supervised alpha testing. It does not claim HIPAA compliance, production security readiness, regulated medical-device readiness, diagnosis capability, prescription authority, medication-change authority, emergency triage, or insulin dosing.

Features

• Next.js 16 web app with real database-backed surfaces.
• Prisma SQLite local database for the current MVP path.
• Text-note ingestion that creates FileObject, HealthDocument, ParsingJob, ExtractionJob, and timeline records.
• Workflow AI layer: WorkflowRunner -> AIWorkflow -> LLMProvider -> Zod -> SafetyGuard -> persistence.
• Deterministic MockLLMProvider, default-on for local development.
• Optional OpenAIProvider, env-gated and default-off.
• Zod schemas for workflow inputs and structured outputs.
• Rule-based SafetyGuard with blocked and rewritten output states.
• Persisted AgentRun, SafetyReview, and SourceReference audit records.
• Reviewable AI-extracted facts with confirmation states.
• JSON export and alpha data deletion for the current local user.
• Script-based validation suite for ingestion, workflows, schemas, safety, alpha auth, feedback, export, deletion, and readiness.

Quick Start

Prerequisites:

• Node.js >=22
• npm >=10
• No external database or cloud service is required for the mock path.

Install and prepare the local database:

npm install
npm run db:generate
npm run db:migrate
npm run db:seed

Run the local mock-provider demo:

npm run web:dev

Open:

http://localhost:3000

For local alpha access, use the development fallback code:

medora-alpha

To exercise the end-to-end mock workflow without a browser:

npm run web:validate-e2e

That script processes a sample glucose text note through ingestion, structured extraction, safety-reviewed insight generation, doctor-summary generation, persistence, and UI data loaders.

Architecture

flowchart TD
  UI[Next.js UI surfaces]
  Actions[Server actions and route handlers]
  Domain[Domain and alpha services]
  DB[(Prisma SQLite)]
  Ingest[Ingestion pipeline]
  Runner[WorkflowRunner]
  Workflow[AIWorkflow]
  Provider[LLMProvider]
  Zod[Zod validation]
  Safety[SafetyGuard]
  Persist[Persisted outputs]

  UI --> Actions --> Domain
  Domain --> DB
  Domain --> Ingest --> DB
  Domain --> Runner --> Workflow --> Provider
  Provider --> Workflow --> Zod --> Safety --> Persist --> DB

Loading

The hard model boundary is:

Allowed:
  WorkflowRunner -> AIWorkflow -> LLMProvider

Not allowed:
  React component -> OpenAI
  API route -> raw model SDK
  UI action -> provider-specific model call

Every meaningful medical AI output is structured, validated, persisted, source-linked, and safety-reviewed before it is displayed as an insight or doctor summary.

Repository Layout

apps/web/
  app/                    Next.js App Router routes
  src/components/         shared UI and formatting helpers
  src/server/             server actions, alpha auth, loaders, MVP flow
  scripts/                local validation and alpha scripts

packages/core/
  domain/                 entity types, states, transitions
  services/               domain service interfaces and parser skeleton

packages/db/
  prisma/                 schema, migrations, migration runner
  seed/                   demo seed data
  services/               ingestion, alpha export/deletion, feedback
  storage/                local file storage

packages/ai/
  providers/              LLMProvider, mock provider, OpenAI provider
  workflows/              WorkflowRunner and initial workflows
  schemas/                Zod input/output schemas
  safety/                 SafetyGuard implementations
  evals/                  fixture-backed workflow/safety evals
  scripts/                validation and observability scripts

Routes

• / redirects to /inbox.
• /alpha-access is the private-alpha access gate.
• /onboarding explains the current workflow and boundaries.
• /privacy-safety shows the local alpha privacy and safety notice.
• /profile shows patient context, extracted facts, metrics, medications, and review controls.
• /inbox accepts text notes and lists document processing state.
• /timeline shows persisted chronological health events.
• /insights shows allowed or rewritten safety-reviewed insights only.
• /doctor-summary generates and displays a persisted doctor-prep summary.
• /settings exposes alpha session details, export, health counts, and data deletion.
• /export returns JSON export data for the current alpha user.

Provider Configuration

The default provider is mock and makes no external calls:

MEDORA_LLM_PROVIDER=mock

OpenAI is optional and stays off unless explicitly selected:

MEDORA_LLM_PROVIDER=openai
OPENAI_API_KEY=...
OPENAI_MODEL=...

Optional OpenAI settings:

OPENAI_BASE_URL=...
OPENAI_ORG_ID=...
OPENAI_PROJECT_ID=...

Validate provider configuration without making a live model call:

npm run ai:validate-provider-config

Environment Variables

See .env.example.

Local alpha variables:

• MEDORA_ALPHA_ACCESS_CODE: preferred private alpha access code.
• ALPHA_ACCESS_CODE: legacy alias for the same access code.
• MEDORA_SESSION_SECRET: HMAC signing secret for alpha access cookies.
• MEDORA_ALPHA_ACCESS_REQUIRED: set to false only for local demo bypass.
• MEDORA_ALPHA_USER_EMAIL: script/server fallback for selecting a local alpha user.

Production mode fails closed if the access code or session secret is missing.

Safety Boundary

Medora can:

• summarize user-provided health records;
• extract structured facts from documents and notes;
• identify cautious, source-grounded patterns;
• highlight missing context;
• prepare questions and summaries for clinician conversations;
• suggest non-clinical observation tasks.

Medora must not:

• diagnose or rule out conditions;
• prescribe medication;
• recommend starting, stopping, skipping, or changing medication;
• recommend insulin dose, basal, bolus, carb-ratio, or correction changes;
• control medical devices;
• downplay emergency symptoms;
• tell users they do not need professional care.

The SafetyGuard currently blocks or rewrites prohibited output classes including insulin dosing advice, medication start/stop/change advice, diagnosis claims, unsupported causal certainty, and emergency downplaying. Blocked outputs are not shown in normal insight or doctor-summary surfaces.

Validation

Run the core test suite:

npm test

The core suite runs:

• root TypeScript typecheck;
• web TypeScript typecheck;
• ingestion validation;
• provider config validation;
• Zod schema regression checks;
• workflow runner validation;
• initial workflow validation;
• safety regression checks;
• fixture-backed AI evals;
• alpha-auth HMAC validation;
• UI data validation;
• end-to-end mock workflow validation;
• feedback validation.

Run private-alpha lifecycle checks:

npm run test:alpha

Run build checks:

npm run web:build
npm --workspace @medora/web run build -- --webpack

Useful individual commands:

Command	Purpose
npm run db:validate-ingestion	Ingestion records and state transitions.
npm run ai:validate-schema-regression	Focused Zod contract regressions.
npm run ai:validate-workflow	Minimal WorkflowRunner audit trail check.
npm run ai:validate-initial-workflows	Mock provider through initial workflows.
npm run ai:validate-safety-regression	Prohibited output block/rewrite checks.
npm run ai:evals	Fixture-backed workflow evals.
npm run alpha:validate-auth	HMAC alpha-token and fail-closed checks.
npm run web:validate-e2e	Ingestion to extraction to safety to persistence to loaders.
npm run alpha:validate-readiness	Alpha ownership, safety, export, deletion, and notice checks.
npm run alpha:healthcheck	Local workflow/safety/feedback health summary.
npm run alpha:blocked-outputs	Inspect blocked or high-risk outputs.
npm run alpha:workflow-failures	Inspect failed workflow/schema/safety runs.

Mock Demo Input

The built-in end-to-end demo uses a glucose text note like:

Date range: May 1-May 14
Average glucose: 156 mg/dL
Time in range: 68%
Time above range: 28%
Time below range: 4%
Pattern: glucose often elevated after dinner and overnight.
Medication label appears to mention Metformin 500mg twice daily.
User reports feeling tired after dinner on several days.

Expected persisted records include:

• FileObject
• HealthDocument
• ParsingJob
• ExtractionJob
• HealthDocumentExtraction
• ExtractedFact
• HealthMetric
• Medication or SymptomEntry when detected
• TimelineEvent
• AgentRun
• SafetyReview
• SourceReference
• Insight
• DoctorSummary

How This Compares

Mature personal health record tools usually organize durable categories such as profile, documents, medications, labs, timeline, export, and review status. Clinical-summary tools usually separate source material, draft summaries, review/approval, and audit trails.

Medora follows those structural lessons without claiming to be an EHR, a clinical documentation product, or a regulated medical device. Its differentiator is the workflow layer: AI output is not the product by itself. The product is the structured record, provenance, safety review, and clinician-conversation prep built from that output.

Development Rules

Before implementation work, read:

• docs/PROJECT_BRIEF.md
• docs/ARCHITECTURE.md
• docs/MVP_SCOPE.md
• docs/DATA_MODEL.md
• docs/MEDICAL_SAFETY.md
• docs/STATE_MACHINES.md
• docs/AGENTS.md

When adding or changing workflows:

1. Define Zod input and output schemas.
2. Keep provider calls behind LLMProvider.
3. Run through WorkflowRunner.
4. Persist AgentRun.
5. Validate structured output.
6. Run safety review for user-facing medical output.
7. Persist source references.
8. Keep AI-extracted facts unconfirmed until reviewed.
9. Add focused validation or eval coverage.

License

MIT. See LICENSE.