Domain-Driven Design in Healthcare: Bounded Contexts, Aggregates, and FHIR Mapping

Why Healthcare Software Needs Domain-Driven Design

Healthcare is one of the most complex domains in software engineering. A single patient encounter involves clinical documentation, billing codes, scheduling, pharmacy orders, lab workflows, and insurance verification — each governed by different regulations, different terminology, and different stakeholders. When engineering teams treat healthcare as a generic CRUD application, the result is a tangled monolith where a change to the billing module breaks clinical workflows.

Domain-Driven Design (DDD), the methodology introduced by Eric Evans, provides the architectural patterns to manage this complexity. This article shows how to apply DDD concepts — bounded contexts, aggregate roots, domain events, and anti-corruption layers — specifically to healthcare software, with code examples in TypeScript and mappings to FHIR R4 resources.

Bounded Contexts: Drawing the Lines in Healthcare

A bounded context is a boundary within which a specific domain model applies. In healthcare, the critical insight is that the same real-world concept means different things in different contexts.

Consider a "Patient":

• Clinical context — A Patient is a person with medical conditions, allergies, medications, and a clinical history. The clinical team cares about diagnoses, vital signs, and treatment plans.
• Billing context — A Patient is an account holder with insurance coverage, copay obligations, and a claims history. The billing team cares about ICD-10 codes (for reimbursement, not clinical meaning), CPT codes, and payer contracts.
• Scheduling context — A Patient is someone with appointments, preferred providers, and availability constraints. The scheduling team cares about appointment types, time slots, and no-show history.
• Pharmacy context — A Patient is a medication recipient with a formulary, drug allergies, and refill schedules. The pharmacy team cares about drug interactions, dosage calculations, and prescription validity.

Trying to build a single "Patient" model that serves all these contexts leads to a bloated, fragile entity with hundreds of fields. DDD says: let each context define its own Patient model, and translate between them at the boundaries.

Defining Healthcare Bounded Contexts

Bounded Context	Core Entities	Key Operations	FHIR Resource Alignment
Clinical	Patient, Encounter, Observation, Condition, Procedure	Record vitals, document encounters, manage problem lists	Patient, Encounter, Observation, Condition
Billing/Revenue Cycle	Account, Claim, Coverage, ExplanationOfBenefit	Submit claims, verify eligibility, manage denials	Account, Claim, Coverage, ExplanationOfBenefit
Scheduling	Appointment, Schedule, Slot, Practitioner	Book appointments, manage provider calendars, handle cancellations	Appointment, Schedule, Slot
Pharmacy	MedicationRequest, MedicationDispense, MedicationAdministration	Prescribe medications, check interactions, track dispense	MedicationRequest, MedicationDispense
Laboratory	ServiceRequest, DiagnosticReport, Specimen	Order tests, report results, manage specimen tracking	ServiceRequest, DiagnosticReport, Specimen
Identity/Registration	Patient (demographics), RelatedPerson, Organization	Register patients, merge duplicates, manage relationships	Patient, RelatedPerson, Organization

Aggregate Roots: Enforcing Consistency in Clinical Data

An aggregate root is the entry point to a cluster of related entities that must remain consistent. All modifications to entities within the aggregate go through the aggregate root, which enforces business rules.

The Patient Aggregate

// Patient Aggregate Root - Clinical Context
class Patient {
  private readonly id: PatientId;
  private demographics: Demographics;
  private identifiers: MedicalRecordNumber[];
  private contacts: ContactPoint[];
  private readonly domainEvents: DomainEvent[] = [];

  // Business rule: MRN uniqueness within facility
  addIdentifier(mrn: MedicalRecordNumber): void {
    if (this.identifiers.some(i => i.system === mrn.system && i.value === mrn.value)) {
      throw new DuplicateIdentifierError(mrn);
    }
    this.identifiers.push(mrn);
    this.domainEvents.push(new PatientIdentifierAdded(this.id, mrn));
  }

  // Business rule: Always have at least one active contact
  updateContact(contact: ContactPoint): void {
    this.contacts = this.contacts.map(c =>
      c.id === contact.id ? contact : c
    );
    if (!this.contacts.some(c => c.isActive)) {
      throw new NoActiveContactError(this.id);
    }
  }

  // Business rule: Date of death must be after date of birth
  recordDeceased(dateOfDeath: Date): void {
    if (dateOfDeath <= this.demographics.birthDate) {
      throw new InvalidDateError("Death date must be after birth date");
    }
    this.demographics = this.demographics.withDeceased(dateOfDeath);
    this.domainEvents.push(new PatientDeceased(this.id, dateOfDeath));
  }
}

The Encounter Aggregate

// Encounter Aggregate Root - Clinical Context
class Encounter {
  private readonly id: EncounterId;
  private readonly patientId: PatientId; // Reference, not embedded
  private status: EncounterStatus;
  private diagnoses: Diagnosis[];
  private participants: Participant[];
  private readonly domainEvents: DomainEvent[] = [];

