Patient App Architecture

Domain Responsibility

What This App Owns

• Patient registration and demographics (UserDetails)
• Home collection scheduling (HomeCollection)
• Patient insurance management (PatientInsurance)
• Patient portal access (via proxies)
• ID proof management (UserIdProofDetails)
• Appointment scheduling (Appointment)

What It Depends On

• core/ - BaseModel, utilities
• admin/ - Labs, lab users, settings
• finance/ - Billing integration
• report/ - Lab report access
• communication/ - Notifications

What Should NOT Be Added Here

• Lab report generation logic (belongs in report/)
• Billing/payment logic (belongs in finance/)
• Lab operations (belongs in operation/)

Model-Centric Design (Fat Models)

Key Models

Business Logic in Models

UserDetails (patient/models/user_details.py) - 3342 lines

Lifecycle Methods:

Validation Methods:

Business Operations:

Side Effect Methods:

Why Fat Model Style Here

UserDetails is the central patient entity. All patient operations flow through it:

1. Validation ensures data quality
2. before_save() generates IDs, formats data
3. after_save() handles external sync

Logic is NOT in views because:

• Same logic needed from API, mobile, and integrations
• Consistent validation across all entry points
• Side effects are traceable in one place

Invariants & Data Rules

Patient Constraints

State Transitions

Data Access Patterns

QuerySet Locations

Optimization Patterns

# patient/managers/patient_overview_manager.py
def get_patient_overview(self, patient_id, lab_id):
    return UserDetails.objects.filter(
        id=patient_id, labId_id=lab_id
    ).select_related(
        "user", "labId", "orgId"
    ).prefetch_related(
        "billing_set", "labreportrelation_set"
    )

N+1 Risk Zones

API Layer (Wiring)

Endpoint Map

Thin View Pattern

# patient/views/registration.py
class RegistrationView(View):
    def post(self, request, *args, **kwargs):
        # 1. Extract session/context
        lab_id = self.get_lab_id_from_session(request.session)
        payload = request.data
        
        # 2. Prepare data (minimal)
        payload = self.prepare_mandatory_patient_data(payload)
        
        # 3. Delegate to model
        user_details = UserDetails.register_patient(
            payload=payload,
            is_collection_center=is_collection_center,
            session=request.session,
        )
        
        # 4. Return response
        return JsonResponse({"patient": model_to_dict(user_details)})

Permission Checks

Integrations

External Systems

Webhook Trigger Points

# patient/models/user_details.py
def trigger_patient_webhooks(self, hl7_payload, **kwargs):
    """Fire webhooks for patient events"""
    # Integration webhooks
    WebhookIntegrationManager.trigger_webhook(...)

Side Effects & Hidden Coupling

after_save() Side Effects

Cross-App Coupling

[!WARNING] UserDetails imports from 20+ modules across 8 apps. This is a coupling hotspot.

Performance & Scaling Notes

Hot Tables

Query Optimization

# Common query pattern
UserDetails.objects.filter(
    labId_id=lab_id,
    contact=contact
).select_related("user", "labId")

Caching

• Patient instances cached in Redis if allow_individual_instance_caching = True
• Lab settings cached for feature flags

Safe Extension Guide

Adding New Patient Attribute

1. Add field to UserDetails model
2. Add migration
3. Add validation in validate() if needed
4. Add to ES sync in update_es_record() if searchable

Adding New Patient Workflow

1. Add method to UserDetails:

   @classmethod
   def new_workflow(cls, payload, session):
       instance = cls.objects.get(pk=payload["patient_id"])
       instance.set_values(payload)
       instance.save(session=session)
       return instance

2. Create thin view:

   class NewWorkflowView(GenericView):
       @transaction.atomic
       def post(self, request, *args, **kwargs):
           result = UserDetails.new_workflow(request.data, request.session)
           return JsonResponse({"status": "success"})

Patterns to Follow

• All business logic in UserDetails methods
• Use @transaction.atomic in views
• Validate permissions in validate_* methods

Patterns to Avoid

• Business logic in views
• Direct ES calls from views
• Skipping model validation with update() for critical fields

File Map