Model a Behavior Module

Prerequisites#

• Finish Start a Consumer Repository through its configuration steps.
• Read the product brief and the requirements this module fulfills.
• Read the decisions that constrain identity, persistence, security, or external behavior.
• Copy the module.yaml, aggregate.yaml, and use-case.yaml templates from the template index, and open .litespec/glossary.yaml for the module terms.

Lesson#

1. Name the module terms: write one term entry per word with its meaning, its layer, its aliases, and the words it rejects. Use the same term in documentation, domain types, use cases, API descriptions, and frontend features. This satisfies litespec/backend/domain#use-one-ubiquitous-language, litespec/core/domain-model#define-every-behavior-term-in-the-glossary, and litespec/core/domain-model#mark-each-term-with-its-layer.

   Term	Meaning	Layer	Aliases	Rejected words
   term/expense	One work cost an employee submitted for approval	behavior	claim	Voucher
   term/receipt	Proof of payment attached to an expense	behavior	proof of payment	Docket
   term/policy	The company spending policy and its receipt threshold	behavior	None	None
   term/approver	The manager who decides a submitted expense	behavior	None	None

   Rejected words stop a later contributor from creating Voucher beside Expense. Aliases let industry readers find your word under the name they already know. They also tell an agent which plausible names are wrong for this domain and which are accepted synonyms.

2. Write the Example section before the rules. Name one occasion the module exists for: who acts, what surrounds them, and what they use today instead. Record it in the module's explanation file under Example, and reuse its people and figures in every record beneath it. Keep the shared cast on the example cast page. This satisfies litespec/core/behavior#illustrate-pages-with-examples-from-the-cast.

   Month end brings every team's expenses at once: employees paid work costs from their own pockets and wait weeks for a decision, chasing managers by email. Without an expense record, finance reconstructs who spent what from forwarded receipts and memory.

3. Write the module record file with its summary. Give the module a person-chosen identifier such as module/spending. Name each module it depends on, or remove the dependency field when the module stands alone. Spending depends on no other module, so its dependency list stays empty. This satisfies litespec/core/domain-model#state-every-module-dependency.

4. Draw aggregate boundaries from invariants. An aggregate is a consistency boundary: state that must stay valid together in one command. An invariant is a condition that holds before and after every successful change. Declare the kind of every aggregate: entity for guarded state, saga for a multi-step aggregate, and store for state no invariant guards. This satisfies litespec/backend/domain#treat-aggregates-as-consistency-boundaries, litespec/backend/domain#keep-child-entities-inside-the-aggregate-boundary, and litespec/core/domain-model#declare-the-kind-of-every-aggregate.

   Aggregate	Kind	Owns	References by typed ID
   aggregate/spending.expense	entity	Expense lifecycle, total, reimbursement facts	ReceiptId, EmployeeId
   aggregate/spending.receipt	entity	Receipt attachment and removal	ExpenseId
   aggregate/spending.policy	store	The current receipt threshold value	None

   The policy store names its owner, the spending settings store, and carries no states, because no invariant guards the stored value: the setting record declares its default and bounds. This satisfies litespec/core/domain-model#name-the-owner-of-every-store. An aggregate owns a child when the child has no independent boundary and changes only through the aggregate. Reference another aggregate by typed ID when it changes on its own. Do not place Employee inside Expense for convenient navigation. This satisfies litespec/backend/domain#reference-other-aggregates-by-id. A saga kind would add steps with compensations and guards, named exits, and drivenBy; spending needs none.

5. Define every state. A state is a business-valid condition with its required data and permitted behavior. Describe states before writing transitions. This satisfies litespec/backend/domain#model-every-aggregate-lifecycle-with-state-types and litespec/core/domain-model#model-each-aggregate-lifecycle-with-states.

   State	Meaning	Required facts
   Submitted	The expense awaits a decision	None
   Approved	The manager approved the expense	Approver, decision date
   Refused	The manager refused the expense	Approver, decision date, reason
   Reimbursed	Finance reimbursed the expense	Reimbursement date

   Create an abstract state record and one sealed record per state. Put state-specific data on the state record. This satisfies litespec/backend/dotnet/domain#model-every-aggregate-lifecycle-with-state-records.

   public abstract record ExpenseState;
   
   public sealed record ExpenseSubmittedState : ExpenseState;
   
   public sealed record ExpenseApprovedState(Guid ApprovedBy, DateTimeOffset DecidedAt) : ExpenseState;
   
   public sealed record ExpenseRefusedState(Guid RefusedBy, DateTimeOffset DecidedAt, string Reason) : ExpenseState;
   
   public sealed record ExpenseReimbursedState(DateTimeOffset ReimbursedAt) : ExpenseState;

   For each state, answer what makes it true, which data it alone requires, and which actions it allows and rejects. Leave no state half-defined.