  // Business rule: Cannot add diagnosis to a cancelled encounter
  addDiagnosis(diagnosis: Diagnosis): void {
    if (this.status === EncounterStatus.CANCELLED) {
      throw new EncounterCancelledError(this.id);
    }
    // Business rule: Principal diagnosis must be set before secondary
    if (diagnosis.rank === DiagnosisRank.SECONDARY
        && !this.diagnoses.some(d => d.rank === DiagnosisRank.PRINCIPAL)) {
      throw new MissingPrincipalDiagnosisError(this.id);
    }
    this.diagnoses.push(diagnosis);
    this.domainEvents.push(new DiagnosisAdded(this.id, diagnosis));
  }

  // Business rule: Discharge requires at least one diagnosis
  discharge(dischargeDisposition: string): void {
    if (this.diagnoses.length === 0) {
      throw new NoDiagnosisForDischargeError(this.id);
    }
    this.status = EncounterStatus.FINISHED;
    this.domainEvents.push(
      new PatientDischarged(this.id, this.patientId, dischargeDisposition)
    );
  }
}

The Order Aggregate

// Order Aggregate Root - Clinical Context
class ClinicalOrder {
  private readonly id: OrderId;
  private readonly patientId: PatientId;
  private readonly encounterId: EncounterId;
  private orderingProvider: PractitionerId;
  private items: OrderItem[];
  private status: OrderStatus;
  private readonly domainEvents: DomainEvent[] = [];

  // Business rule: Orders require an active encounter
  static create(
    patientId: PatientId,
    encounterId: EncounterId,
    provider: PractitionerId,
    items: OrderItem[]
  ): ClinicalOrder {
    if (items.length === 0) {
      throw new EmptyOrderError();
    }
    const order = new ClinicalOrder(/* ... */);
    order.domainEvents.push(new OrderPlaced(order.id, patientId, items));
    return order;
  }

  // Business rule: Only pending orders can be cancelled
  cancel(reason: string): void {
    if (this.status !== OrderStatus.PENDING) {
      throw new OrderNotCancellableError(this.id, this.status);
    }
    this.status = OrderStatus.CANCELLED;
    this.domainEvents.push(new OrderCancelled(this.id, reason));
  }
}

Domain Events: The Nervous System of Healthcare Software

Domain events capture what happened in the system in business terms. They are the mechanism for communication between bounded contexts without creating direct dependencies.

Key Healthcare Domain Events

Event	Published By	Consumed By	Clinical Significance
PatientAdmitted	Clinical Context	Billing (create account), Pharmacy (review medications), Quality (track metrics)	Triggers all downstream admission workflows
LabResultReceived	Laboratory Context	Clinical (update chart), Alerting (check critical values), Quality (measure TAT)	Critical lab values may trigger immediate clinical action
MedicationPrescribed	Clinical Context	Pharmacy (fill prescription), Billing (charge), Safety (interaction check)	Drug interaction check must happen synchronously
PatientDischarged	Clinical Context	Billing (finalize claim), Scheduling (follow-up), Quality (readmission tracking)	Triggers 30-day readmission monitoring window
DiagnosisAdded	Clinical Context	Billing (code validation), Quality (registry reporting), Analytics	Must map ICD-10 for billing and SNOMED CT for clinical

Event Implementation

// Domain Event Base
interface DomainEvent {
  readonly eventId: string;
  readonly occurredAt: Date;
  readonly aggregateId: string;
  readonly eventType: string;
}

// Concrete Event
class PatientDischarged implements DomainEvent {
  readonly eventType = "clinical.patient.discharged";

  constructor(
    public readonly eventId: string,
    public readonly occurredAt: Date,
    public readonly aggregateId: string, // encounterId
    public readonly patientId: string,
    public readonly dischargeDisposition: string,
    public readonly diagnoses: { code: string; system: string }[],
    public readonly lengthOfStay: number
  ) {}
}

// Event Handler in Billing Context
class CreateClaimOnDischarge {
  async handle(event: PatientDischarged): Promise<void> {
    // Translate clinical diagnoses to billing codes
    const billingDiagnoses = await this.codingService.mapToBillingCodes(
      event.diagnoses
    );

    // Create claim in billing context with its own model
    const claim = Claim.create({
      patientAccountId: await this.accountLookup.findByPatientId(event.patientId),
      encounterId: event.aggregateId,
      diagnoses: billingDiagnoses,
      serviceDate: event.occurredAt,
    });

    await this.claimRepository.save(claim);
  }
}

Mapping DDD to FHIR: A Natural Fit

FHIR was designed with many of the same principles as DDD. FHIR resources are essentially aggregate roots with clear boundaries and reference-based relationships.

