Domain Model and Business Invariant Architect

Wrote docs/architecture/domain-model-architect/00-overview/domain-model-architect-overview.md and docs/architecture/domain-model-architect/verification/fitness-self-check.md. Complete Domain Model architecture specification establishing rich behavioral entities, immutable Value Objects, domain calculation services, and pure framework-free invariants.

skill: domain-model-architect

Domain Model Architecture: Commercial Revolving Credit [DOMMODEL-CREDIT-001]

Summary

This specification establishes the rich Domain Model architecture, entity encapsulation boundaries, Value Object hierarchies, and pure domain calculation rules for commercial-revolving-credit-model v3.0 under run ID credit-domain-model-001. It governs commercial revolving credit facilities up to $75M across multi-currency drawdowns. It decisively eliminates the invariant leakage and state corruption demonstrated in defect BUG-4820 (where an anemic domain model exposing public setters allowed an external orchestration script to overwrite credit limits directly, issuing an unauthorized $4.5M un-collateralized loan). The architecture enforces a

Rich Domain Model pattern: strictly encapsulating state behind domain behavior methods, modeling financial concepts as

immutable Value Objects (Money, InterestRateSpread, CreditCeiling, CovenantRatio), isolating multi-entity arithmetic inside pure

Domain Services, and guaranteeing that domain classes compile with zero third-party framework dependencies.

Detailed Description

In complex financial applications, implementing an Anemic Domain Model (entities composed purely of public getters and setters, with business logic exiled to procedural "service" classes) destroys object encapsulation. External services can manipulate internal fields into invalid business states, bypassing critical business rules. A Rich Domain Model co-locates business state with the logic that mutates it: entities protect their own invariants, constructor factories guarantee that invalid objects cannot be instantiated, and immutable Value Objects eliminate primitive obsession.

External Application Service (Command: `DrawdownRevolvingCredit`)
                             │
                             ▼
[ Domain Factory: `CreditFacilityFactory` ]
  ├── Asserts: Initial Borrower Covenants & Facility Caps
  └── Mints Encapsulated `CreditFacility` Aggregate
                             │
                             ▼
[ Rich Domain Entity: `CreditFacility` (Aggregate Root) ]
  ├── 1. Encapsulated State (Private Fields, Zero Public Setters)
  ├── 2. Immutable Value Objects:
  │      ├── `CreditCeiling` (Upper bound <= $75M)
  │      ├── `InterestRateSpread` (Margin Floor >= 2.25%)
  │      └── `DrawdownSchedule` (Maturity & Repayment Dates)
  └── 3. Invokes Pure Domain Service:
         `InterestAccrualService.calculateAccruedInterest(...)`
                             │
       ┌─────────────────────┴─────────────────────┐
       ▼ (Valid Domain Mutation)                   ▼ (Invariant Breach: Over-Drawdown)
State Transition Committed in Memory         [ Domain Exception Thrown ]
Emits Domain Event: `CreditDrawnDownEvent`     Throws `CreditLimitBreachedException`

Criteria and weights

Mechanism Specifications

