CtrlK
BlogDocsLog inGet started
Tessl Logo

pantheon-ai/software-design-principles

Apply software design principles across architecture and implementation using deterministic decision workflows, SOLID checks, structural patterns, and anti-pattern detection; use when reviewing designs, refactoring modules, or resolving maintainability and coupling risks.

Does it follow best practices?

Evaluation99%

1.01x

Agent success when using this tile

Validation for skill structure

Overview
Skills
Evals
Files

entity-encapsulate-invariants.mdreferences/

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

Install with Tessl CLI

npx tessl i pantheon-ai/software-design-principles

SKILL-FULL.md

SKILL.md

tile.json