# Meduvo Health System Flow

Last reviewed: 2026-07-21

This document describes the current Meduvo Health flow from practice signup through patient care, alerts, psychiatric review, billing, and reporting. It is based on the current Laravel backend implementation, public/web routes, API routes, policies, and recently completed assessment/kiosk work.

## 1. Big Picture

Meduvo Health is a multi-tenant Collaborative Care Management platform. A practice registers publicly, Meduvo SuperAdmin reviews compliance, approved practice staff are invited into the system, clinic staff register patients, patients complete intake and assessments, the care team reviews risk and decides next steps, and billing/reporting dashboards track care delivery and claim readiness.

Core flow:

1. Practice submits public registration.
2. SuperAdmin reviews BAA/eSign compliance.
3. SuperAdmin approves the practice.
4. Clinic Admin or SuperAdmin invites staff users.
5. Staff accept secure invitation links and create accounts.
6. Staff register a patient and assign PCP/BHCM.
7. Staff assign assessments and launch kiosk/tablet or patient app flow.
8. Patient signs CoCM consent, completes SDOH, and answers assessments.
9. Assessment answers are streamed one question at a time.
10. Scores are calculated automatically when required questions are complete.
11. Safety-risk answers immediately generate emergency alerts.
12. Care team reviews results and decides CoCM accept, decline, referral, warm handoff, care plan, or psychiatric review.
13. BHCM manages follow-up tasks, care goals, outreach, and patient communication.
14. Psychiatrist reviews elevated cases and routes recommendations to BHCM or PCP.
15. Billing engine computes CoCM billing status from time logs and rule sets.
16. Reports show outcomes, documentation gaps, and claim readiness.

## 2. Practice Registration Flow

Public entry points:

- `/`
- `/providers`
- `/providers/flow`
- `/providers/register`

How a practice registers:

1. A practice opens `/providers/register`.
2. The practice submits:
   - practice name
   - primary contact name
   - primary contact email
   - phone
   - website
   - address
   - operational timezone
   - estimated monthly CoCM patients
   - BAA intake acknowledgement
   - eSign intake acknowledgement
   - optional signup notes
3. The system creates a `tenants` row with:
   - `status = pending_review`
   - public intake/contact fields
   - BAA/eSign acknowledgement timestamps
4. The practice sees a confirmation message that the practice is queued for compliance review.
5. Email notifications are sent:
   - SuperAdmins or configured system admin email get a new-practice registration email.
   - The practice primary contact gets a registration-received email.

Important behavior:

- A newly registered practice does not immediately get PHI access.
- The tenant remains blocked until SuperAdmin compliance verification and approval are complete.

## 3. Practice Compliance And Approval

Admin route:

- `/admin/tenants`
- `/admin/tenants/{tenant}`

Who can manage this:

- SuperAdmin only.

Flow:

1. SuperAdmin opens Practice Activation.
2. SuperAdmin reviews the pending tenant.
3. SuperAdmin marks:
   - BAA executed
   - eSign compliance verified
4. The system audit-logs the compliance update.
5. When both compliance items are verified, the practice contact receives a compliance-completed email.
6. SuperAdmin approves the tenant.
7. The tenant changes from `pending_review` to `approved`.
8. The system audit-logs the approval.
9. The practice contact receives a practice-approved email.
10. PHI access is unblocked for users in that tenant.

Protection:

- Pending or suspended tenants are blocked from normal API and web PHI access.
- SuperAdmin can still access tenant activation routes so they can approve or manage pending practices.

## 4. System User Registration Flow

System users do not self-register publicly. Staff accounts are created by secure invitation.

Staff management route:

- `/admin/staff`

Invitation acceptance route:

- `/invitations/{token}/accept`

Roles that can be invited:

- Clinic Admin
- PCP
- BHCM
- Psychiatrist

Who can invite:

- SuperAdmin can invite users into any tenant.
- Clinic Admin can invite staff into their own tenant.
- Clinic Admin cannot invite SuperAdmin users.

Flow:

1. Clinic Admin or SuperAdmin opens Care Team/Staff Management.
2. They enter the staff member's email and select a role.
3. The system creates an `invitations` row with:
   - tenant id
   - email
   - role
   - hashed token
   - invited by user id
   - 7-day expiry
4. The raw token is only shown/sent once and is not stored.
5. The invited staff member receives an email with a secure setup link.
6. The staff member opens the link, enters name and password, and activates the account.
7. The system creates a `users` row with:
   - assigned tenant
   - invited role
   - active status
   - verified email timestamp
