Domain Models

All models are derived from the Django apps in novahomecareapi/. Every tenant-scoped model carries a FK to Organization. Soft-deletion (SoftDeletableModel) and timestamping (TimeStampedModel) are applied where noted.

---

Table of Contents

• organizations
• users
• applications
• assessments
• competency_checklists
• competency_tests
• compliance_documents
• grievances
• job_forms
• messages
• notes
• notifications
• referrals
• services
• support
• work_schedules

---

organizations

Organization

Root tenant model. Every other model scopes to this via FK.

Field	Type	Notes
name	CharField	Display name
health_name	CharField	Name used in Home Health context
token	UUIDField	Unique; used in public-facing portal URLs (/login/<token>)
short_name	CharField	Abbreviated name
email	EmailField	Org contact email
phone	CharField
address, city, state, zipcode	CharField
style	JSONField	Custom CSS/branding overrides served to portals SPA
logo, favicon	FileField	S3-stored branding assets
url	URLField	Org website
active	BooleanField	Soft on/off for the whole tenant

Key methods: get_administrators(), to_dict(), get_service_names()

---

users

User

Single table for all roles (extends AbstractUser + SoftDeletableModel).

Field	Type	Notes
role	CharField	MASTER / ADMIN / EMPLOYEE / CLIENT / MARKETER
organization	FK → Organization
email	EmailField	Primary login identifier
phone, secondary_phone	CharField	E.164 format
gender	CharField	Choice field
marital_status	CharField	Choice field
address, city, state, zipcode	CharField
timezone	CharField
profile_image	FileField	S3
zip_file	FileField	Bulk export zip
signature	—	Handled via Signature model (see job_forms)

Custom managers: UserManager, EmployeeManager, ClientManager, AdminManager, MasterManager, MarketerManager — each pre-filters by role.

Key properties: full_name, age, is_health_available

Key methods: get_applications(), get_competency_tests(), get_forms(), get_notes(), get_grievances(), get_work_schedules(), get_service_visits(), get_service_plans()

---

EmployeePosition

Lookup table for staff roles. Controls which documents and checklists are generated.

Field	Type	Notes
key	CharField	HCC, CNA, HHA, RN, LPN, ST (SLP), OT, PT, MSW, ADM, MKT
label	CharField	Human-readable name
is_health	BooleanField	True for clinical roles (RN, LPN, CNA, HHA, PT, OT, ST, MSW)
is_oasis	BooleanField	True for roles that document OASIS assessments
is_home_care	BooleanField	True for HC-eligible roles

The is_health / is_oasis / is_home_care flags drive document generation logic — e.g. competency checklists are only generated for positions where the flag is set. See Employee Documents.

---

JobOffer

An employment offer extended to an applicant.

Field	Type	Notes
user	FK → User	The applicant receiving the offer
position	FK → EmployeePosition
salary	DecimalField
start_date	DateField
payment_rates	JSONField	Rate structure
compensation	JSONField	Additional compensation details
status	CharField	NEW / REJECTED / ACCEPTED

---

EmployeeProfile

Extended profile for EMPLOYEE users (OneToOne with User).

Field	Type	Notes
user	OneToOneField → User
manager	FK → User	Assigned manager/supervisor
position	FK → EmployeePosition	Current role
salary	DecimalField
payment_rates	JSONField
external_id	CharField	ID in external payroll / HR system
sos_*	CharField fields	Emergency contact name, phone, relationship
health_license_*	CharField/DateField	License number, state, expiration
cpr_certification_date, cpr_expiration_date	DateField
forms	—	Tracking fields for onboarding form completion

---

ClientType

Lookup table. Determines which admission document set applies.

Key	Meaning
HCC	Home Care Client
HHP	Home Health Patient

---

ClientProfile

Extended profile for CLIENT users (OneToOne with User).

