Medical Terminology & Code Libraries — Admin Guide

This guide covers code set loading, effective dating, modifier configuration, payer rule management, and troubleshooting for the PF-70 Medical Terminology & Code Library.

​

Table of Contents

1. Overview
2. Prerequisites
3. Code Set Loading
4. Annual Code Set Update Process
5. Modifier Configuration
6. Payer Rule Configuration
7. Dev Seed Data
8. Troubleshooting

​

Overview

• Platform-managed codes (organization_id IS NULL) — readable by all authenticated users in all orgs.
• Org-scoped modifiers/payer rules (organization_id IS NOT NULL) — visible only within the owning organization.
• User-scoped data (pf_code_favorites, pf_code_recent) — visible only to the owning user.

​

Prerequisites

• You must have pf.codes.admin permission (typically granted to org_admin and platform_admin roles).
• For platform-managed code sets, mutations require a Supabase service role or migration script (RLS blocks app-layer writes on platform-managed tables).
• Effective dates must be verified against CMS or the relevant governing body’s published release.

​

Code Set Loading

​

How Platform Code Sets Work

-- Example: ICD-10-CM FY 2026
INSERT INTO pf_code_sets (
  code_set,        -- 'ICD10CM', 'CPT', 'HCPCS'
  version,         -- Human-readable version label, e.g. '2026'
  effective_from,  -- CMS release date (YYYY-MM-DD)
  effective_to,    -- NULL for current version; set when superseded
  organization_id, -- NULL = platform-managed (readable by all orgs)
  is_active,
  description
)
VALUES ('ICD10CM', '2026', '2025-10-01', NULL, NULL, TRUE, 'ICD-10-CM FY 2026 — CMS release');

​

Loading Individual Codes

-- Example: batch insert ICD-10-CM codes
INSERT INTO pf_icd10_codes (
  code_set_id,
  code,
  description,
  effective_from,
  effective_to,      -- NULL = no known expiry
  is_behavioral_health,
  is_sdoh
)
VALUES
  ('<code_set_id>', 'F32.1', 'Major depressive disorder, single episode, moderate', '2025-10-01', NULL, TRUE, FALSE),
  ('<code_set_id>', 'Z59.0', 'Homelessness',                                        '2025-10-01', NULL, FALSE, TRUE),
  -- ... additional rows
;

Important: Never hard-delete existing codes. Use effective_to to retire them.

​

Loading CPT and HCPCS Codes

INSERT INTO pf_cpt_codes (code_set_id, code, description, effective_from, effective_to, is_behavioral_health, category)
VALUES ('<code_set_id>', '90837', 'Psychotherapy, 60 minutes', '2025-01-01', NULL, TRUE, 'Psychiatry');

INSERT INTO pf_hcpcs_codes (code_set_id, code, description, effective_from, effective_to, is_behavioral_health, category)
VALUES ('<code_set_id>', 'H0038', 'Self-help/peer services, per 15 minutes', '2025-01-01', NULL, TRUE, 'Community Support');

​

Where to Run Load Scripts

