Skip to main content
This screen lists Level-of-Care (LoC) assessments for the current organization and is available at /cl/loc-assessments.

​
Overview

The LoC Assessments list page renders all records from cl_loc_assessments scoped to the current organization, using the LocAssessmentListTable component. Records are filtered to non-deleted rows and ordered by assessed_at descending. An instrument filter dropdown allows narrowing the list to ASAM or LOCUS assessments, or showing all instruments. Users see a New Assessment button that navigates to /cl/loc-assessments/new. Clicking a row in the table navigates to the detail page at /cl/loc-assessments/:assessmentId. The signing flow requires a final_loc_code; when this differs from recommended_loc_code, an override_reason_code and a rationale of at least 20 characters are required (enforced client-side and by a DB trigger).

​
Who it’s for

Requires permission: cl.loc_assessment.view Creating new assessments additionally requires: cl.loc_assessment.create

​
Before you start

You must hold cl.loc_assessment.view to access this page. Assessments are scoped to your current organization.

​
Steps

1

Open LoC Assessments

Navigate to /cl/loc-assessments. All non-deleted assessments for your organization load, ordered most recent first.
2

Filter by instrument (optional)

Use the instrument dropdown (All Instruments / ASAM / LOCUS) to narrow the list.
3

Review the assessments table

The table is rendered by LocAssessmentListTable. Click any row to open the detail page at /cl/loc-assessments/:assessmentId.
4

Create a new assessment (if permitted)

Click New Assessment (requires cl.loc_assessment.create) to navigate to /cl/loc-assessments/new.

​
Key concepts

The dropdown maps to instrument_type column values: asam and locus. Selecting “All Instruments” removes the filter.
The status field progresses to signed upon finalization. The signing mutation sets signed_at and signed_by. An override (where final_loc_code !== recommended_loc_code) requires a reason code and rationale.
The list table component (LocAssessmentListTable) receives an isLoading prop and handles the skeleton/loading state internally.

​
Creating a LoC assessment

The New LoC Assessment page at /cl/loc-assessments/new allows a clinician to create a new level-of-care assessment. Requires cl.loc_assessment.create. The page accepts optional patientId and priorId URL search params for pre-population. The user selects an instrument type (asam or locus) and enters (or confirms) a patient ID. When a prior assessment ID is supplied via priorId, a LocTransitionRecommendationCard and a LocReassessmentDeltaTable are displayed above the form, showing the prior recommended LoC code, the current preview recommendation, and a dimensional delta table. The LocAssessmentForm component captures dimensional scores and emits a recommended_loc_code on change. On save, useCreateLocAssessment creates the record in cl_loc_assessments with status: 'draft' and navigates to the detail page at /cl/loc-assessments/:id. The new record links to the prior assessment via supersedes_id when reassessing. Before you start: have the patient’s chart ID available (the page accepts a patientId query param, or you can type it into the Patient ID field). To reassess from a prior assessment, include a priorId query param with the prior assessment’s ID.
1

Navigate to New LoC Assessment

Go to /cl/loc-assessments/new. Optional: append ?patientId=<id> and/or ?priorId=<priorAssessmentId> to pre-populate the form.
2

Enter the patient ID

Type the patient chart ID in the Patient ID field, or confirm the pre-populated value from the URL param.
3

Select the instrument type

Choose “ASAM Criteria (Substance Use)” or “LOCUS (Mental Health)” from the Instrument dropdown. The default is asam.
4

Review prior assessment delta (reassessment only)

If a prior assessment was loaded via priorId, the LocTransitionRecommendationCard shows the prior final LoC code vs. the current preview recommendation. The LocReassessmentDeltaTable shows per-dimension score changes.
5

Complete dimensional scoring

Fill in the dimensional scores in the LocAssessmentForm. The form emits a recommended_loc_code preview as scores change.
6

Save the assessment