Field	Type	Notes
user	OneToOneField → User
client_types	M2M → ClientType	HC, HH, or both — drives dynamic nav (see Client Profile)
soc	DateField	Start of Care
insurance	CharField / JSONField	Insurance details
primary_condition	CharField	Primary diagnosis/condition
sos_*	CharField fields	Emergency contact
designated_representative_*	CharField fields	Legal rep / power of attorney
case_manager_*	CharField fields	Referring physician / case manager contact
allergies	TextField	Medical history
advance_directives	BooleanField / CharField
dnr	BooleanField	Do Not Resuscitate
triage_code	CharField
manual_upload_documents	BooleanField	Flag to allow admin manual document uploads

---

applications

Application

Job application submitted by a prospective employee.

Field	Type	Notes
organization	FK → Organization
user	FK → User	Applicant
position	FK → EmployeePosition	Applied-for role
status	CharField	NEW → PRE_APPROVED → RBC → BCC → APPROVED / REJECTED / BCE
Personal fields	CharField	First/last name, DOB, SSN, address, phone, email
training	JSONField	Training history
education	JSONField	Education history
job_history	JSONField	Previous employment
references	JSONField	Professional references
signature	FileField	Signature image
pdf	FileField	Generated application PDF
health_license_*	CharField/DateField	License number, state, expiration
cpr_certification_date, cpr_expiration_date	DateField
contact_opt_in	BooleanField	SMS/marketing consent

Status flow: NEW → PRE_APPROVED → RBC (Reference & Background Check initiated) → BCC (Background Check Complete) → APPROVED or REJECTED; BCE = Background Check Exception.

---

ApplicationFile

Individual supporting documents attached to an application.

Field	Type	Notes
application	FK → Application
type	CharField	See choices below
file	FileField	S3
expiration_date	DateField	Nullable
active_date	DateField	Nullable
completed_date	DateField	Nullable

File type choices:

Key	Meaning
ID	Government-issued ID
SSN	Social Security card
TBT	TB Test
OIG	OIG exclusion check
NSO	Non-Sex Offender registry check
IN	Proof of Insurance
DDB
BCC	Background Check (consent)
BCR	Background Check (report)
CPR	CPR certification
RU
HSP

---

assessments

OASISAssessment

Clinical outcome tracking document. Home Health and Both clients only.

Field	Type	Notes
caregiver	FK → User	The HH employee who completed the assessment
category	CharField	INITIAL / REVALIDATION
completed_date	DateField
expiration_date	DateField
file	FileField	S3

Property: is_expired — true if expiration_date < today.

---

competency_checklists

ChecklistAssessmentForm

Template/definition for a competency assessment checklist (distinct from CompetencyTest which is a quiz).

Field	Type	Notes
key	CharField	Identifier (e.g. RN, LPN, CNA_HHA, ANNUAL)
label	CharField	Display name
employee_positions	M2M → EmployeePosition	Which roles this checklist applies to
is_annually_renew	BooleanField	True for the Annual Competency Checklist
pdf_preview	FileField	Preview PDF
pdf_template	FileField	Template used to generate filled PDF
creator	FK → User	Admin who created the form definition

---

ChecklistAssessment

An instance of a checklist assigned to a specific employee.

Field	Type	Notes
organization	FK → Organization
assessment_form	FK → ChecklistAssessmentForm
user_assigned	FK → User	The employee
user_assigner	FK → User	The admin who assigned it
file	FileField	Completed/signed PDF
answers	JSONField	Employee responses
is_important	BooleanField	Flags high-priority items
is_manually_submitted	BooleanField	True if admin uploaded instead of using the portal flow
signing_status	CharField	UNS (Unsigned) / SHA (Shared) / SIG (Signed)
completion_date	DateField

Method: sign() — transitions signing_status to SIG and sets completion_date.

---

competency_tests

The competency test app is a scored quiz engine, separate from the checklist app above.

CompetencyTest

Definition of a knowledge test.