6. Connect the states with transitions. List every allowed state change with the use case that moves it in the aggregate's transitions field. This satisfies litespec/core/domain-model#connect-every-state-through-transitions.

   From	To	By
   None	Submitted	use-case/spending.submit-expense
   Submitted	Approved	use-case/spending.approve-expense
   Submitted	Refused	use-case/spending.approve-expense
   Approved	Reimbursed	use-case/spending.reimburse-expense

   Creation is a transition from None, so the first state stays reachable. One use case can move more than one transition: approval ends submitted either approved or refused.

7. Declare the data classes with their erasure positions. A data class groups fields that share one classification and one fate on erasure. Then list every field the aggregate keeps with its meaning, data class, and classification in the aggregate's data field. This satisfies litespec/core/privacy#declare-every-data-class-with-its-erasure-position and litespec/core/privacy#classify-every-aggregate-data-field.

   Data class	Classification	Fields	On erasure	Enforced by
   expense-money	internal	amount, state	retain for 7 years by statute	record-expiry
   submitter	personal	employee	erase on approved request	job/spending.erase-expired-personal-data

   Name	Meaning	Data Class	Classification
   total	The amount claimed, with its currency	expense-money	internal
   receipt	The payment proof attached to the expense	expense-money	internal
   approver	The manager who decided, once decided	expense-money	internal
   employee	The employee who submitted the expense	submitter	personal

   Every field names its data class, so the retention schedule can erase by class instead of by table. A personal or sensitive class that is retained or exempt needs an Intent decision or requirement accepting it.

8. Write the rules with kinds. Give each rule a person-chosen identifier of one to six lowercase words. A statement with not, no, never, or cannot keeps that word in its name. This satisfies litespec/core/domain-model#state-each-rule-with-its-kind and litespec/core/domain-model#keep-the-negation-word-in-the-rule-name.

   Rule	Kind	Statement	Refusal
   rule/expense.receipt-required-above-threshold	precondition	An expense above the policy threshold needs a receipt.	result/submit-expense.receipt-missing
   rule/expense.approver-is-not-submitter	invariant	An approver is not the submitter.	result/approve-expense.own-expense
   rule/expense.reimbursed-once	invariant	An expense is reimbursed at most once.	result/reimburse-expense.already-reimbursed
   rule/expense.approved-before-reimbursement	precondition	An expense is reimbursed only after approval.	result/reimburse-expense.not-approved
   rule/receipt.attaches-before-decision	precondition	A receipt attaches before the expense is decided.	result/attach-receipt.expense-decided

   An invariant holds after every change to its aggregate. A precondition guards the behavior before it runs and refuses caller-correctable input. A calculation derives a value and is proven by a scenario with examples. A cross-aggregate rule spans aggregates and lives on a rule record file. The remaining kinds cover atomicity, held reservations, frozen commercial values, and fallback defaults. Each rule that refuses names its refusal. This satisfies litespec/core/domain-model#name-the-refusal-a-broken-rule-produces and litespec/core/domain-model#keep-cross-aggregate-rules-on-a-rule-page. The cross-aggregate rule rule/spending.receipt-filed-once, a receipt file supports one expense across spending, lives on the spending rule record file. A tunable bound such as the threshold is a setting, not a rule. Input shape stays in the validator; current aggregate state stays in the aggregate. This satisfies litespec/backend/application#separate-input-validation-from-invariants.

9. Name the people and their permissions. Write one actor record file per party and one role record file per grantable set. Roles grant permissions; each use case later declares its access against one grant. This satisfies litespec/core/access#grant-permissions-through-roles and litespec/backend/application#enforce-target-authorization-in-the-pipeline.

   Actor	Role	Permission
   actor/employee	role/employee at self scope	permission/submit-expense
   actor/manager	role/approver at team scope	permission/approve-expense
   actor/finance	role/finance at platform scope	permission/reimburse-expense