1. Context Boundary:

   • Owner: Principal Domain Architect (David O'Reilly).
   • Trigger: Inbound application service command (DrawdownRevolvingCredit) or domain event ingestion.
   • State/Algorithm: The bounded context isolates Commercial Revolving Credit models from upstream Commercial Lending origination and downstream Treasury clearing. Context-specific ubiquitous language and entity types are strictly preserved.
   • Failure Behavior: Any attempt to pass foreign entity classes or invoke un-mapped cross-context models triggers an immediate compilation failure or runtime Anti-Corruption Layer translation rejection.
   • Test Oracle: ArchUnit package containment rule asserting zero references to foreign domain packages outside explicit translation adapters.

2. Invariant Owner:

   • Owner: Rich Domain Aggregate Root (CreditFacility).
   • Trigger: Internal state mutation requests (drawdown(), adjustCreditCeiling(), accrueInterest()).
   • State/Algorithm: Invariants are owned and enforced directly inside the entity instance before state fields mutate. Mutating state via public setters or external orchestration services is prohibited.
   • Failure Behavior: Precondition or invariant violation throws a domain-specific exception (CreditLimitBreachedException, InvalidCovenantStateException) without altering aggregate state.
   • Test Oracle: Unit test suite test_invariant_rejection_on_overdraw verifying entity state remains unaltered when invariant check fails.

3. State Transition:

   • Owner: Core Lending Engineering Lead.
   • Trigger: Domain lifecycle commands (ActivateFacility, SuspendDrawdowns, MatureFacility).
   • State/Algorithm: Explicit finite state machine governing credit facility states (DRAFT -> ACTIVE -> SUSPENDED -> MATURED). Transitions evaluate legal source-to-target state matrices with attached precondition checks.
   • Failure Behavior: Illegal state transitions throw IllegalDomainStateTransitionException and log an auditable security event.
   • Test Oracle: State transition matrix test suite asserting all undefined or backward transitions throw expected domain errors.

4. Event Semantics:

   • Owner: Head of Commercial Underwriting (Elena Rostova).
   • Trigger: Successful aggregate state mutation commit.
   • State/Algorithm: Domain events represent committed, immutable past-tense business facts (CreditDrawnDownEvent, FacilityCeilingAdjustedEvent). Payloads carry minimal essential identifiers and deltas without leaking internal aggregate references.
   • Failure Behavior: Serialization or event dispatch failure rolls back the local transactional outbox staging record.
   • Test Oracle: Integration test confirming emitted event carries monotonically incremented aggregate version and non-empty causation ID.

Alternatives rejected

Contracts and Invariants

Zero Public Field and Setter Invariant [INV-DOMMODEL-01]
  Domain entities must not expose public setters or mutable public fields.
  State modifications must occur strictly through encapsulated, invariant-checking domain methods.

Value Object Immutability Mandate [INV-DOMMODEL-02]
  Value Objects must be completely immutable once instantiated.
  Methods on Value Objects must return fresh instances rather than mutating internal state.

Framework-Free Domain Core Invariant [INV-DOMMODEL-03]
  Classes in the domain package must have zero dependencies on third-party frameworks.
  Imports from Spring, Hibernate, Jackson, or Jakarta EE inside domain packages are strictly barred.

Ownership and Handoffs

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against domain model architecture standards:

• Encapsulation Rigor: PASS. Zero public setters; all mutations pass through behavioral methods.
• Value Object Quality: PASS. Money, Spread, and Covenants modeled as immutable types.
• Framework Independence: PASS. Domain core compiles with pure Java 21 standard library.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-DOMMODEL-01: David O'Reilly to determine whether domain entities should emit domain events directly via an internal event list (@DomainEvents) or return event tuples from domain methods (Owner: David O'Reilly).

Next steps

1. Core Lending team implements the pure domain model classes for CreditFacility and Money.
2. Platform team configures ArchUnit tests enforcing zero framework dependencies in com.bank.credit.domain.*.
3. Conduct unit test benchmark validating that 35 domain invariants execute in-memory in under 25 milliseconds.

skill: domain-model-architect

Commercial Revolving Credit Domain Model — Fitness Self-Check [DOMMODEL-CREDIT-FIT-001]

Summary

This fitness self-check evaluates the commercial revolving credit domain model architecture against three critical red-capable domain failure probes: anemic model, cross-context transaction, and duplicate language. All targeted probes pass by design construction. A self-check is supporting evidence, never the authoritative gate. Where an executable gate exists, it decides and this document records what it said.

Detailed Description

Residual Risk

• Slight memory allocation overhead from instantiating immutable Value Objects during high-volume batch interest accrual jobs. Accepted by David O'Reilly with JVM escape analysis optimizations.

Traceability

Verification

No validator was supplied, so no command was run.

Open Decisions

None.

Next steps

1. Architecture Guild incorporates ArchUnit rules enforcing domain model encapsulation in CI pipelines.
2. Engineering team runs benchmark verifying zero performance degradation from immutable Value Object instantiation.
3. Conduct quarterly domain review auditing domain models against newly introduced commercial lending covenants.