Field	Type	Notes
name, description	CharField/TextField
minimum_score	IntegerField	Default: 75 (passing threshold)
pdf_template, html_template	FileField	For generating the PDF result
validations, answers	JSONField	Answer key and validation rules
steps	—	Defined via CompetencyTestStep
onboarding	BooleanField	Assigned during onboarding
renewal	BooleanField	Assigned on annual renewal cycle
renewal_delta	IntegerField	Days until renewal is due
version	CharField	Unique; used for versioning test content

---

CompetencyTestStep

An ordered section/page within a CompetencyTest.

Field	Type	Notes
competency_test	FK → CompetencyTest
name	CharField
order	IntegerField	Determines display sequence
mdx	TextField	Step content (MDX / Markdown with components)
validations, extended_validations	JSONField	Per-step validation rules

---

CompetencyTestSubmission

A completed attempt at a CompetencyTest.

Field	Type	Notes
answers	JSONField	Employee's submitted answers
score	IntegerField	Calculated score
approved	BooleanField	True if score ≥ minimum_score
pdf	FileField	Generated result PDF
expiration_date	DateField	When re-testing is required
completed_date	DateField
manually_loaded	BooleanField	Admin bypass / manual upload

---

CompetencyTestRequest

Join record linking a test to an employee for a given org. One request per employee-test assignment.

Field	Type	Notes
competency_test	FK → CompetencyTest
employee	FK → User
organization	FK → Organization
submission	OneToOneField → CompetencyTestSubmission	Nullable until submitted

Method: submit(answers) — creates a CompetencyTestSubmission, scores it, auto-approves if score ≥ minimum.

---

compliance_documents

Introduced in v5.1.0. Dual-signature flow: client signs first, then Case Manager. See Compliance Documents.

CaseManager

External physician/provider who co-signs compliance documents. Has no portal account.

Field	Type	Notes
full_name	CharField
email	EmailField	OTP is sent here
organization	FK → Organization
creator	FK → User	Admin who registered this Case Manager

Unique constraints: (full_name, email, organization) and (email, organization).

---

ComplianceDocumentForm

Template/definition for a compliance document type.

Field	Type	Notes
key	CharField	Identifier
label	CharField	Display name
pdf_preview	FileField
pdf_template	FileField
creator	FK → User
organizations	M2M → Organization	Which orgs have access to this form type

---

ComplianceDocument

An instance of a compliance document assigned to a client. Tracks both user and Case Manager signing independently.

Field	Type	Notes
organization	FK → Organization
compliance_form	FK → ComplianceDocumentForm
user_assigned	FK → User	The client
user_assigner	FK → User	The admin who assigned it
case_manager	FK → CaseManager	The co-signer
case_manager_signature	FileField	Case Manager's signature image
case_manager_comment	TextField	Optional comment from Case Manager
file	FileField	Final signed PDF
answers	JSONField	Client's form responses
is_important	BooleanField
is_manually_submitted	BooleanField
user_signing_status	CharField	PEN (Pending) / SIG (Signed)
manager_signing_status	CharField	PEN (Pending) / SIG (Signed)
user_completion_date	DateField	When client signed
manager_completion_date	DateField	When Case Manager signed
completed_date	DateField	Set when both have signed
last_reminder_sent	DateTimeField	Tracks reminder email cadence

---

grievances

Grievance

A formal grievance raised by an employee. Extends SoftDeletableModel and ExportableModel.

Field	Type	Notes
organization	FK → Organization
employee	FK → User
subject	CharField
body	TextField
is_read	BooleanField	Admin read receipt
file_to_export	FileField	Generated PDF export

Method: export() — renders the grievance to PDF and stores in file_to_export.

---

job_forms

The core document engine. Form defines a document template; FormRequest is the per-user assignment; FormSubmission is the completed record.

Form