10. Write the use cases. Give each use case a name that is unique across the project, so its results and scenarios resolve. Name the kind, command or query, the goal, what happens, the journey steps it serves, the requirements it fulfills, the access it declares, the entry points, the aggregates it changes and reads, its consistency, its effects, and the events it raises. This satisfies litespec/backend/application#use-this-use-case-layout, litespec/core/use-cases#give-each-use-case-a-command-or-query-kind, litespec/core/use-cases#connect-each-use-case-to-intent, and litespec/core/access#declare-access-on-every-use-case.

    Use case	Kind	Serves	Access grant	Changes	Consistency
    use-case/spending.submit-expense	command	journey/submit-and-reimburse#s1	permission/submit-expense	aggregate/spending.expense	atomic
    use-case/spending.approve-expense	command	journey/submit-and-reimburse#s2	permission/approve-expense	aggregate/spending.expense	atomic
    use-case/spending.reimburse-expense	command	journey/submit-and-reimburse#s3	permission/reimburse-expense	aggregate/spending.expense	atomic
    use-case/spending.list-expenses	query	journey/submit-and-reimburse#s4	self(permission/list-expenses)	None	None

    At least one of serves and fulfills is present on every use case. Access declares one grant and the tenant scope; a grant of self(...) limits the permission to the caller's own records. changes and reads name every aggregate the use case touches, and consistency states how the writes hold together. This satisfies litespec/core/use-cases#grant-each-use-case-scoped-access, litespec/core/use-cases#name-every-aggregate-a-use-case-changes-or-reads, and litespec/core/use-cases#state-the-consistency-of-every-use-case. Every edge the use case causes goes in effects with one verb and its timing: runs, sends, emits, or calls. This satisfies litespec/core/use-cases#declare-every-effect-with-one-verb-and-its-timing. Every input field names its origin and classification, and caller-supplied values on money or access paths carry bounding rules. This satisfies litespec/core/use-cases#describe-every-use-case-input-with-origin-and-classification. Every use case names its idempotency and, for commands, its audit position. This satisfies litespec/core/use-cases#name-the-idempotency-of-every-use-case and litespec/core/use-cases#state-the-audit-position-of-every-command.

    A query changes nothing and declares its output in include groups with freshness, plus its paging. This satisfies litespec/core/use-cases#declare-every-query-output and litespec/core/use-cases#declare-paging-on-every-collection-query.

11. Write one result per ending. A result is one way a use case ends: success, or a named refusal with its stable code. List refusals in precedence order, first match wins. This satisfies litespec/core/use-cases#end-every-use-case-in-named-results, litespec/core/use-cases#order-every-refusal-list-by-precedence, and litespec/backend/application#model-expected-use-case-refusals-explicitly.

    Result	Outcome	Code	Meaning
    result/submit-expense.submitted	success	None	The expense is submitted.
    result/submit-expense.receipt-missing	refusal	spending.receipt-missing	The expense is above the threshold and carries no receipt.

    Never write the generic forbidden or invalid-input refusals: the use case derives them from its access and input. This satisfies litespec/core/use-cases#derive-generic-refusals-instead-of-writing-them. A refusal that stores the attempt carries recorded: true; a success with recorded outcomes inside it carries codes. Each refusal explains what the caller sees. The code is stable across releases. The backend stack derives the HTTP status from the outcome. This satisfies litespec/backend/api#use-consistent-status-codes.

12. Write the scenarios. A scenario is one working example in given, when, then: the situation, the action, and the expected ending. Each scenario names the result it ends in. A scenario with no proving test yet becomes a gap exception record with an expiry date. This satisfies litespec/core/use-cases#write-every-scenario-in-given-when-then and litespec/core/use-cases#name-the-result-each-scenario-ends-in.

    Scenario	Given	When	Then	Result
    scenario/submit-expense.submitting-with-a-receipt-succeeds	An employee paid for a train ticket and kept the receipt.	The employee submits the expense with the receipt.	The expense is submitted.	result/submit-expense.submitted
    scenario/approve-expense.approving-a-submitted-expense-succeeds	An employee submitted an expense with its receipt.	The manager approves the expense.	The expense is approved.	result/approve-expense.approved

    When the scenario proves a calculation, add examples with the debated rows. This satisfies litespec/core/domain-model#tabulate-every-calculation-with-examples. Name each test by the observable behavior it asserts. This satisfies litespec/backend/testing#name-tests-by-observable-behavior. An acceptance test carries one proves mark naming its scenario. The model builder confirms the claim when the test calls the use case through the public boundary and asserts the result the scenario names.

