Neatoo Domain Models

Business logic belongs in the domain model, not the UI. Neatoo domain models are not DTOs that shuttle data to a smart UI. They are rich domain objects that encapsulate business rules, computed state, validation, and reactive behavior. The UI is a thin binding layer.

When implementing a feature: design domain properties and rules first. Write the UI as a binding layer over those properties. If you find yourself writing business logic in a .razor file, stop and move it to the domain model.

These patterns use RuleManager.AddAction and AddActionAsync, covered in Core Patterns below and in references/validation.md.

Where Logic Goes

The Smell Test

When writing or reviewing .razor files: if there are more than 3 conditional/computed expressions, business logic is leaking into the UI. Move it to the domain model as rules or computed properties.

// WRONG: UI computes
<MudText>@(order.Quantity * order.UnitPrice)</MudText>
@if (order.Quantity > 0 && order.UnitPrice > 0 && order.Total > 500)
{ <MudAlert>Discount!</MudAlert> }

// RIGHT: Domain computes, UI binds
// In constructor: RuleManager.AddAction(t => t.Total = t.Quantity * t.UnitPrice, t => t.Quantity, t => t.UnitPrice);
// In constructor: RuleManager.AddAction(t => t.QualifiesForDiscount = t.Total > 500, t => t.Total);
<MudText>@order.Total</MudText>
@if (order.QualifiesForDiscount) { <MudAlert>Discount!</MudAlert> }

See references/domain-logic-placement.md for detailed patterns: computed properties, conditional visibility, cascading state, async side-effects, workflow state machines, child property triggers for parent-child reactivity, class-based rules with DI, and the refactoring smell test table.

Base Class Quick Reference

Key Properties

There is no IsDirty in Neatoo. Use IsModified / IsSelfModified.

Core Patterns

Properties with Change Tracking

All Neatoo properties use partial properties. The source generator implements backing fields with automatic change tracking and validation triggering:

<a id='snippet-skill-properties-basic'></a>

public partial string Name { get; set; }
public partial decimal Price { get; set; }

^{<a href='/src/samples/QuickStartSamples.cs#L35-L38' title='Snippet source file'>snippet source</a> | <a href='#snippet-skill-properties-basic' title='Start of snippet'>anchor</a>}

The generator creates property implementations that call Getter<T>() and Setter() internally.

Factory Methods

Neatoo entities use RemoteFactory for factory generation. See the /RemoteFactory skill for factory attributes ([Factory], [Create], [Fetch], [Insert], [Update], [Delete]), service injection ([Service]), remote execution ([Remote]), and authorization ([AuthorizeFactory]).

Save Routing (Neatoo State-Based)

When Save() is called, the factory routes based on Neatoo entity state:

• IsNew == true → [Insert] method
• IsNew == false && IsDeleted == false → [Update] method
• IsDeleted == true → [Delete] method

This routing is automatic based on entity state properties.

Aggregate Save Cascading

State cascades UP automatically; saves cascade DOWN manually — each parent's [Insert]/[Update] must call childFactory.SaveAsync() on its children. See references/entities.md → "Aggregate Save Cascading" for the full pattern, rules, and anti-patterns.

Validation

Add validation rules in the constructor using RuleManager or validation attributes:

<a id='snippet-skill-validation'></a>

public SkillValidationExample(IEntityBaseServices<SkillValidationExample> services) : base(services)
{
    // Inline validation with lambda
    RuleManager.AddValidation(
        emp => string.IsNullOrEmpty(emp.Name) ? "Name is required" : "",
        e => e.Name);

    // Or use validation attributes on properties
    // [Required(ErrorMessage = "Name is required")]
    // public partial string Name { get; set; }
}

^{<a href='/src/samples/SkillValidationSamples.cs#L52-L64' title='Snippet source file'>snippet source</a> | <a href='#snippet-skill-validation' title='Start of snippet'>anchor</a>}

RuleManager also provides AddAction, AddActionAsync, AddValidationAsync, and class-based rules. AddValidation/AddValidationAsync accept exactly one trigger property — for multiple triggers, use a class-based rule. See references/validation.md for details.

Check validation state with IsValid, IsSelfValid, and PropertyMessages.