Field	Type	Notes
name, description	CharField/TextField
type	CharField	FILLABLE (portal renders fields) / UPLOADABLE (user uploads a file)
submitter	CharField	ADMIN / EMPLOYEE / CLIENT / MASTER — who completes this form
category	CharField	See choices below
pdf_template, html_template	FileField	Used by WeasyPrint to generate PDF
mdx	TextField	Rich content for portal rendering
json_schema	JSONField	Field definitions for fillable forms
onboarding	BooleanField	Assigned automatically at onboarding
renewal	BooleanField	Assigned on renewal cycle
renewal_delta	IntegerField	Days until renewal due
only_manually	BooleanField	Admin-only assignment; never auto-assigned
active	BooleanField
can_resend	BooleanField	Admin can re-send for re-signature
dates_required	BooleanField	Whether active/expiration dates must be set
employee_positions	M2M → EmployeePosition	Restricts form to specific roles
client_types	M2M → ClientType	Restricts form to HCC or HHP clients

Category choices:

Key	Meaning
OB	Onboarding
EV	E-Verify
GE	General
OF	Offer / Job Acceptance
TS	Testing
MD	Medical
VI	Vehicle Insurance
DT	Drug Test
TM	Termination
PC	Provisional Contract
SP	Service Plan

---

FormSubmission

The completed data for a form assignment.

Field	Type	Notes
answers	JSONField	Submitted field values
pdf_uploaded	BooleanField	True if user uploaded a file rather than filling fields
pdf	FileField	Generated or uploaded PDF (S3)
signature	ImageField	Captured signature image
expiration_date, active_date, completed_date	DateField
manually_loaded	BooleanField	Admin bypass

---

FormRequest

Per-user assignment of a Form. One record per user-form pair.

Field	Type	Notes
form	FK → Form
user	FK → User
submission	OneToOneField → FormSubmission	Nullable until submitted
extra_data	JSONField	Additional context passed at assignment time
is_important	BooleanField
end_date	DateField	Deadline

Methods: submit(data) — creates a FormSubmission, triggers PDF generation. load_submission(file) — manual upload path.

---

SignatureFontType

A font available for typed signatures.

Field	Type	Notes
name	CharField
google_font_url	URLField
woff_renderer	FileField	Woff font file for PDF rendering
family_name	CharField	CSS font-family name

---

Signature

A saved signature belonging to a user. Can be handwritten (canvas) or typed (font-rendered).

Field	Type	Notes
user	FK → User
font_type	FK → SignatureFontType	Nullable; used for FONT type signatures
type	CharField	HANDWRITTEN / FONT
text	CharField	The typed text (for FONT type)
hand_write	ImageField	Canvas-drawn signature image
typed_render	ImageField	Font-rendered signature image
is_default	BooleanField	User's selected default signature

---

messages

Message

Direct message between two portal users within an org.

Field	Type	Notes
creator	FK → User	Sender
recipient	FK → User	Receiver
organization	FK → Organization
body	TextField

---

MessageAttachment

File attached to a Message.

Field	Type	Notes
message	FK → Message
filename	CharField
attachment	FileField	S3

---

notes

Note

Covers multiple structured record types that share the same data shape. Extends SoftDeletableModel and ExportableModel.

Field	Type	Notes
organization	FK → Organization
creator	FK → User	Admin who created the record
user	FK → User	Employee or client the note is about
type	CharField	See choices below
subject	CharField
body	TextField
file_to_export	FileField	Generated PDF
completed_date	DateField

Type choices:

Key	Meaning
NOTE	General note
DISCIPLINARY_ACTION	Disciplinary record
PERFORMANCE_EVALUATION	Performance review
PERFORMANCE_EVALUATION_90	90-day performance review
SUPERVISORY_REPORTS	Supervisory visit report
SATISFACTORY_SURVEYS	Satisfaction survey
CASE_COMUNICATION	Case communication (note: typo in codebase)
INCIDENT_REPORT	Incident report

---

NotesFile

Supporting file attached to a Note (e.g. signed PDF page).

