Installation & Setup

This guide walks through integrating the Obelawium Dental module (obelaw/ium-dental) into an existing Laravel application with the core Obelawium framework.

Requirements

Before installing the package, verify that your environment satisfies the following minimum prerequisites:

• PHP: ^8.2 or later
• Laravel Framework: ^11.0 or ^12.0
• Obelawium Core: obelaw/ium: *
• Database: PostgreSQL 14+, MySQL 8.0+, or SQLite 3.35+
• PHP Extensions: ext-pdo, ext-json, ext-openssl, ext-bcmath

Installation via Composer

Install the dental domain package into your Laravel application using Composer:

composer require obelaw/ium-dental

Service Provider Registration

If your Laravel application uses package auto-discovery, ObelawDentalServiceProvider is automatically registered. If discovery is disabled, register the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php:

// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    Obelaw\Ium\Dental\Providers\ObelawDentalServiceProvider::class,
];

The service provider automatically registers the dental domain key with the central ium() gateway:

Ium::registerDomain('dental', DentalDomain::class);

Publishing Configuration & Migrations

To customize default settings or publish database migration files into your application’s database/migrations directory, execute the vendor:publish Artisan command:

# Publish configuration file to config/ium/dental.php
php artisan vendor:publish --tag=ium-dental-config

# Publish migrations to database/migrations
php artisan vendor:publish --tag=ium-dental-migrations

Running Database Migrations

Run the database migrations to provision the dental schema:

php artisan migrate

Table Prefix Convention

In accordance with Obelawium’s persistence architecture, all dental tables are automatically namespaced with the ium_dental_ prefix:

• ium_dental_patients — Patient master records with encrypted PHI
• ium_dental_medical_alerts — Systemic health risks, allergies, and prophylactic needs
• ium_dental_emergency_contacts — Patient emergency contact directories
• ium_dental_consent_records — Digital signature tokens and legal authorizations
• ium_dental_odontogram_charts — Clinical charts and notation system configuration
• ium_dental_odontogram_teeth — 5-surface anatomical findings per tooth
• ium_dental_periodontal_exams — Comprehensive periodontal examination headers
• ium_dental_periodontal_points — 6-point probing matrix, recession, CAL, BOP
• ium_dental_treatment_plans — Phased treatment plans
• ium_dental_treatment_plan_phases — Sequenced phases (Urgent to Maintenance)
• ium_dental_planned_procedures — Scheduled and executed ADA/CDT procedures
• ium_dental_operatories — Dental chairs and clinical room configurations
• ium_dental_appointments — Patient appointments with multi-resource bindings
• ium_dental_resource_blocks — Blocked slots and maintenance reservations
• ium_dental_autoclave_cycles — Sterilization cycles, cassette barcodes, indicators
• ium_dental_dicom_studies — Radiograph study metadata and PACS links
• ium_dental_dental_invoices — Itemized procedure invoices and insurance splits
• ium_dental_invoice_line_items — Individual CDT code charges and fees
• ium_dental_ledger_payments — Posted patient and insurance remittance payments
• ium_dental_cdt_codes — ADA/CDT standard code catalog
• ium_dental_lab_orders — Dental laboratory prosthetic work orders and STL scans
• ium_dental_quickbooks_sync_jobs — Idempotent 2-way QuickBooks sync jobs
• ium_dental_audit_logs — Tamper-evident SHA-256 hash-chained audit trails

Environment & Configuration Options

Configuration settings reside in config/ium/dental.php and can be overridden via environment variables:

