Patient Management - Technical Specification

Core patient data management and demographics

Purpose

The Patient Management module serves as the foundational entry point for all medical-legal cases in the platform. It manages patient demographics, insurance information, and relationships to legal cases. Each patient can have multiple legal cases, and patient data is used throughout the system for prior authorizations, claims adjudication, medical records processing, and appointment scheduling.

Key Concepts

Term	Definition
Patient	Individual receiving medical care related to a legal case
Demographics	Personal information including name, DOB, address, contact details
Insurance Carrier	Primary/secondary insurance providers
Legal Case Relationship	One-to-many relationship between patient and legal cases
Patient Identifier	Unique system-generated ID for each patient
PHI	Protected Health Information - regulated under HIPAA
Consent	Patient authorization for treatment and information sharing

User Roles

Role	Description	Permissions
Patient Coordinator	Primary patient data management	Create, Read, Update
Case Manager	View patient info for case management	Read only
Medical Records Clerk	Attach documents to patient records	Read, Upload Documents
Claims Processor	Verify patient info for claims	Read only
System Administrator	Full access including deletion	All permissions
Attorney	View patients linked to their cases	Read only (filtered)

Field Documentation - Patient Entity

Field Name	Type	Required	Description	Validation Rules	Related Entity
ID	String	Yes	Unique patient identifier (CUID)	Auto-generated, immutable	Primary Key
First Name	String	Yes	Patient's legal first name	Max 100 chars, alpha only	-
Middle Name	String	No	Patient's middle name or initial	Max 100 chars	-
Last Name	String	Yes	Patient's legal last name	Max 100 chars, required	-
Date of Birth	DateTime	Yes	Patient's date of birth	Must be past date, format MM/DD/YYYY	-
SSN	String	No	Social Security Number (encrypted)	9 digits, unique, encrypted at rest	-
Gender	String	No	Patient's gender	Enum: Male, Female, Other, Unknown	-
Marital Status	String	No	Current marital status	Enum values	-
Email	String	No	Primary email address	Valid email format	-
Phone	String	Yes	Primary phone number	10 digits, format (XXX) XXX-XXXX	-
Mobile Phone	String	No	Mobile phone number	10 digits, format validation	-
Address	String	Yes	Street address	Max 200 chars	-
City	String	Yes	City	Max 100 chars	-
State	String	Yes	State code	2-letter state code	-
Zip Code	String	Yes	ZIP code	5 or 9 digits	-
Emergency Contact Name	String	No	Emergency contact full name	Max 200 chars	-
Emergency Contact Phone	String	No	Emergency contact phone	Phone format validation	-
Emergency Contact Relation	String	No	Relationship to patient	Enum values	-
Primary Insurance Carrier	String	No	Primary insurance company	Validate against carrier list	-
Primary Insurance Policy Number	String	No	Primary policy number	Alphanumeric	-
Primary Insurance Group Number	String	No	Primary group number	Alphanumeric	-
Secondary Insurance Carrier	String	No	Secondary insurance company	Validate against carrier list	-
Secondary Insurance Policy Number	String	No	Secondary policy number	Alphanumeric	-
Secondary Insurance Group Number	String	No	Secondary group number	Alphanumeric	-
Preferred Language	String	No	Preferred communication language	ISO language code	-
Interpreter Needed	Boolean	No	Requires interpreter services	Default false	-
Created At	DateTime	Yes	Record creation timestamp	Auto-generated	-
Updated At	DateTime	Yes	Last modification timestamp	Auto-updated	-
Created By	User	No	User who created record	Valid user ID	User
Updated By	User	No	User who last updated	Valid user ID	User
Legal Cases	LegalCase[]	No	Associated legal cases	-	LegalCase (1:Many)
Documents	Document[]	No	Attached documents	-	Document (1:Many)
Appointments	Appointment[]	No	Patient appointments	-	Appointment (1:Many)

Workflows

Patient Registration Workflow

1. Initial Data Collection

   • Collect demographic information
   • Verify SSN uniqueness
   • Capture insurance information

2. Validation

   • Validate all required fields
   • Check for duplicate patients (SSN, DOB, Name match)
   • Verify insurance eligibility (if applicable)

3. Patient Creation

   • Generate unique patient ID
   • Encrypt sensitive data (SSN, DOB)
   • Create audit log entry
   • Send welcome communication (if enabled)

4. Post-Creation

   • Available for legal case assignment
   • Ready for appointment scheduling
   • Document upload enabled

Patient Search Workflow

1. Search by name, DOB, SSN (last 4), patient ID
2. Apply role-based filtering
3. Return paginated results
4. Display match confidence score

Patient Update Workflow

1. Lock record for editing
2. Validate changes against business rules
3. Log all changes in audit trail
4. Update timestamp and user
5. Trigger dependent updates (if needed)

Business Rules

Required Fields

• First Name, Last Name
• Date of Birth
• Phone Number
• Address, City, State, Zip Code

Validation Rules

• Patient must be at least 18 years old (or have guardian info)
• SSN must be unique across system
• Email format must be valid if provided
• Phone numbers must be 10 digits
• State must be valid US state code

Data Privacy Rules

• SSN must be encrypted at rest
• PHI access must be logged
• Minimum necessary principle applies
• Patient consent required for data sharing

Integrations

System	Integration Type	Purpose
Legal Case Management	Direct Database	Patient assignment to cases
Appointment Scheduler	Direct Database	Patient appointment booking
Claims Processing	Direct Database	Patient verification for claims
Document Management	File System	Patient document storage
Insurance Verification	External API	Real-time eligibility checks
Address Validation	External API	USPS address standardization

Common Issues

Issue	Description	Resolution
Duplicate Patients	Same patient registered multiple times	Merge patient records tool
Invalid Insurance	Insurance information cannot be verified	Manual verification process
Missing Demographics	Required fields incomplete	Data completion workflow
Address Mismatch	Address doesn't validate with USPS	Manual override option

Screenshots Needed

• Patient Registration Form
• Patient Search Interface
• Patient Profile View
• Patient Edit Form
• Insurance Information Tab
• Document Upload Interface
• Patient Merge Tool
• Audit History View

Performance Considerations

• Patient search should return results in < 2 seconds
• Encryption/decryption should not impact user experience
• Support for 100,000+ patient records
• Concurrent user access handling

Security Considerations

• Role-based access control (RBAC)
• PHI encryption at rest and in transit
• Audit logging for all patient data access
• Session timeout for inactive users
• Multi-factor authentication for sensitive operations

Notes

• Patient records cannot be deleted, only deactivated
• All patient data changes are audited
• Integration with state immunization registries planned for future release