Field	Type	Notes
note	FK → Note
answers	JSONField
file	FileField	S3

---

notifications

NotificationMessage

Template/definition for a notification type. Configured once, reused across all deliveries.

Field	Type	Notes
type	CharField	One of ~30 choices — see below
channel	CharField	EMAIL / PORTAL / ALL
receiver	CharField	ADMIN / EMPLOYEE / CLIENT / MARKETER
email_subject, portal_subject	CharField	May contain {Organization Name} etc. placeholders
email_body, html_email_body	TextField	Plain + HTML email templates
portal_body	TextField	In-portal notification text

Notable type values (partial list):

Type	When
NEW_ACCOUNT	User account created
NEW_APPLICATION	New job application submitted
APPLICATION_APPROVED	Application approved
ONBOARDING_COMPLETED	Employee onboarding complete
ANNUAL_CT	Annual competency test due
ANNUAL_TB	Annual TB test due
MESSAGE	New direct message
GRIEVANCE	New grievance submitted
WORK_SCHEDULE	Work schedule updated
SERVICE_PLAN	Service plan generated/shared
SERVICE_PLAN_REMINDER	Service plan reminder
SATISFACTION_SURVEY	Satisfaction survey available
SUPERVISORY_REPORT	Supervisory report due
MISSING_DOCUMENTATION	Incomplete document reminder
COMPETENCY_TEST_DUE	Competency test coming due
NEW_JOB_ACCEPTANCE	New job offer to accept
REFERRAL_COMPLETED	Referral converted to client
REFERRAL_STEP_EXPIRED	Referral step overdue
CLIENT_ONBOARDING_COMPLETED	Client onboarding complete
BC_COMPLETED	Background check completed

---

Notification

An individual notification delivered to a specific user.

Field	Type	Notes
user	FK → User	Recipient
message	FK → NotificationMessage	Template used
organization	FK → Organization
is_read	BooleanField	In-portal read status
is_notified	BooleanField	Whether email has been dispatched
context	JSONField	Dynamic values used to render the template (e.g. org name, link)

Methods: send() and role-specific send variants that resolve the template + context into an actual email/portal notification.

---

referrals

Tracks a prospective client from initial intake through conversion to a ClientProfile.

Referral

Field	Type	Notes
user	OneToOneField → User	Created when referral converts to a client; nullable until then
creator	FK → User	Marketer who submitted the referral
organization	FK → Organization
status	CharField	IP (In Progress) / CL (Closed) / DC (Discarded) / PD (Pending)
ssn	CharField	Encrypted
Personal fields	CharField	First/last name, birth_date, phone, email
Address fields	CharField	address, city, state, zipcode
gender, marital_status	CharField
soc	DateField	Anticipated Start of Care
insurance	JSONField	Insurance details
primary_condition	CharField
Referrer fields	CharField	Referring physician/provider contact info
Case manager fields	CharField	Case manager contact info
estimate_at	DateField	Expected admission date

Methods: discard() — marks referral as DC. to_client() — creates a User + ClientProfile from the referral data, sets status to CL.

---

Step

Definition of a referral pipeline stage (ordered).

Field	Type	Notes
name	CharField
order	IntegerField	Unique; determines pipeline sequence
time_due	IntegerField	Days allowed for this step

---

ReferralStep

An instance of a Step for a specific Referral.

Field	Type	Notes
step	FK → Step
referral	FK → Referral
status	CharField	IP (In Progress) / NA (Not Applicable) / DN (Done)
expiration_date	DateField	Calculated from Step.time_due
completed_at	DateTimeField

Method: done() — marks step complete, triggers next-step logic.

---

StepNote

A note or attachment on a specific ReferralStep.

Field	Type	Notes
referral_step	FK → ReferralStep
creator	FK → User
note	TextField
file	FileField	Optional attachment

---

MarketerMetric / GeneralMetric

Aggregated performance metrics. Updated via update_metrics().