13. Record the events. A domain event is an immutable record of a completed fact. Name what completed and which fields it carries. This satisfies litespec/core/domain-model#state-each-event-with-meaning-and-carries and litespec/backend/dotnet/domain#raise-immutable-domain-facts.

    Event	Meaning	Carries
    event/expense.submitted	An expense was submitted.	expenseId, amount, currency, employeeId
    event/expense.reimbursed	An expense was reimbursed.	expenseId, amount, currency, reimbursedAt

    A fact that leaves the product is an integration event with a direction, a CloudEvents type and source, and a payload. Reimbursing emits integration-event/payout.requested, which translates event/expense.reimbursed for the payout bank. The use case declares it in effects with emits. This satisfies litespec/core/edges#describe-every-integration-event-for-its-direction and litespec/core/edges#publish-every-outbound-integration-event-from-effects.

14. Write the reactions, jobs, notifications, and settings as their own records. Work that answers an event is a reaction: it names the events in triggeredBy and runs its use cases through effects, and it never writes an aggregate directly. Work that runs on a schedule or by hand is a job: it names its kind with its schedule, selection, and guard, and it never writes an aggregate directly either. This satisfies litespec/core/automation#trigger-every-reaction-from-its-declared-events, litespec/core/automation#run-every-job-from-its-declared-kind, litespec/core/automation#declare-every-reaction-and-job-edge-in-effects, and litespec/core/automation#write-no-aggregate-directly-from-a-reaction-or-job. File each reaction and job with the module whose records it changes, and run each reaction in a dedicated handler. This satisfies litespec/core/automation#file-every-reaction-and-job-with-the-module-it-changes and litespec/backend/dotnet/application#run-reactions-in-dedicated-handlers.

    Record	Shape
    reaction/spending.notify-on-reimbursement	On event/expense.reimbursed, sends notification/spending.reimbursement-received.
    job/spending.send-approver-reminders	Scheduled nightly; runs use-case/spending.send-approver-reminder per waiting expense.
    notification/spending.approver-reminder	Email to the manager with the expense and its waiting time.
    setting/spending.receipt-threshold	Money, default EUR 25, set by the operator, refuses at the bound.

    Declare every reaction with the events it answers and every job with its kind; a manual job also states where it runs and its guard. This satisfies litespec/core/automation#trigger-every-reaction-from-its-declared-events, litespec/core/automation#run-every-job-from-its-declared-kind, and litespec/core/automation#guard-every-manual-job. Describe every notification with its addresses, channel, and consent, and claim each promise it makes from a requirement. This satisfies litespec/core/edges#describe-every-notification-with-audience-channel-and-consent and litespec/core/edges#claim-every-notification-promise-from-a-requirement. Hold every commercial, legal, or varying setting default to a requirement, and keep model invariants in rules. This satisfies litespec/core/use-cases#hold-every-setting-default-to-a-requirement and litespec/core/domain-model#keep-model-invariants-in-rules.

15. Name the entry points and the external systems. Give each entry point its kind: the expenses app is a browser, the payout bank callback is a webhook. This satisfies litespec/core/access#name-every-entry-point-with-its-kind. Declare every operation on the payout bank with its timeout, retries, and response, and route erasure through an operation. This satisfies litespec/core/access#declare-every-operation-on-every-external-system and litespec/core/access#declare-erasure-for-every-external-system. Schedule every data class for retention with its basis, period, enforcement, and Intent acceptance. This satisfies litespec/core/privacy#schedule-every-data-class-for-retention.

16. Keep one transaction per command. One handler stages the aggregates its use case owns and lets the pipeline commit once, with the consistency the record declares. This satisfies litespec/backend/application#dispatch-only-declared-effect-edges and litespec/backend/persistence#commit-each-command-pipeline-once.

17. Map the model to folders. Mirror the module, aggregate, UseCases/, and use case path in every layer. This satisfies litespec/backend/architecture#organize-code-by-module-aggregate-and-use-case.

    apps/api/src/Claimwick.Modules/
      Spending/
        Expenses/
          Domain/
            Expense.cs
            ExpenseState.cs
            Events/
              ExpenseSubmittedEvent.cs
            Exceptions/
              ExpenseReceiptMissingException.cs
          UseCases/
            SubmitExpense/
              SubmitExpenseCommand.cs
              SubmitExpenseCommandHandler.cs

    Create subfolders only when real types require them. The folders mirror the records so a reader finds the code; the builder follows the marks from code up to the records.

18. Run the model check. Run litespec model check from the consumer root. It resolves every citation, follows the marks from code and tests to their records and the screens calling each use case, prints a level beside each finding, and reports each unproved scenario. The command index states how litespec runs in a consumer.

What You Built#

• One module with its terms, aggregates, data classes, rules, use cases, results, scenarios, events, reactions, jobs, notifications, settings, and permissions.
• Every identifier is person-chosen, every citation resolves, and every edge between records is declared.
• Every scenario is proved by a passing test or covered by a gap exception.