8. If the role is BHCM, default max caseload is assigned.
9. The invitation is marked accepted.
10. The user is logged in and marked online.

Login and MFA:

- Web users sign in at `/login`.
- API/mobile users sign in with `/api/v1/login`.
- MFA can be enabled for provider sign-in.
- Successful login marks the user online.
- Logout marks the user offline.

## 5. Role Responsibilities

### SuperAdmin

Primary job: platform administration and tenant activation.

Can:

- Review practice registrations.
- Verify BAA/eSign compliance.
- Approve practices.
- Enter tenant workspace when needed.
- Invite users broadly.
- View administrative audit and compliance areas.

Should not be part of normal day-to-day patient care unless acting in an administrative/support capacity.

### Clinic Admin

Primary job: tenant-level operations.

Can:

- Manage staff for the practice.
- Invite PCP, BHCM, psychiatrist, and clinic admin users.
- Register patients.
- View patient registry and dashboards.
- Assign assessments.
- Monitor alerts.
- View billing and reports.
- Export claim-ready report data.
- View audit trail.

### PCP

Primary job: lead medical care and in-room clinical decision-making.

Can:

- View and create patient profiles.
- Assign assessments.
- Review patient chart and scores.
- Accept or decline patient into CoCM workflow.
- Trigger referral or warm handoff to BHCM.
- Acknowledge/respond to emergency safety alerts.
- Log clinical/outreach time.
- Review psychiatric recommendations routed to them.

### BHCM

Primary job: coordinate behavioral health care.

Can:

- View assigned caseload.
- Manage BHCM worklist.
- Review assessment results.
- Handle referral scheduling tasks.
- Join warm handoffs.
- Create care goals.
- Communicate with patient through patient/BHCM message thread.
- Log direct/indirect care time.
- Acknowledge/respond to emergency safety alerts.
- Review psychiatric recommendations routed to them.

Capacity:

- BHCM users have a max caseload.
- Registry/capacity endpoints show caseload, maximum caseload, and whether the BHCM is at capacity.
- Warm handoff/referral logic uses online status and caseload capacity.

### Psychiatrist

Primary job: consultant/advisor to the care team.

Can:

- Open the psychiatrist review portal.
- See active CoCM cases, elevated scores, safety-risk cases, and pending recommendations.
- Create recommendations.
- Route recommendations only to BHCM or PCP.

Cannot:

- Route recommendations directly to patients.
- Act as direct patient-facing warm handoff participant.
- Acknowledge emergency alerts as a physical responder.

### Patient

Primary job: complete intake, consent, assessments, and participate in care.

Can:

- Sign CoCM consent.
- Complete SDOH intake.
- Complete PHQ/GAD assessments from app or kiosk.
- Join a secure warm handoff video session after BHCM joins.
- Message assigned BHCM through the patient/BHCM thread.
- View care goals scoped to their own profile.

Patient access is always restricted to their own patient profile.

## 6. Patient Registration Flow

Main web route:

- `/admin/patients`

Who can create patients:

- SuperAdmin
- Clinic Admin
- PCP
- BHCM

Patient registration fields:

- name
- email
- medical record number
- date of birth
- sex
- phone
- address
- payer type
- PCP
- BHCM

What happens when staff registers a patient:

1. Staff opens Patient Registry.
2. Staff enters patient demographics and selects assigned PCP and BHCM.
3. The system creates a `users` row:
   - role `patient`
   - status `invited`
   - random generated password
4. The system creates a `patient_profiles` row:
   - tenant id
   - user id
   - encrypted MRN
   - MRN hash for exact search
   - PCP assignment
   - BHCM assignment
   - DOB, sex, phone, address
   - enrollment date
   - `co_cm_status = prospect`
   - payer type
5. Staff is redirected to the patient chart.
6. The patient is ready for assessment assignment and kiosk/tablet handoff.

Patient search:

- Staff can search by name, email, DOB, or exact MRN hash.
- PHI reads are audit-logged.

Current implementation note:

- The web registration flow creates a patient user with status `invited`, but the currently inspected web flow does not send a patient password setup email at the moment of patient creation. Patient app access may require a separate operational setup/reset-password process unless a patient-invite email flow is added.

## 7. Assessment Assignment And Kiosk Flow

Patient chart route:

- `/admin/patients/{patientProfile}`

Kiosk launch routes:

- `/admin/kiosk/{patientProfile}/launch`
- `/kiosk/terminal`

