Getting Started with Domains

Adopting Domain-Driven Design (DDD) transforms monolithic applications from tangled webs of controllers and database models into modular, business-aligned enterprise platforms.

In the Obelaw architecture, business capabilities are partitioned into self-contained Bounded Contexts. This guide introduces the architectural principles, directory topology, and operational boundaries necessary to construct and integrate custom domain modules.

---

1. The Anatomy of a Bounded Context

Every business domain in Obelaw is an isolated bounded context. Domains do not expose their internal persistence mechanics (such as raw Eloquent models or internal table schemas) to outside systems. Instead, they expose explicit business actions, read queries, and type-safe Data Transfer Objects (DTOs).

flowchart TB
    subgraph ContextBoundary["Bounded Context Boundary"]
        Gateway["Domain Manager / Gateway<br/>Unified Fluent Context Entry Point"]
        
        subgraph Operations["Tactical Operations"]
            Actions["Actions<br/>Single-Purpose Write Mutations"]
            Queries["Queries<br/>Fluent Read Pipelines"]
        end

        subgraph Modeling["Domain Heart"]
            Invariants["Domain Invariants<br/>The Law & Business Rules"]
            Aggregates["Aggregate Roots & Entities<br/>Pure Business Models"]
            Events["Domain Events<br/>State Change Broadcasts"]
        end

        subgraph Persistence["Persistence Boundary"]
            Storage["Storage Models<br/>Persistence Only"]
        end
    end

    External["External Delivery Layers<br/>Web · API · CLI · Queue"] -->|"Validated DTOs"| Gateway
    Gateway --> Actions
    Gateway --> Queries
    Actions --> Invariants
    Actions --> Aggregates
    Actions -->|"State Changes"| Events
    Aggregates -.-> Storage

---

2. The Three Architectural Layers

To eliminate architectural drift, Obelaw enforces a strict three-layer boundary:

Layer	Responsibility	What Belongs Here	What is Forbidden
1. Presentation & Delivery	Translates protocol requests into domain calls; renders UI responses.	HTTP Controllers, Filament Resources, Livewire Components, Console Commands, Webhooks.	Business invariants, transaction rollbacks, raw database mutations.
2. Domain Layer	Governs business invariants, operational lifecycles, and transactions.	Actions, Queries, Domain Invariants, Value Objects, Domain Events, DTOs, Context Gateways.	HTTP sessions, request headers, framework rendering, UI components.
3. Infrastructure & Persistence	Manages data storage, external network calls, and driver adapters.	Table schemas, persistence models, cache drivers, search index drivers, third-party adapters.	Business rule decisions, validation workflows, domain event emissions.

---

3. Directory Layout Standard

Each domain module adheres to a standardized structural hierarchy that segregates concerns:

src/
├── Actions/        # Single-purpose write operations (one command, one transaction)
├── Data/           # Immutable, type-safe Data Transfer Objects (DTOs)
├── Events/         # Domain events emitted upon validated state transitions
├── Exceptions/     # Strongly-typed domain invariant violation exceptions
├── Managers/       # Context gateway entry points and service orchestrators
├── Models/         # Persistence-only data representations (no business rules)
├── Providers/      # Context service registration and dependency bindings
├── Queries/        # Read-only query builders and search criteria pipelines
└── Traits/         # Reusable behaviors and cross-cutting model traits

Directory Roles & Boundaries

• Actions/: Implements atomic business mutations. Each action executes a single unit of work (e.g., RegisterPayment, PostJournalVoucher, AllocateStock). Actions accept validated DTOs, assert domain invariants, mutate domain state, and broadcast domain events.
• Data/: Enforces type-safety at the context boundary. DTOs encapsulate payloads entering or exiting the domain, preventing loose arrays or untyped primitives from crossing context walls.
• Queries/: Dedicated read pipelines that optimize data retrieval for reports, grids, and dashboards without triggering domain mutations or event listeners.
• Managers/: Provide a clean, unified fluent API for cross-domain orchestration without exposing internal class dependencies.

---

4. Inter-Domain Integration Principles

Domains in an enterprise ecosystem must collaborate without establishing tight structural coupling. Obelaw implements three core integration mechanisms:

flowchart LR
    D1["Domain A<br/>e.g. Sales OMS"] -->|"1. Domain Event"| Bus["Asynchronous<br/>Domain Event Bus"]
    Bus -->|"2. Dispatched"| ACL["Anti-Corruption Layer<br/>(ACL Translator)"]
    ACL -->|"3. Inbound Action"| D2["Domain B<br/>e.g. Accounting FMS"]

1. Asynchronous Event Choreography: When an aggregate state changes (e.g., OrderPlaced, InvoiceIssued, ShipmentDispatched), the domain publishes an immutable domain event. Downstream contexts subscribe to these events independently.
2. Anti-Corruption Layer (ACL): When a downstream context receives an external event, an ACL translates external data representations into canonical local DTOs, ensuring that external schema changes do not contaminate internal models.
3. Gateway Managers: For synchronous queries (such as checking available-to-promise inventory during cart checkout), communication occurs through explicit interface contracts registered in a central domain gateway.

---

5. Domain Suite Catalog

Obelaw provides a comprehensive suite of domain blueprints covering end-to-end enterprise operations:

• Product Information Management (PIM): Canonical merchandise hub, dynamic attribute schemas, variant option matrices, and engineering BOM recipes.
• Customer Relationship Management (CRM): Lead scoring, pipeline forecasting, contact directory, and customer support SLA tracking.
• Financial Accounting & Ledger (FMS): Double-entry bookkeeping, chart of accounts, balanced journal vouchers, and period closure.
• Inventory & Warehouse Logistics (WMS): Multi-warehouse spatial topology, stock reservations, cycle counts, and quarantine lifecycles.
• Procurement & Purchasing: Vendor management, RFQ-to-PO lifecycles, 3-way matching, and landed cost allocations.
• Sales & Order Management (OMS): Omnichannel order orchestration, reservation pipelines, split dispatches, and return management.
• Manufacturing / MRP (In-House): Work center routing, machine capacity planning, bill of materials consumption, and shop floor work orders.
• Manufacturing / MRP (Subcontracting): Outwork processing, raw material consignments, contractor yield tracking, and service cost reconciliation.
• Point of Sale (POS): Offline-resilient register checkout, till float management, barcode scanning buffers, and shift reconciliation.

---

6. Next Steps

• Explore the Domain Architecture specification for deep tactical design patterns.
• Read through specific domain blueprints starting with PIM Introduction or Accounting Introduction.