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

Part of our complete guide to FHIR in healthcare data exchange.

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

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 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.

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.