Assessment APIs:

- `/api/v1/assessments/templates`
- `/api/v1/assessments/start`
- `/api/v1/assessments/stream-answer`
- `/api/v1/kiosk/assessments/templates`
- `/api/v1/kiosk/assessments/start`
- `/api/v1/kiosk/assessments/stream-answer`

Assessment templates currently include:

- PHQ-2
- PHQ-9
- GAD-7

Staff assignment flow:

1. Staff opens patient chart.
2. Staff selects one or more active assessment templates.
3. The system creates pending `patient_assessment_responses` rows.
4. Staff clicks send/launch to kiosk.
5. Staff chooses the exact assessment for the kiosk session.
6. The system creates a short-lived Sanctum token:
   - name `kiosk-handover`
   - ability `kiosk:screening`
   - expires in 30 minutes
   - scoped to one patient
   - scoped to selected assessment/template context
   - includes witnessing provider id
7. Staff opens the generated kiosk link or QR code on the patient-facing tablet.
8. Patient confirms identity using first name and masked DOB.
9. Patient completes consent, SDOH, and assessment screens.

Kiosk security:

- Kiosk tokens cannot access normal provider API routes.
- Kiosk routes verify that the token's patient id matches the route/body/assessment response patient.
- The kiosk shows only the selected assigned questionnaire.
- If PHQ-2 is positive and creates a PHQ-9 follow-up, the kiosk may continue into that generated PHQ-9 without exposing unrelated stale questionnaires.

## 8. CoCM Consent And SDOH Intake

Consent endpoint:

- `/api/v1/co-cm-consents`
- `/api/v1/kiosk/co-cm-consents`

Consent behavior:

1. Patient signs CoCM consent from app or kiosk.
2. Consent stores:
   - tenant id
   - patient profile id
   - witnessing provider id
   - signature image
   - consent version
   - server-side signed timestamp
3. In kiosk mode, the witnessing provider is inferred from the staff member who issued the handover token.
4. Consent rows are treated as immutable signed records.

SDOH endpoint:

- `/api/v1/patient-sdoh-records`
- `/api/v1/kiosk/patient-sdoh-records`

SDOH behavior:

1. Patient answers housing, food, and transportation questions.
2. Each step can be submitted independently.
3. The system upserts one SDOH record per patient.
4. Missing later steps do not erase earlier saved SDOH values.

## 9. Assessment Scoring And Need-For-Care Identification

Assessments stream answers one question at a time. The system does not wait until the end to receive a full survey payload.

Streaming behavior:

1. Client sends:
   - assessment response id
   - question key
   - answer value
   - whether the question is a critical safety item
2. The backend merges the answer into the response's `answers` JSON.
3. The backend checks whether required questions are complete.
4. If all required questions are complete and answers are scoreable, the backend saves `total_score`.
5. Until completion, score remains pending.

PHQ-2 behavior:

- PHQ-2 has two questions.
- Score range is 0-6.
- If PHQ-2 total score is 3 or higher, the system automatically creates a pending PHQ-9 follow-up assessment.
- If PHQ-2 score is below 3, no automatic PHQ-9 follow-up is created.

PHQ-9/GAD-7 behavior:

- PHQ-9 and GAD-7 are scored from their answer options.
- PHQ-9 question 9 is a safety-risk item.
- GAD-7 has a configured risk indicator on its final item according to the current seeded reference data.

How the system identifies patients who may need care:

1. Basic CoCM status:
   - `prospect`
   - `active`
   - `declined`
2. Scored assessment results:
   - completed PHQ/GAD scores
   - latest score
   - score delta compared with prior assessment
3. PHQ-2 positive screen:
   - score 3 or higher creates PHQ-9 follow-up
4. Safety-risk flags:
   - critical item positive answer marks `has_safety_risk = true`
5. Registry risk engine:
   - compares recent assessment scores
   - checks missing care milestones
   - checks safety-risk flags in the configured window
   - applies active risk stratification rule-set weights
   - marks whether psychiatric review is needed
6. Psychiatrist review portal:
   - shows active CoCM cases
   - shows safety-risk cases
   - shows cases with assessment score 10 or higher
   - shows pending psychiatric recommendations

Important note:

- The safety-positive evaluator is currently simple/configurable: boolean true, numeric value greater than 0, or string yes/true/1 counts as positive for a critical item. This should be clinically reviewed before production clinical use.

## 10. Emergency Safety Alert Flow

Alert trigger:

