Obelawium Dental Domain Module

The Obelawium Dental module (obelaw/ium-dental) is a headless, decoupled dental practice management and clinical governance engine built for the Obelawium (IUM) ecosystem. Designed on Domain-Driven Design (DDD) principles, it provides enterprise-grade aggregates, type-safe value objects, domain services, and automated compliance workflows for modern dental clinics, multi-location dental support organizations (DSOs), and hospital dental departments.

Core Philosophy: Headless & Decoupled

In accordance with Obelawium’s core architectural tenets, ium-dental is 100% headless:

• Zero UI / Presentation Bias: Contains no Blade templates, JavaScript widgets, controllers, or HTTP routing logic.
• Pure Domain Orchestration: All dental business rules, clinical state machines, and financial invariants reside entirely inside domain services and aggregates.
• Universal Consumption: The domain can be consumed from any presentation layer, including Laravel Blade, Filament admin panels, mobile apps, chairside iPad apps, background daemon workers, or REST/GraphQL APIs.
• Fluent Gateway Access: Every operation is invoked through Obelawium’s centralized fluent domain gateway:

ium()->dental()->[service]()->[method]()

High-Level Architecture & Bounded Contexts

Obelawium Dental is organized into six tightly bounded contexts, accessible through twelve specialized domain services:

graph TD
    IUM["ium()->dental() Fluent Gateway"]
    
    subgraph Clinical["Clinical Bounded Context"]
        PAT["patients()<br/>Patient & EMR"]
        ODO["odontograms()<br/>Odontogram & Perio"]
        PLN["treatmentPlans()<br/>Phased Treatment"]
        PRC["procedures()<br/>CDT Procedures"]
        IMG["imaging()<br/>DICOM & PACS"]
    end

    subgraph Operations["Practice Operations Bounded Context"]
        APT["appointments()<br/>Appointments"]
        SCH["scheduling()<br/>Operatory Logistics"]
        INF["infectionControl()<br/>Autoclave Sterilization"]
        LAB["labOrders()<br/>Dental Lab Tracking"]
    end

    subgraph Finance["Financial & Compliance Context"]
        LDG["ledgers()<br/>Dual-Payer Billing"]
        QBO["quickBooks()<br/>2-Way Invoicing Sync"]
        AUD["audit()<br/>SHA-256 Hash Chain"]
    end

    IUM --> Clinical
    IUM --> Operations
    IUM --> Finance

Domain Services Matrix

The DentalDomain gateway exposes twelve singleton services:

Key Clinical & Enterprise Invariants

1. Morphological Surface Invariant: Anterior teeth (incisors and canines) do not possess occlusal surfaces; attempting to record an occlusal finding on teeth 6–11, 22–27 (Universal) triggers an immediate InvalidToothMorphologyException. Conversely, incisal edges are blocked on posterior teeth (premolars and molars).

2. Aerosol Disinfection Turnover Buffer: Procedures flagged as aerosol-generating (e.g., high-speed cavity preparations, ultrasonic scaling) automatically append a 10–15 minute turnover buffer to the operatory schedule before the chair can be booked for the next patient.

3. Chairside Autoclave Sterility Gate: Before an invasive procedure or appointment is started, the dental assistant scans the autoclave cassette barcode (AutoclaveBarcode). If the sterilization cycle failed, biological spore indicators were unverified, or the 30-day sterility window expired, an AutoclaveSterilizationFailedException blocks chairside commencement.

4. Zero-PHI QuickBooks Invoicing: QuickBooks Online and Desktop synchronization transmits only itemized ADA/CDT procedure codes, quantities, financial totals, and opaque ledger references. Patient names, dates of birth, medical history, and clinical notes are strictly blocked from leaving the HIPAA/GDPR security perimeter.

5. Mandatory Informed Consent Gating: Invasive treatment plans require a chairside tablet signature (SignConsentDto) before phase activation. Accounting sync and external DICOM cloud sharing are gated by active ConsentType::BILLING and ConsentType::IMAGING_CLOUD_SYNC consents.

6. Tamper-Evident SHA-256 Audit Trail: Every state mutation logs an audit entry cryptographically linked to the previous entry: current_hash = SHA-256(previous_hash + actor + action + resource + timestamp). Any unauthorized alteration of audit records breaks the chain verification.

Fluent Invocation Example

use Obelaw\Ium\Dental\Data\CreatePatientDto;
use Obelaw\Ium\Dental\Data\BookAppointmentDto;
use Obelaw\Ium\Dental\Data\CalculateCopayDto;
use Obelaw\Ium\Dental\ValueObjects\ToothNumber;
use Obelaw\Ium\Dental\ValueObjects\SurfaceSet;
use Obelaw\Ium\Dental\Enums\ToothSurface;
use Obelaw\Ium\Dental\Enums\ToothCondition;

// 1. Create patient record with encrypted PHI
$patient = ium()->dental()->patients()->create(CreatePatientDto::from([
    'medical_record_number' => 'MRN-2026-9041',
    'first_name' => 'Alexander',
    'last_name' => 'Wright',
    'ssn' => '987-65-4321',
    'phone' => '+1-555-0182',
    'email' => 'alex.wright@example.com',
]));

// 2. Chart tooth surface condition
$chart = ium()->dental()->odontograms()->createChart($patient->id);
$tooth = ToothNumber::fromUniversal(14); // Upper Left First Molar
$surfaces = SurfaceSet::from([ToothSurface::MESIAL->value, ToothSurface::OCCLUSAL->value]);
ium()->dental()->odontograms()->markSurface($chart->id, $tooth, $surfaces, ToothCondition::CARIES);

// 3. Coordinate dual-payer insurance benefits
$copay = ium()->dental()->ledgers()->calculateDualPayerCopay(CalculateCopayDto::from([
    'total_fee_minor' => 125000, // $1,250.00
    'primary_coverage_percent' => 0.80, // 80%
    'primary_deductible_minor' => 5000,  // $50.00
    'secondary_coverage_percent' => 0.50, // 50%
]));

// Results: $960.00 primary paid, $120.00 secondary paid, $170.00 patient copay

Next Steps

• Proceed to Installation & Setup to configure Composer dependencies, migrations, and storage modes.
• Explore Patient Management & EMR for PHI encryption and consent gating.
• Review Odontogram & Periodontics for anatomical charting rules.