DDD Concept	FHIR Equivalent	Example
Bounded Context	FHIR Module (Clinical, Financial, etc.)	Clinical module contains Patient, Encounter, Observation
Aggregate Root	FHIR Resource	Patient resource is the aggregate root for demographics
Entity	FHIR BackboneElement or contained resource	Encounter.diagnosis is an entity within the Encounter aggregate
Value Object	FHIR DataType (CodeableConcept, Period, etc.)	CodeableConcept for diagnosis codes is immutable
Domain Event	FHIR MessageHeader + Bundle	ADT message as a FHIR Bundle with MessageHeader
Reference by ID	FHIR Reference	Encounter.subject references Patient by ID, not embedding
Repository	FHIR REST API + search	GET /Patient?identifier=MRN123 is a repository query

Anti-Corruption Layer: Integrating with Legacy HL7v2

Most healthcare organizations run legacy systems that communicate via HL7v2 messages. The anti-corruption layer (ACL) is a DDD pattern that translates between the legacy model and your clean domain model, preventing legacy data structures from leaking into your modern codebase.

ACL Implementation for HL7v2 ADT Messages

// Anti-Corruption Layer: HL7v2 ADT -> Clinical Domain Model
class HL7v2AntiCorruptionLayer {
  constructor(
    private readonly patientRepository: PatientRepository,
    private readonly encounterRepository: EncounterRepository,
    private readonly eventBus: DomainEventBus
  ) {}

  async handleADT_A01(message: HL7v2Message): Promise<void> {
    // Step 1: Extract and translate patient demographics
    const pid = message.getSegment("PID");
    const patientData = this.translatePatient(pid);

    // Step 2: Find or create patient in our domain
    let patient = await this.patientRepository.findByMRN(patientData.mrn);
    if (!patient) {
      patient = Patient.register(patientData);
    } else {
      patient.updateDemographics(patientData.demographics);
    }
    await this.patientRepository.save(patient);

    // Step 3: Create encounter from PV1 segment
    const pv1 = message.getSegment("PV1");
    const encounterData = this.translateEncounter(pv1);
    const encounter = Encounter.create({
      patientId: patient.id,
      ...encounterData
    });
    await this.encounterRepository.save(encounter);

    // Step 4: Publish domain events (clean, not HL7v2-shaped)
    for (const event of [...patient.domainEvents, ...encounter.domainEvents]) {
      await this.eventBus.publish(event);
    }
  }

  private translatePatient(pid: HL7v2Segment): PatientData {
    return {
      mrn: new MedicalRecordNumber(
        pid.getField(3, 1),  // PID.3.1 - ID
        pid.getField(3, 4)   // PID.3.4 - Assigning authority
      ),
      demographics: new Demographics({
        familyName: pid.getField(5, 1),
        givenName: pid.getField(5, 2),
        birthDate: this.parseHL7Date(pid.getField(7)),
        gender: this.mapGender(pid.getField(8)),
      })
    };
  }
}

Testing Domain Models in Healthcare

DDD models are inherently testable because business rules are encapsulated in the domain objects, not spread across controllers and services.

describe("Encounter Aggregate", () => {
  it("should not allow discharge without a diagnosis", () => {
    const encounter = Encounter.create({
      patientId: "patient-123",
      type: EncounterType.INPATIENT,
      provider: "practitioner-456"
    });

    expect(() => encounter.discharge("home")).toThrow(
      NoDiagnosisForDischargeError
    );
  });

  it("should require principal diagnosis before secondary", () => {
    const encounter = Encounter.create({ /* ... */ });
    const secondary = new Diagnosis("J18.9", DiagnosisRank.SECONDARY);

    expect(() => encounter.addDiagnosis(secondary)).toThrow(
      MissingPrincipalDiagnosisError
    );
  });

  it("should emit PatientDischarged event on successful discharge", () => {
    const encounter = Encounter.create({ /* ... */ });
    encounter.addDiagnosis(new Diagnosis("J18.9", DiagnosisRank.PRINCIPAL));
    encounter.discharge("home");

    const events = encounter.domainEvents;
    expect(events).toHaveLength(2); // DiagnosisAdded + PatientDischarged
    expect(events[1]).toBeInstanceOf(PatientDischarged);
  });
});

Apply DDD to Your Healthcare Platform with Nirmitee

At Nirmitee, we apply domain-driven design principles to every healthcare platform we build. Our architects work with clinical SMEs to define bounded contexts, identify aggregate roots, and design event-driven workflows that scale with organizational complexity. From agile product engineering to EHR integration, DDD is how we manage the inherent complexity of healthcare software.

Contact our team to discuss applying DDD to your healthcare platform.

Need expert help with healthcare data integration? Explore our Healthcare Interoperability Solutions to see how we connect systems seamlessly. We also offer specialized Healthcare Software Product Development services. Talk to our team to get started.