return [
    /*
    |--------------------------------------------------------------------------
    | Deployment Mode
    |--------------------------------------------------------------------------
    | 'saas' : Multi-tenant scoping, shared database, cloud backups.
    | 'on_prem' : Single-tenant, local PACS bridge, air-gapped storage.
    */
    'storage' => [
        'mode' => env('IUM_DENTAL_STORAGE_MODE', 'saas'),
        'disk' => env('IUM_DENTAL_STORAGE_DISK', 'local'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Tenant Scoping (SaaS Mode)
    |--------------------------------------------------------------------------
    */
    'tenant' => [
        'enabled' => env('IUM_DENTAL_TENANT_ENABLED', true),
        'source' => env('IUM_DENTAL_TENANT_SOURCE', 'request'), // request|config|env
        'id' => env('IUM_DENTAL_TENANT_ID', null),
    ],

    /*
    |--------------------------------------------------------------------------
    | Default Odontogram Notation System
    |--------------------------------------------------------------------------
    | Supported: 'universal', 'fdi', 'palmer'
    */
    'odontogram' => [
        'default_notation' => env('IUM_DENTAL_DEFAULT_NOTATION', 'universal'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Aerosol / Room Turnover Buffer
    |--------------------------------------------------------------------------
    | Turnover minutes added after aerosol-generating dental procedures.
    */
    'scheduling' => [
        'aerosol_buffer_minutes' => (int) env('IUM_DENTAL_AEROSOL_BUFFER_MINUTES', 15),
    ],

    /*
    |--------------------------------------------------------------------------
    | DICOM / PACS Bridge
    |--------------------------------------------------------------------------
    */
    'imaging' => [
        'adapter' => env('IUM_DENTAL_IMAGING_ADAPTER', 'local'),
        'local_incoming_path' => env('IUM_DENTAL_IMAGING_INCOMING_PATH', storage_path('dicom/incoming')),
        'pacs_query_retrieve_ae' => env('IUM_DENTAL_PACS_QR_AE', null),
        'pacs_query_retrieve_host' => env('IUM_DENTAL_PACS_QR_HOST', null),
        'pacs_query_retrieve_port' => (int) env('IUM_DENTAL_PACS_QR_PORT', 11112),
        'cloud_bucket' => env('IUM_DENTAL_IMAGING_CLOUD_BUCKET', null),
        'deidentify_by_default' => (bool) env('IUM_DENTAL_IMAGING_DEIDENTIFY_BY_DEFAULT', true),
    ],

    /*
    |--------------------------------------------------------------------------
    | QuickBooks Integration
    |--------------------------------------------------------------------------
    */
    'quickbooks' => [
        'enabled' => (bool) env('IUM_DENTAL_QUICKBOOKS_ENABLED', false),
        'environment' => env('IUM_DENTAL_QUICKBOOKS_ENV', 'sandbox'), // sandbox|production
        'client_id' => env('IUM_DENTAL_QUICKBOOKS_CLIENT_ID', null),
        'client_secret' => env('IUM_DENTAL_QUICKBOOKS_CLIENT_SECRET', null),
        'redirect_uri' => env('IUM_DENTAL_QUICKBOOKS_REDIRECT_URI', null),
        'realm_id' => env('IUM_DENTAL_QUICKBOOKS_REALM_ID', null),
    ],

    /*
    |--------------------------------------------------------------------------
    | HIPAA & GDPR Compliance
    |--------------------------------------------------------------------------
    */
    'compliance' => [
        'encrypt_phi' => (bool) env('IUM_DENTAL_ENCRYPT_PHI', true),
        'audit_enabled' => (bool) env('IUM_DENTAL_AUDIT_ENABLED', true),
        'retention_years' => (int) env('IUM_DENTAL_RETENTION_YEARS', 7),
        'baa_recorded' => (bool) env('IUM_DENTAL_BAA_RECORDED', false),
    ],
];

Deployment Modes

1. Cloud SaaS Mode (saas)

• Multi-tenant tenant isolation applied automatically to all patient, clinical, and financial aggregates.
• PHI encrypted at rest using Laravel application encryption keys (APP_KEY).
• DICOM studies stored in S3/compatible object storage with patient de-identification applied unless cloud sync consent is granted.

2. On-Premise Connect Mode (on_prem)

• Single-tenant execution designed for private dental practices, surgical suites, and institutional hospital networks.
• Air-gapped storage: files reside on local clinic storage arrays (/var/local/pacs/dicom/incoming).
• Direct integration with local DICOM Query/Retrieve PACS servers via standard TCP port 11112.

Verifying the Installation

To verify that the module is correctly discovered and bound to the Obelawium gateway, execute the following Pest PHP test or run it through tinker:

use Obelaw\Ium\Facades\Ium;
use Obelaw\Ium\Dental\DentalDomain;

// Verify domain registration
expect(ium()->hasDomain('dental'))->toBeTrue();

// Verify fluent domain gateway returns instance
expect(ium()->dental())->toBeInstanceOf(DentalDomain::class);

// Verify services resolve as singletons
expect(ium()->dental()->patients())->toBe(ium()->dental()->patients());

Run package unit and feature tests:

vendor/bin/pest