Rules Do NOT Fire During Factory Methods

Rules (including AddAction computed properties) do NOT fire during [Create], [Fetch], [Insert], [Update], [Delete], or LoadValue. Factory operations are wrapped in PauseAllActions(). ResumeAllActions() does NOT run rules — it only recalculates cached validity. PropertyChanged does NOT fire for changes made while paused.

RunRules works while paused — it has no IsPaused guard. Call await RunRules(RunRulesFlag.All) at the end of any factory method that sets properties with dependent AddAction rules:

[Create]
public async Task Create()
{
    Quantity = 10;
    UnitPrice = 5.00m;
    await RunRules(RunRulesFlag.All);  // Forces computed properties to populate
    // Total is now 50.00
}

Without this call, computed properties remain at their default values when the entity reaches the client. See references/rules-lifecycle.md for the complete execution lifecycle, RunRulesFlag enum reference, and the factory method timeline.

Child Property Triggers — Parent Reacts to Child Changes

To react to child property changes in an aggregate, use a child property trigger expression with AddAction. The [0] indexer is a syntactic placeholder — any child whose named property changes triggers the rule:

// Parent recalculates when any child's LineTotal changes
RuleManager.AddAction(
    t => t.OrderTotal = t.Items?.Sum(i => i.LineTotal) ?? 0,
    t => t.Items![0].LineTotal);

// Multiple child property triggers
RuleManager.AddAction(
    t => t.HasInvalidQuantities = t.Items?.Any(i => i.Quantity <= 0) ?? false,
    t => t.Items![0].Quantity);

The action body can also push changes to other children — the parent acts as orchestrator:

// When ShippingAddress.State changes, update tax on all items
RuleManager.AddAction(
    t => { foreach (var item in t.Items!) item.TaxRate = TaxRates.Get(t.ShippingAddress!.State); },
    t => t.ShippingAddress!.State);

Do NOT use t => t.Items as the trigger — that only fires when the Items property reference itself is reassigned, not when child items change. TriggerProperty.IsMatch uses exact string equality: "Items" != "Items.LineTotal".

See references/domain-logic-placement.md → "Pattern 6: Child Property Triggers" for child triggers, orchestrator patterns, NeatooPropertyChanged, and HandleNeatooPropertyChanged overrides.

Testing

Critical: Never mock Neatoo interfaces or classes. Use real factories and mock only external dependencies. Use [SuppressFactory] on test-only classes that inherit from Neatoo base classes. See references/testing.md for patterns and references/pitfalls.md for common mistakes.

Reference Documentation

Detailed documentation for each topic area:

• references/domain-logic-placement.md - Where business logic belongs: computed properties, conditional visibility, cascading state, async side-effects, child property triggers, workflow state machines, refactoring smell test
• references/base-classes.md - Neatoo-to-DDD mapping, when to use each base
• references/properties.md - Partial properties, change tracking, calculated properties
• references/validation.md - RuleManager, attributes, async validation
• references/rules-lifecycle.md - When rules fire and when they don't, RunRulesFlag enum, factory method gap, RunRules works while paused
• references/shared-rules.md - Shared rules across entities via interface-typed AsyncRuleBase and DI injection
• references/entities.md - EntityBase lifecycle, persistence, Save routing
• references/collections.md - EntityListBase, parent-child relationships, deletion tracking
• references/lazy-loading.md - EntityLazyLoad<T>, IEntityLazyLoadFactory, explicit LoadAsync(), passive Value read, WaitForTasks integration
• references/source-generation.md - What gets generated, Generated/ folder, [SuppressFactory]
• references/trimming.md - IL trimming annotations, suppression strategy, consumer project setup
• references/blazor.md - Blazor-specific binding and component patterns (see also the MudNeatoo skill for component binding and anti-patterns)
• references/testing.md - No mocking Neatoo, integration test patterns
• references/pitfalls.md - Common mistakes and gotchas

RemoteFactory topics (see /RemoteFactory skill):

• Factory attributes, service injection, remote execution, authorization

Troubleshooting

See references/pitfalls.md for common issues. Key quick checks: class and properties must be partial, class needs [Factory] attribute, and IsSavable requires both IsValid and IsModified.