An alert is generated when an answer is submitted for a question marked as a critical safety item and the answer is positive.

What happens immediately:

1. Backend saves the answer into the assessment response.
2. Backend marks the assessment response with `has_safety_risk = true`.
3. If the response is complete and scoreable, total score is saved.
4. Backend snapshots the question text for audit/clinical history.
5. Backend creates an `emergency_safety_alerts` row with:
   - tenant id
   - patient profile id
   - assessment response id
   - question key
   - question text
   - answer value
   - triggered timestamp
6. Backend broadcasts a safety-alert event.
7. Backend sends push notification to:
   - assigned PCP
   - assigned BHCM
   - all Clinic Admin users in the tenant
8. Patient/kiosk receives `action = halt_survey`.
9. Patient-facing screen moves to a non-dismissable safety-halt state.
10. Staff see the alert in the global emergency alert widget/drawer.

Alert acknowledgement:

1. PCP, BHCM, Clinic Admin, or SuperAdmin opens/receives the alert.
2. Staff confirms/acknowledges physical intervention.
3. The alert saves:
   - acknowledged timestamp
   - acknowledged by user id
4. Acknowledgement is broadcast so other open dashboards can update.
5. Alert read/actions are PHI audit-logged.

Who responds:

- PCP, BHCM, and Clinic Admin are responder roles.
- Psychiatrist is not a direct responder to emergency alerts.

## 11. Care Team Journey After Screening

After registration/intake/assessment, staff use the patient chart and dashboards to decide the next workflow.

Patient chart shows:

- demographics
- PCP/BHCM assignment
- assessment review
- recent alerts
- open tasks
- care goals
- time logs
- BHCM availability
- available assessment templates

Possible next actions:

### Accept Into CoCM

1. Staff marks patient accepted.
2. `co_cm_status` changes to `active`.
3. Enrollment date is set if missing.
4. Patient becomes part of active CoCM reporting and billing readiness checks.

### Decline CoCM

1. Staff records a required decline reason.
2. `co_cm_status` changes to `declined`.
3. A 30-day follow-up task is created.
4. Decline tracker shows the patient and task.

### Referral Or Warm Handoff

1. PCP initiates referral from patient chart or API.
2. System checks assigned BHCM availability:
   - if BHCM is online and under capacity: direct call/warm handoff
   - otherwise: scheduling task
3. Direct call creates a warm handoff session.
4. BHCM receives broadcast/push.
5. BHCM joins.
6. Patient is invited to the secure video session.
7. If BHCM declines or is unavailable, scheduling/follow-up remains the fallback.

### Care Plan

1. BHCM can create care goals.
2. Goals include statement, action steps, and target date.
3. Patient and assigned providers can view care goals according to policy.

### Outreach And Time Tracking

1. PCP/BHCM/Psychiatrist can log clinical time.
2. Logs include activity type, start/end timestamps, and notes.
3. Time contributes to billing period computation after submission.
4. Submitted logs are treated as immutable, with corrections handled separately.

## 12. BHCM Worklist

Route:

- `/admin/bhm`

Who can access:

- BHCM
- Clinic Admin
- SuperAdmin

What it shows:

- assigned/recent patients
- referral scheduling tasks
- decline follow-up tasks
- pending warm handoff sessions
- recent time logs
- active care goals

BHCM-specific behavior:

- BHCM sees their own assigned caseload.
- Clinic Admin and SuperAdmin can see broader tenant-level worklist context.

## 13. Psychiatric Review Flow

Route:

- `/admin/psychiatry`

Who can access:

- Psychiatrist
- Clinic Admin
- SuperAdmin

Cases appear when:

- patient is active in CoCM
- any assessment has safety risk
- any assessment total score is 10 or higher
- patient has pending psychiatric recommendation

Recommendation flow:

1. Psychiatrist reviews case context.
2. Psychiatrist writes recommendation.
3. Psychiatrist chooses recipient:
   - BHCM
   - PCP
4. Recommendation is saved with status `pending`.
5. Recommendation is broadcast.
6. Recipient receives push notification.
7. Recipient can approve or defer.
8. Deferral requires a structured deferral reason.

Important rule:

- Psychiatrist recommendations route to care team only, never directly to the patient.

## 14. Billing And Reporting Flow

Billing dashboard:

- `/admin/billing`
- `/admin/billing/{patientProfile}`

Reports:

- `/admin/reports`
- `/admin/reports/claim-export`

Who can view billing dashboard:

- SuperAdmin
- Clinic Admin
- PCP
- BHCM

