Operational Reference

Collaborative care, from intake to outcomes

Meduvo Health System Flow

A branded end-to-end guide to practice onboarding, staff registration, patient intake, assessment scoring, safety alerts, care-team roles, psychiatric review, billing, and reporting.

Starts With Practice intake

Public signup, compliance verification, and SuperAdmin approval before PHI access opens.

Patient Journey Screening to care plan

Patient registration, consent, SDOH, assessments, alerts, triage, and follow-up.

Care Team PCP, BHCM, psychiatrist

Role-specific responsibilities across warm handoff, care goals, recommendations, and billing.

Last reviewed: July 21, 2026 Meduvo Health

Meduvo Health System Flow

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:

How a practice registers:

  1. A practice opens /providers/register.
  2. The practice submits:
  3. The system creates a tenants row with:
  4. The practice sees a confirmation message that the practice is queued for compliance review.
  5. Email notifications are sent:

Important behavior:

3. Practice Compliance And Approval

Admin route:

Who can manage this:

Flow:

  1. SuperAdmin opens Practice Activation.
  2. SuperAdmin reviews the pending tenant.
  3. SuperAdmin marks:
  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:

4. System User Registration Flow

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

Staff management route:

Invitation acceptance route:

Roles that can be invited:

Who can invite:

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:
  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:
  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:

5. Role Responsibilities

SuperAdmin

Primary job: platform administration and tenant activation.

Can:

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:

PCP

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

Can:

BHCM

Primary job: coordinate behavioral health care.

Can:

Capacity:

Psychiatrist

Primary job: consultant/advisor to the care team.

Can:

Cannot:

Patient

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

Can:

Patient access is always restricted to their own patient profile.

6. Patient Registration Flow

Main web route:

Who can create patients:

Patient registration fields:

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:
  4. The system creates a patient_profiles row:
  5. Staff is redirected to the patient chart.
  6. The patient is ready for assessment assignment and kiosk/tablet handoff.

Patient search:

Current implementation note:

7. Assessment Assignment And Kiosk Flow

Patient chart route:

Kiosk launch routes:

Assessment APIs:

Assessment templates currently include:

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:
  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:

Consent endpoint:

Consent behavior:

  1. Patient signs CoCM consent from app or kiosk.
  2. Consent stores:
  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:

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:
  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-9/GAD-7 behavior:

How the system identifies patients who may need care:

  1. Basic CoCM status:
  2. Scored assessment results:
  3. PHQ-2 positive screen:
  4. Safety-risk flags:
  5. Registry risk engine:
  6. Psychiatrist review portal:

Important note:

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:
  6. Backend broadcasts a safety-alert event.
  7. Backend sends push notification to:
  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:
  4. Acknowledgement is broadcast so other open dashboards can update.
  5. Alert read/actions are PHI audit-logged.

Who responds:

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:

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:
  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:

Who can access:

What it shows:

BHCM-specific behavior:

13. Psychiatric Review Flow

Route:

Who can access:

Cases appear when:

Recommendation flow:

  1. Psychiatrist reviews case context.
  2. Psychiatrist writes recommendation.
  3. Psychiatrist chooses recipient:
  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:

14. Billing And Reporting Flow

Billing dashboard:

Reports:

Who can view billing dashboard:

Who can export claims:

Billing computation uses:

Reporting dashboard uses:

Claim readiness requires no documentation gaps.

Current documentation gaps checked:

Claim export:

15. Audit, Security, And Tenant Boundaries

Tenant approval:

Tenant isolation:

PHI audit:

Immutable or controlled records:

Kiosk hardening:

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.