CtrlK
BlogDocsLog inGet started
Tessl Logo

pantheon-ai/design-principles

Strategic architecture, tactical design, and testable code principles (SOLID, Clean Architecture, Design Patterns, Testable Design)

97

Quality

97%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

entity-encapsulate-invariants.mdclean-architecture/references/

title:
Encapsulate Business Invariants Within Entities
impact:
CRITICAL
impactDescription:
prevents invalid state, centralizes validation
tags:
entity, invariants, validation, encapsulation

Encapsulate Business Invariants Within Entities

Business rules that must always be true (invariants) should be enforced by the entity itself. External code should not be able to put an entity into an invalid state.

Incorrect (invariants scattered outside entity):

# application/usecases/transfer_money.py
class TransferMoneyUseCase:
    def execute(self, from_id, to_id, amount):
        from_account = self.repo.find(from_id)
        to_account = self.repo.find(to_id)

        # Validation scattered in use case
        if from_account.balance < amount:
            raise InsufficientFundsError()
        if amount <= 0:
            raise InvalidAmountError()
        if from_account.status != 'active':
            raise AccountInactiveError()

        from_account.balance -= amount  # Direct field mutation
        to_account.balance += amount

# Another use case might forget these checks!

Correct (invariants enforced by entity):

# domain/entities/account.py
class Account:
    def __init__(self, id: AccountId, balance: Money, status: AccountStatus):
        self._id = id
        self._balance = balance
        self._status = status

    def withdraw(self, amount: Money) -> None:
        self._ensure_active()
        self._ensure_positive_amount(amount)
        self._ensure_sufficient_funds(amount)
        self._balance = self._balance.subtract(amount)

    def deposit(self, amount: Money) -> None:
        self._ensure_active()
        self._ensure_positive_amount(amount)
        self._balance = self._balance.add(amount)

    def _ensure_active(self) -> None:
        if self._status != AccountStatus.ACTIVE:
            raise AccountInactiveError(self._id)

    def _ensure_positive_amount(self, amount: Money) -> None:
        if amount.is_zero_or_negative():
            raise InvalidAmountError(amount)

    def _ensure_sufficient_funds(self, amount: Money) -> None:
        if self._balance.less_than(amount):
            raise InsufficientFundsError(self._id, self._balance, amount)

# application/usecases/transfer_money.py
class TransferMoneyUseCase:
    def execute(self, from_id, to_id, amount):
        from_account = self.repo.find(from_id)
        to_account = self.repo.find(to_id)

        from_account.withdraw(amount)  # Invariants guaranteed
        to_account.deposit(amount)

Benefits:

  • Impossible to create invalid account state
  • Validation rules documented in one place
  • Every use case gets consistent validation automatically

Reference: Domain-Driven Design - Aggregates

clean-architecture

SKILL.md

tile.json