backend-development-guide.md

Backend Development Guide: End-to-End Feature Implementation

This guide demonstrates how to build a new feature end-to-end in CARE's backend, using the Patient model as a concrete example. Follow this guide to understand how to create new models and APIs that integrate seamlessly with CARE's architecture.

Quick Overview of the Tech Stack

Our backend uses:

• Django & Django REST Framework: For models, APIs, and business logic
• Pydantic: For API contract definitions and validation
• PostgreSQL: As the primary database

Key directories:

• Models: care/emr/models/ - Extend EMRBaseModel for audit fields and common behavior
• Resources (Pydantic): care/emr/resources/<feature>/spec.py - Define create/update/read contracts
• API ViewSets: care/emr/api/viewsets/ - Compose mixins from EMRBaseViewSet
• Routing: config/api_router.py - Use nested routers for facility/patient-scoped endpoints

Step 1: Model Development

Let's look at the Patient model as an example of best practices. The model is defined in care/emr/models/patient.py and extends EMRBaseModel.

Key Model Patterns

1. Field Definitions:

class Patient(EMRBaseModel):
    name = models.CharField(max_length=200, default="")
    gender = models.CharField(max_length=35, default="")
    phone_number = models.CharField(
        max_length=14,
        validators=[mobile_or_landline_number_validator],
        default=""
    )
    date_of_birth = models.DateField(default=None, null=True)
    year_of_birth = models.IntegerField(
        validators=[MinValueValidator(1900)],
        null=True
    )

2. Best Practices:

   • Extend EMRBaseModel to get audit fields (created/modified dates, external_id)
   • Use appropriate field types and validators
   • Keep normalized fields and caches separate
   • Document complex fields or business logic
   • Use descriptive field names

3. Model Methods:

   • Keep save() methods minimal and safe
   • Encapsulate complex logic in helper methods
   • Use properties for derived fields
   • Handle caches and signals appropriately

Step 2: Pydantic Resources

Resources define the API contracts and handle model mapping. They live in care/emr/resources/<feature>/spec.py.

Resource Types

1. Base Spec:

class PatientBaseSpec(EMRResource):
    name: str
    gender: str
    phone_number: str
    date_of_birth: datetime.date | None = None
    year_of_birth: int | None = None

2. Create Spec:

class PatientCreateSpec(PatientBaseSpec):
    geo_organization: UUID4
    identifiers: list[PatientIdentifierConfigRequest] = []
    tags: list[UUID4] = []

    @model_validator(mode="after")
    def validate_identifiers(self):
        # Validation logic here
        return self

    def perform_extra_deserialization(self, is_update, obj):
        # Map Pydantic fields to Django model
        obj.geo_organization = Organization.objects.get(
            external_id=self.geo_organization
        )

3. Update/List/Retrieve Specs:

• Create separate specs for different operations
• Handle partial updates in UpdateSpec
• Add computed fields in ListSpec/RetrieveSpec

Best Practices:

• Use validators for complex validation logic
• Handle related objects in perform_extra_deserialization
• Keep serialization logic in perform_extra_serialization
• Document any non-obvious mappings

Step 3: ViewSet Implementation

ViewSets compose EMR mixins and handle authorization. They live in care/emr/api/viewsets/.

Basic ViewSet Setup:

class PatientViewSet(EMRModelViewSet):
    database_model = Patient
    pydantic_model = PatientCreateSpec
    pydantic_read_model = PatientListSpec
    pydantic_update_model = PatientUpdateSpec
    pydantic_retrieve_model = PatientRetrieveSpec
    filterset_class = PatientFilters
    ordering_fields = ["created_date", "modified_date"]

Key Components:

1. Authorization:

def authorize_update(self, request_obj, model_instance):
    if not AuthorizationController.call(
        "can_write_patient_obj",
        self.request.user,
        model_instance
    ):
        raise PermissionDenied("Cannot Update Patient")

2. Create/Update Operations:

def perform_create(self, instance):
    with transaction.atomic():
        super().perform_create(instance)
        # Additional setup like tags, identifiers
        instance.save()

Best Practices:

• Use transactions for multi-step operations
• Keep business logic in model methods
• Implement proper authorization checks
• Add appropriate filters and ordering
• Optimize querysets with select_related/prefetch_related

Step 4: API Routing

Register your ViewSet in config/api_router.py:

# For top-level resources
router.register("patient", PatientViewSet, basename="patient")

# For nested resources under patient
patient_nested_router = NestedSimpleRouter(
    router, r"patient", lookup="patient"
)
patient_nested_router.register(
    r"consultation",
    ConsultationViewSet,
    basename="patient-consultation"
)

Choose the appropriate router based on your resource's scope:

• Root router: For top-level resources
• facility_nested_router: For facility-scoped resources
• patient_nested_router: For patient-scoped resources

Step 5: Testing

Create comprehensive tests covering all operations:

@pytest.mark.django_db
class TestPatientAPI:
    def test_create_patient(self, user_factory):
        client = APIClient()
        user = user_factory()
        client.force_authenticate(user)

        url = reverse("api:patient-list")
        payload = {
            "name": "John Doe",
            "gender": "male",
            "phone_number": "+910000000000",
            "geo_organization": "<org-external-id>",
        }

        res = client.post(url, payload, format="json")
        assert res.status_code == 200
        assert res.data["name"] == "John Doe"

    def test_update_patient(self, patient_factory):
        # Test update operations
        pass

    def test_list_filters(self):
        # Test list filters and ordering
        pass

Test Coverage:

• Basic CRUD operations
• Validation error cases
• Authorization rules
• Custom actions/endpoints
• Edge cases and business rules

Development Checklist

When creating a new feature:

• Create model and migrations

  • Extend EMRBaseModel
  • Add appropriate fields and validators
  • Document complex logic

• Create Pydantic resources

  • Base spec with common fields
  • Create/Update/List/Retrieve specs
  • Add validation rules
  • Implement serialization methods

• Implement ViewSet

  • Set up basic configuration
  • Add authorization rules
  • Implement custom actions
  • Add filters and ordering

• Update routing

  • Register with appropriate router
  • Add nested routes if needed

• Write tests

  • CRUD operations
  • Validation cases
  • Authorization rules
  • Custom functionality

• Documentation

  • API endpoints
  • Request/response formats
  • Authorization requirements
  • Example usage

Common Gotchas

1. Authorization:

   • Always implement proper authorization checks
   • Consider both object and action-level permissions
   • Test with different user roles

2. Transactions:

   • Use atomic transactions for multi-step operations
   • Handle rollbacks appropriately
   • Consider using select_for_update when needed

3. Performance:

   • Optimize database queries
   • Use select_related/prefetch_related
   • Add appropriate indexes
   • Cache expensive computations

4. Validation:

   • Add comprehensive validation rules
   • Handle edge cases
   • Provide clear error messages
   • Validate at both model and API levels