Who can export claims:

- SuperAdmin
- Clinic Admin

Billing computation uses:

- submitted time logs
- active billing rule sets
- tenant operational timezone
- patient payer type
- billing period year/month
- resolved CPT/code units

Reporting dashboard uses:

- patient CoCM status
- consent signed status
- latest scored assessment
- baseline-to-latest score delta
- submitted time logs
- computed billing period
- resolved billing codes

Claim readiness requires no documentation gaps.

Current documentation gaps checked:

- CoCM not active
- missing consent
- missing scored assessment
- no submitted time logs
- no resolved billing code

Claim export:

- Streams CSV.
- Audit-logs the export before download.
- Includes patient, billing period, minutes, resolved codes, score, consent, submitted logs, claim-ready flag, and documentation gaps.

## 15. Audit, Security, And Tenant Boundaries

Tenant approval:

- Pending practices cannot access PHI.
- Approved tenant status is required for normal staff/patient use.

Tenant isolation:

- Users belong to a tenant except SuperAdmin.
- Patient profiles, alerts, logs, billing, and most clinical records are tenant-scoped.

PHI audit:

- Patient profile reads are audited.
- Assessment reads are audited.
- Consent reads are audited.
- SDOH reads are audited.
- Care goal reads are audited.
- Time log reads are audited.
- Billing/reporting reads and exports are audited.
- Alert reads and acknowledgement are audited.

Immutable or controlled records:

- Signed CoCM consents are immutable.
- Audit log is read-only in UI.
- Submitted time logs are not freely edited; corrections are controlled.
- Psychiatric recommendation deferrals require a reason.

Kiosk hardening:

- Short-lived tokens.
- Single patient scope.
- Selected questionnaire scope.
- Normal API rejection for kiosk-only tokens.
- Kiosk token cannot browse provider data or tenant records.

## 16. End-To-End Patient Journey Example

1. Practice registers at `/providers/register`.
2. SuperAdmin verifies compliance and approves practice.
3. Clinic Admin invites PCP, BHCM, and Psychiatrist.
4. Staff accept invitations and create passwords.
5. Clinic Admin or provider registers patient in `/admin/patients`.
6. Patient profile is created with assigned PCP and BHCM.
7. Staff opens patient chart.
8. Staff assigns PHQ-2, PHQ-9, GAD-7, or another active assessment packet.
9. Staff launches kiosk/tablet with selected questionnaire.
10. Patient confirms identity on kiosk.
11. Patient signs CoCM consent.
12. Patient completes SDOH steps.
13. Patient completes PHQ-2.
14. If PHQ-2 score is 3 or higher, PHQ-9 follow-up is created automatically.
15. Patient completes PHQ-9/GAD-7 as assigned.
16. If a critical safety item is positive, survey halts and emergency alert is generated immediately.
17. PCP/BHCM/Clinic Admin respond and acknowledge alert.
18. Care team reviews score, SDOH, consent, and patient chart.
19. Staff either accepts patient into CoCM, records decline with follow-up, or starts referral/warm handoff.
20. BHCM coordinates care goals, outreach, communication, and follow-up tasks.
21. Psychiatrist reviews elevated/safety/active cases and sends recommendations to BHCM or PCP.
22. PCP/BHCM approve or defer recommendations.
23. Providers submit time logs.
24. Billing engine computes monthly CoCM billing status.
25. Reports show outcomes, documentation gaps, and claim readiness.
26. Clinic Admin exports claim-ready CSV when appropriate.

## 17. Current Operational Notes

The following are important for product/operations planning:

1. Practice self-registration is implemented and emails are wired.
2. Staff self-registration is invitation-only, not public self-signup.
3. Patient creation exists in the web portal, but patient password setup/email invitation is not currently part of the inspected web patient creation flow.
4. PHQ-2 prescreen is implemented with automatic PHQ-9 follow-up at score 3 or higher.
5. Assessment scoring is automatic once all required scoreable questions are answered.
6. Safety alerts are immediate and interrupt the assessment flow.
7. The current safety-positive evaluator is intentionally simple and should be reviewed by a clinical lead before production clinical reliance.
8. Kiosk device lockdown has a separate runbook in `docs/kiosk-device-lockdown.md`; actual MDM/device enforcement is an external clinic IT step.
9. Firebase/native push configuration depends on real project credentials and mobile platform configuration.
10. Billing and risk rule sets are data-driven and should be reviewed/approved before real claims or clinical escalation use.