Field	Notes
active_referrals	Current open referrals
clients	Total converted clients
days_by_referral	Average days from referral to admission

MarketerMetric is OneToOne with a Marketer user. GeneralMetric is FK to Organization.

---

services

Models for Service Plans and Service Visits — the care delivery records. Covers both Home Care and Home Health.

WorkService

The central record for both service plans (type=PLAN) and service visits (type=VISIT).

Field	Type	Notes
organization	FK → Organization
creator	FK → User	Admin who created the record
type	CharField	PLAN / VISIT
care_type	CharField	HOME (Home Care) / HEALTH (Home Health)
kind	CharField	Name/description of the plan or visit
related_service	FK → WorkService	Self-referential; links a VISIT back to its parent PLAN
signing_status	CharField	UNS (Unsigned) / SHA (Shared) / SIG (Signed)
consents	JSONField	List of consent types collected — see ClientConsents choices
file	FileField	Signed PDF
is_important	BooleanField
is_manually_created	BooleanField	Admin bypass
has_verbal_consent	BooleanField	Consent obtained verbally
start_date, end_date	DateField
client_completion_date	DateField	When client signed
manager_completion_date	DateField	When Case Manager / admin signed

ClientConsents choices: RR, COE, CB, CCI, CI, CC

---

ServiceAuthorization

Authorization details attached to a WorkService plan.

Field	Type	Notes
work_service	OneToOneField → WorkService
from_date, to_date	DateField	Authorization period
total_hours	DecimalField	Authorized hours

---

WorkServiceWeek / WorkServiceShift / ADLService

Structured schedule nested inside a service plan.

• WorkServiceWeek: One record per week of the plan (index, total_hours).
• WorkServiceShift: A named shift within a week (index, title, week_schedule JSON).
• ADLService: Links an ADLSelected task to a shift, with program_week JSON and note.

---

ADL (Activities of Daily Living)

Lookup hierarchy for ADL tasks that can be scheduled in a service plan.

Model	Fields
ADLCategory	name — top-level category (e.g. "Bathing")
ADLCategorySelected	name, adl_category FK — selected category on a plan
ADL	name, adl_category FK — individual task
ADLSelected	name, adl FK, adl_category FK — selected task on a plan

---

WorkServiceAssignment

Assigns a staff member to a WorkService (visit or plan).

Field	Type	Notes
work_service	FK → WorkService
owner	FK → User	Assigned employee
is_accepted	BooleanField	Whether the employee accepted the assignment

Unique constraint: (work_service, owner) — one assignment per employee per service record.

---

support

Public-facing intake forms. No auth required.

ContactForm

General contact submission from the public website.

Field	Notes
first_name, last_name
email, phone, state
comments
sms_opt_in	BooleanField

EligibilityForm

Initial eligibility check for prospective clients.

Field	Notes
first_name, last_name, email, phone
is_patient	YES / NO / NOT_SURE
has_medical_coverage	Coverage type choices
contact_via_phone	BooleanField

ReferralForm

Detailed intake referral from an external referrer (physician, hospital).

Field	Notes
first_name, last_name, dob, ssn	Patient identity
phone, email, address fields
primary_disability_type
has_client_been_hospitalized
has_client_medicaid, is_client_65_years	Eligibility flags
is_client_income_under, is_client_assets_under	Medicaid financial criteria
is_interpreter_needed, interpreter_language	LEP / language access
ppc_* fields	Primary Point of Contact (name, relationship, phone, email)
client_needs, client_needs_other	Care needs description

---

work_schedules

WorkSchedule

A scheduled work block for an employee. Extends SoftDeletableModel and ExportableModel.

Field	Type	Notes
organization	FK → Organization
creator	FK → User	Admin who created it
employee	FK → User	Assigned employee
client_id	—	The associated client
subject	CharField
body	TextField	Schedule details
file_to_export	FileField	Generated PDF

Method: export() — renders schedule to PDF.