• Development/Staging: Supabase Dashboard → SQL Editor (https://supabase.com/dashboard/project/{project_id}/sql/new)
• Production: Via a reviewed and approved migration script in supabase/migrations/ or Supabase SQL Editor with Live environment selected.

​

Annual Code Set Update Process

​

Step-by-Step Update Procedure

• ICD-10-CM: Download the CMS flat file from cms.gov/Medicare/Coding/ICD10
• CPT: AMA annual CPT data file (licensed)
• HCPCS: CMS HCPCS quarterly update files

-- New version; DO NOT touch old code_set row
INSERT INTO pf_code_sets (code_set, version, effective_from, organization_id, is_active, description)
VALUES ('ICD10CM', '2026', '2025-10-01', NULL, TRUE, 'ICD-10-CM FY 2026');

SELECT id FROM pf_code_sets WHERE code_set = 'ICD10CM' AND version = '2026';
-- Use this ID for all code inserts

-- Set effective_to on the superseded code set (not DELETE)
UPDATE pf_code_sets
SET effective_to = '2025-09-30'  -- last valid day of old version
WHERE code_set = 'ICD10CM'
  AND version = '2025'
  AND organization_id IS NULL;

// In browser console or test:
import { searchCodes } from '@/platform/codes';
const result = await searchCodes({ codeSet: 'ICD10CM', query: 'F32', effectiveDate: '2025-10-15', organizationId: orgId });
console.log(result.results); // Should include FY2026 codes

​

Rollback Procedure

1. Clear the affected pf_icd10_codes / pf_cpt_codes / pf_hcpcs_codes rows by the new code_set_id:
   DELETE FROM pf_icd10_codes WHERE code_set_id = '<new_bad_code_set_id>';
   DELETE FROM pf_code_sets WHERE id = '<new_bad_code_set_id>';
   
2. Restore the previous version’s effective_to to NULL if it was incorrectly retired.

​

Modifier Configuration

​

Who Can Configure Modifiers

​

Adding a Modifier

INSERT INTO pf_code_modifiers (
  organization_id,
  modifier_code,
  description,
  effective_from,
  effective_to,         -- NULL = no expiry
  applicable_code_sets, -- array: ['CPT'], ['HCPCS'], or ['CPT', 'HCPCS']
  created_by
)
VALUES (
  '<your_org_id>',
  'GT',
  'Via interactive audio/video telecommunication systems',
  '2025-01-01',
  NULL,
  '["CPT", "HCPCS"]',
  auth.uid()
);

​

Retiring a Modifier

UPDATE pf_code_modifiers
SET effective_to = '2025-12-31'
WHERE organization_id = '<your_org_id>'
  AND modifier_code = 'GT'
  AND deleted_at IS NULL;

​

Payer Rule Configuration

Note: payer_id is a bare UUID referencing the PM-layer payer. There is no FK to pm_payers (architecture decision C-3: no PF→PM boundary crossing).

​

Supported Rule Types

​

Adding a Payer Rule

INSERT INTO pf_payer_code_rules (
  organization_id,
  payer_id,       -- bare UUID from pm_payers (no FK)
  code_set,       -- 'ICD10CM', 'CPT', 'HCPCS'
  code,
  rule_type,      -- 'denied' | 'prior_auth' | 'requires_modifier'
  rule_config,    -- JSONB: e.g. {"required_modifier": "GT"} for requires_modifier
  effective_from,
  effective_to    -- NULL = no expiry
)
VALUES (
  '<your_org_id>',
  '<payer_uuid>',
  'CPT',
  '90837',
  'requires_modifier',
  '{"required_modifier": "GT"}',
  '2025-01-01',
  NULL
);

​

Dev Seed Data

​

Troubleshooting

​

Search returns no results

1. Check code set exists and is active:
   SELECT * FROM pf_code_sets WHERE code_set = 'ICD10CM' AND is_active = TRUE;
   
2. Check effective date: The search filters to codes where effective_from <= today AND (effective_to IS NULL OR effective_to >= today). Ensure your seed/load date covers the queried date.
3. Check RLS: Run the query as an authenticated user. Platform code sets (organization_id IS NULL) should be visible to all users. Run SELECT pf_can_read_code_set('<code_set_id>') in the SQL editor to test the SECURITY DEFINER helper.

​

Permission denied on INSERT/UPDATE

• Verify the user has pf.codes.admin permission:
  SELECT * FROM pf_module_permissions WHERE permission_key = 'pf.codes.admin';
  SELECT * FROM pf_role_permissions WHERE permission_key = 'pf.codes.admin';
  
• Platform-managed code tables (pf_icd10_codes, pf_cpt_codes, pf_hcpcs_codes) block all app-layer mutations (by design). Loads must be done via service role or migration.

​

loinc_unavailable: true in search metadata

​

validateCode returns unexpected errors

• Ensure sanitizeErrorMessage is wrapping all DB errors in validateCode.ts.
• Check the Supabase Edge Function logs if the validation is called via an edge function context.
• For payer rule issues, verify payer_id is the correct UUID (no FK enforcement — it is the caller’s responsibility to pass the correct UUID).

​

Related Docs

• PF-70 Spec
• PF-70 Integration Doc
• Platform Integration Layers
• Permissions Quick Reference
• Supabase SQL Editor