Deep DDD & Model Improvements Roadmap

[alfredorueda]

🧠 Deep DDD & Model Improvements Roadmap

🎯 Purpose

This issue tracks structural improvements in the model package to:

• Strengthen DDD alignment
• Make invariants explicit
• Improve SOLID compliance
• Remove hidden assumptions
• Increase long-term maintainability

This is not a bug fix.
This is a model hardening and architectural refinement task.

---

🔴 Priority 1 – Critical Domain Consistency

☐ Refactor Transaction to be DDD-consistent

• ☐ Decide: Entity or true Value Object?

• ☐ If Value Object:

  • ☐ Convert to immutable (record)
  • ☐ Remove null-permitted states
  • ☐ Add static factory methods per type
  • ☐ Enforce invariants per TransactionType

• ☐ If Entity:

  • ☐ Remove "Value Object" claim in Javadoc
  • ☐ Make fields effectively immutable
  • ☐ Validate construction invariants

• ☐ Align documentation with real behavior

---

☐ Make FIFO explicit in Holding.sell()

• ☐ Define FIFO rule formally (by purchasedAt)
• ☐ Sort lots before selling OR
• ☐ Replace internal structure with ordered queue
• ☐ Add unit test proving FIFO independent of insertion order

---

🟠 Priority 2 – Domain Invariants Clarification

☐ Define invariant for empty holdings

• ☐ Decide: remove holding when shares reach zero?

• ☐ If yes:

  • ☐ Remove holding after final sale
  • ☐ Add unit test for this behavior

• ☐ If no:

  • ☐ Document explicitly in Javadoc

---

☐ Standardize exception strategy

• ☐ Introduce DomainException base class
• ☐ Replace IllegalArgumentException in domain layer
• ☐ Align JavaDoc with actual thrown exceptions
• ☐ Ensure consistency across all IDs and Value Objects

---

🟡 Priority 3 – Model Expressiveness Improvements

☐ Replace ownerName String with OwnerName Value Object

• ☐ Enforce non-blank
• ☐ Trim input
• ☐ Possibly length validation
• ☐ Add unit tests

---

☐ Reduce redundant validations (improve DRY)

• ☐ Audit duplicate checks in:

  • ☐ Portfolio.buy
  • ☐ Lot.create
  • ☐ Portfolio.deposit

• ☐ Centralize validation inside Value Objects where possible

• ☐ Keep defense-in-depth but remove unnecessary duplication

---

🟢 Priority 4 – Minor Cleanups & Naming

• ☐ Rename awkward method names (e.g. getRemainingSharesPurchasePrice)
• ☐ Avoid repeated getTotalShares() calls in same block
• ☐ Improve domain wording consistency
• ☐ Review Javadoc coherence across model

---

🧪 Optional Hardening Tasks

• ☐ Add tests for invariant enforcement
• ☐ Add tests for FIFO correctness after rehydration
• ☐ Add tests for invalid Transaction states
• ☐ Review aggregate boundaries under stress scenarios

---

📌 Acceptance Criteria

This issue can be closed when:

• All critical invariants are explicit
• Transaction modeling is internally consistent
• FIFO behavior is deterministic and tested
• Exception strategy is unified
• Domain language is coherent and expressive
• No hidden ordering assumptions remain

---

🧭 Long-Term Vision

Goal:
Turn this model into ailgrade DDD reference implementation suitable for:

• Teaching advanced DDD
• Architectural demonstrations
• Production-grade domain modeling patterns