Click Save in the LocAssessmentForm. The assessment is created with status: 'draft' and you are redirected to the detail page at /cl/loc-assessments/:id to review and sign.
The instrument_type field accepts asam or locus. Labels rendered in the UI are “ASAM Criteria (Substance Use)” and “LOCUS (Mental Health)”. Clinical scoring rules for each instrument are not implemented in this component.
When priorId is provided, useLocAssessmentReassess loads the prior record and seeds the form with its dimension_scores. computeDirection compares the new total score to the prior total: step_up (new > prior), step_down (new < prior), or lateral (equal). The new record is linked via supersedes_id.
New assessments are created with status: 'draft'. Signing (via useSignLocAssessment on the detail page) sets status: 'signed' and records signed_at and signed_by. If final_loc_code !== recommended_loc_code, an override_reason_code and override_rationale (minimum 20 characters) are required.

​
Detail view

This screen displays the detail of a single Level-of-Care assessment record at route /cl/loc-assessments/:assessmentId.

​
Overview

The LoC Assessment detail page loads a single assessment from the cl_loc_assessments table using the assessmentId URL parameter. It displays the instrument type (ASAM or LOCUS), the date and time of the assessment, and a status badge (draft, finalized, or amended). The Summary tab shows a dimensional profile radar chart and a recommendation card. When a prior assessment exists for the same patient and instrument type, a Comparison tab appears showing side-by-side dimension scores. For draft assessments, action buttons allow the clinician to accept the computed recommendation or open an override dialog to record a different Level-of-Care with a reason category and rationale.

​
Who it’s for

Requires the cl.loc_assessment.view permission. The Override button additionally requires cl.loc_assessment.override. The Accept Recommendation button additionally requires cl.loc_assessment.sign.

​
Before you start

  • You must hold the cl.loc_assessment.view permission for your organization.
  • The assessment must exist in the system; navigating to an unknown assessmentId renders an “Assessment not found” message with a link back to the list.
  • To finalize with an override, you must also hold cl.loc_assessment.override and cl.loc_assessment.sign.

​
Steps

1

Open an assessment from the list

Navigate to /cl/loc-assessments and select a record, or follow a direct link to /cl/loc-assessments/:assessmentId.
2

Review the Dimensional Profile

On the Summary tab, inspect the radar chart showing per-dimension scores. If a prior assessment exists, a previous-score overlay is rendered for comparison.
3

Review the recommendation card

The Recommendation card displays the system-computed recommended_loc value derived from computeLocRecommendation. If a final LoC has been set and differs from the recommendation, the card indicates the assessment is overridden.
4

Compare with a prior assessment (if available)

If a prior assessment exists for the same patient and instrument type, select the Comparison tab to view the LocAssessmentComparisonView side-by-side display.
5

Accept the recommendation or override (draft only)

For draft assessments, either click Accept Recommendation to finalize with the computed LoC, or click Override (requires cl.loc_assessment.override) to open the LocOverrideDialog. In the dialog, select a reason category and enter a rationale of at least 20 characters, then confirm.

​
Key concepts

The instrument_type field is either asam or locus. ASAM assessments use six dimensions (acute_intoxication, biomedical_conditions, emotional_behavioral_cognitive, readiness_to_change, relapse_continued_use, recovery_environment). LOCUS assessments use six dimensions (risk_of_harm, functional_status, medical_comorbidity, recovery_environment, treatment_history, engagement).
The status field follows the values draft, finalized, and amended. Action buttons for accepting a recommendation or overriding are only visible when status === 'draft'.
An override occurs when the final_loc set on the assessment differs from recommended_loc. An override requires a OverrideReasonCategory selection and a rationale string; the database enforces a minimum rationale length of 20 characters.
If the assessment record is not found or does not belong to the current organization, the page renders: “Assessment not found.” with a Back to List button.

Clinical

Overview of the Clinical core.

Governance & parity

Documentation coverage and governance.
This page documents shipped product behavior. It is not medical, legal, or billing advice. Verify against your organization’s policies and applicable regulations before using it for clinical, compliance, or billing decisions. Protected health information (PHI) shown in the product is governed by your tenant’s access controls and is never exposed in this documentation.
  • src/routes/cl.tsx
  • src/cores/cl/pages/LocAssessmentListPage.tsx
  • src/cores/cl/hooks/useLocAssessments.ts
  • src/cores/cl/pages/LocAssessmentNewPage.tsx
  • src/cores/cl/pages/LocAssessmentDetailPage.tsx
  • src/cores/cl/types/loc-assessment.ts