Care Team Workflows

Care Team Workflows

Who this is for: care-team/consent-coordinator staff, admins, doctors, new hires.

The case (task) lifecycle

Every purchase becomes a case with a status that changes as it moves through the system, for example: unscheduled, scheduled, under review, missing a document, on hold, ready for packaging, completed, refunded, canceled, expired, or missed appointment. Staff and doctors move a case forward by taking action on it (approving it, requesting missing information, marking it printed, etc.). This case-level status is separate from the records-request status described below — a single case can have its own record request going through the care-team queues while the case itself sits in a different status.

The care-team queues are about one specific workflow: getting a patient’s outside medical records

Correction from an earlier pass of this wiki: the care-team queues are not a general “case needs attention” list. They are specifically the work queue for release-of-records requests — the process of contacting a patient’s outside clinic/doctor to obtain their existing medical records on the patient’s behalf (see Consent & Agreement Documents for what a records request is). Every queue below is a filtered view over that same records-request list, not over cases/tasks in general.

A records request moves through these statuses, each with its own queue:

• New — request just created, no outreach attempted yet
• Voicemail (VM) — staff called the clinic and left a voicemail
• Contacted — staff reached someone at the clinic and got a promised turnaround date
• Received — records came back from the clinic
• Insufficient — the records that came back weren’t complete/usable
• Incorrect — something about the request itself (clinic info, etc.) needs correcting
• Resolved — the request is fully closed out
• Unresponsive — the clinic hasn’t answered after a set number of voicemail attempts

Two additional queues are computed dynamically from configurable day-thresholds rather than being their own status:

• Overdue — a request is flagged overdue if it’s sat too long in one of several states past its configured threshold: still “New” past 3 days (default), still on “Voicemail” past 2 days, “Contacted” past its promised turnaround date plus 10 days, “Received” past 3 days without being checked off, or “Insufficient” past 3 days without a follow-up.
• Consent overdue — a request is flagged if it isn’t yet “Resolved” or “Incorrect” and was created more than 5 days ago (default) — this tracks the release-of-records consent specifically, distinct from the general overdue thresholds above.

All five day-thresholds above (3, 2, 10, 3, 5) are admin-configurable platform settings, not fixed in code — an admin can tighten or loosen them without an engineer needing to change anything.

There’s also a separate Faxes queue (inbound/outbound fax handling for clinics that only accept requests by fax) and an Active view (requests still in “New” or “Voicemail” status). Reviewed is a second view onto the same “Resolved” requests as the Resolved queue above, not a distinct stage.

Staff move a request between these queues as they work it, and each queue is a saved filter over the same underlying records-request list.

Saved filters (“Views”)

Across the admin and provider areas, staff can build and save their own filtered/sorted views of the general case list (for example, “my Florida cases with status X”) — separate from the records-request queues above, which are their own dedicated system. These saved views turn a set of filter choices into a reusable, named shortcut for case lists specifically.

Doctor case-assignment priority (admin-only)

Admins have a dedicated screen for setting each doctor’s priority weighting, per state, for automatic case assignment — this is the configuration behind the “priority weighting” mentioned in Scheduling & appointments for services that don’t use a live appointment booking. Admins can also export the current priority setup to a spreadsheet.

Provider filters (admin-only)

A separate admin screen lets an admin build and save filter presets specifically for provider/doctor case lists (by state, task status, task type, tag, and payment status) — distinct from the general saved “Views” above, and scoped to managing what doctors see in their own task queues.

In-app conversation oversight (admin-only)

Admins have their own view of every in-app message thread across all cases and patients (not filtered to one case), for oversight and stepping into a conversation directly — using the same thread component that appears elsewhere for staff and providers. See Messaging & notifications for how in-app messaging works.

Provider (doctor) workflow

1. New cases assigned to a doctor appear in that doctor’s task list.
2. The doctor opens a case, reviews the patient’s intake answers and uploaded documents, and (if applicable) their own visit notes.
3. The doctor approves the case, which allows the official document to be generated and signed (see Document generation & e-signature).
4. Doctors have their own analytics and payment-history views to track their caseload and earnings.

Follow-ups

Cases can have follow-up messages/reminders attached to them — used to nudge a patient (or flag to staff) when something is still outstanding on a case. This is a distinct mechanism from the scheduled appointment reminders described in Messaging & notifications.

Case labels

Cases can be tagged with labels for quick visual sorting/filtering in staff task lists, managed through a dedicated labels screen. This is separate from a case’s “task type” and “task tag” (see Glossary) — labels are a free-form organizational layer staff add on top.

Case creation (staff-initiated)

Besides a patient buying a service themselves (see Onboarding & signup), staff can also create a case directly from the admin area on a patient’s behalf — used, for example, when a case originates from a phone call or another channel instead of the patient completing the online funnel themselves.

Open questions

• Whether staff can manually move a request between queues outside of the automatic day-threshold rules above (e.g. manually flagging something overdue early) was not confirmed.
• Whether every one of the several near-duplicate “task label” API endpoints found in the code (three separate routes that read/write case labels) is actively used by the current UI, or whether some are leftover from a past refactor, was not confirmed.

Where this comes from

• parkingmd-care-portal/docs/care-portal-kt-guide.md
• parkingmd-care-portal/src/app/(main)/care/ (queue folder names: active, consent-overdue, contacted, dashboard, faxes, incorrect, insufficient, overdue, received, resolved, reviewed, unresponsive)
• parkingmd-care-portal/src/app/api/care/requests/route.ts (the actual overdue/consent-overdue day-threshold logic, medicalRecordRequests queries)
• parkingmd-care-portal/src/lib/constants.ts (CARE_SETTINGS_KEYS, CARE_SETTINGS_DEFAULTS, CARE_STATUS, CARE_STATUS_LABELS)
• parkingmd-care-portal/src/server/db/schema.ts (medicalRecordRequests)
• parkingmd-care-portal/src/app/(main)/care/_components/CareRequestList.tsx, CareSidebar.tsx, CareStatusBadge.tsx
• parkingmd-care-portal/src/lib/tasks/
• parkingmd-care-portal/src/lib/filters/
• parkingmd-care-portal/src/lib/followups/
• parkingmd-care-portal/src/app/(main)/provider/[doctorId]/
• parkingmd-care-portal/src/app/(main)/admin/priority/page.tsx, parkingmd-care-portal/src/lib/provider/action.ts (getDoctorPriorities, upsertDoctorPriorities)
• parkingmd-care-portal/src/app/(main)/admin/provider-filters/page.tsx, parkingmd-care-portal/src/lib/filters/provider-filter-action.ts
• parkingmd-care-portal/src/app/(main)/admin/threads/page.tsx, parkingmd-care-portal/src/app/(main)/_components/shared/ThreadsPage.tsx
• parkingmd-care-portal/src/app/api/labels/route.ts, .../labels/[id]/route.ts, .../labels/task-labels/route.ts, .../labels/tasks/route.ts, .../tasks/labels/route.ts, .../tasks/[id]/labels/route.ts
• parkingmd-care-portal/src/app/api/create/patient-task/route.ts, .../admin/tasks/new/route.ts (staff-initiated case creation — the live routes; parkingmd-care-portal/src/app/api/task/route.ts is present but fully commented out/dead)