Naming and Code Style

Leading with the root name reveals the owner without folder context. The rule covers events, states, child entities, values, and discriminated unions. A type nested inside a declaring type inherits that type's prefix through its qualified name, so PostState.Published satisfies the rule while a flat PostStatePublishedState repeats the anchor twice.

PostPublishedEvent and PostState.Published both lead with Post. PublishedState declared at namespace level does not.

Reviewed forEach aggregate-owned type name in apps/api/src begins with its aggregate root name, through nesting or prefix.

Marked guidance: a reviewer answers this question.

An event handler folder starts with On and names the business fact without the Event suffix: OnPostPublished holds NotifySubscribersOnPostPublishedHandler for PostPublishedEvent (litespec/workspace/naming#group-event-handlers-by-the-fact-they-handle). The On prefix already marks the handler, and folder names carry no technical suffix, so OnPostPublishedEvent is wrong. The event type keeps its Event suffix (litespec/workspace/naming#anchor-aggregate-owned-types-on-the-aggregate-root).

Application types keep their full suffix: {UseCase}Result, {UseCase}Handler, and {UseCase}Validator shorten away the command-or-query distinction the full name carries. A result part carries the full name of its result, as litespec/workspace/naming#name-result-parts-after-their-result states, not a bare summary name like PostSummary. The full role suffix distinguishes command coordination from query projection without opening the file.

HTTP transport types keep their full suffix too: {UseCase}Request and {UseCase}Response shorten away the boundary marking. Model marks the type as passive boundary data rather than an operation or rich business object. Other project-owned, passive HTTP DTOs also name their concrete role and end in Model, such as ListPostsResponseItemModel or PaginationModel.

A polymorphic transport model mirrors a Domain discriminated union (litespec/backend/api#mirror-a-domain-closed-set-as-a-transport-model-of-the-same-shape). Its abstract base names the concept and each sealed case names its case, with both ending in Model: FulfillmentOutcomeModel and ShippedFulfillmentOutcomeModel.

The transport name drops the Domain union's aggregate prefix, such as OrderFulfillmentOutcome, while its discriminator string keeps the Domain union's stable case code unchanged.

Checked bydotnet build reports LS2005 for a handler missing its command or query suffix, LS2006 for an endpoint missing its suffix, and LS2007 for a reaction or job whose name hides its kind, in the dotnet stack; each other type name in apps/api/src and each frontend file name carries the suffix its role assigns in the Role Suffixes table.

Marked checkable: the tool named here checks it.

A result part named for its own shape instead of its result collides with every other use case shaping the same thing: two summaries named PostSummary answer different queries with different fields. Leading with the full result name keeps each part beside the result it belongs to in every listing, and keeps command coordination apart from query projection without opening the file.

ListPostsQueryResultItem belongs to ListPostsQueryResult, and ReadLoanQueryResultHold belongs to ReadLoanQueryResult.

Checked bydotnet build reports LS2009 for a type a use-case result reaches through its properties whose name does not start with the result name, in the dotnet stack.

Marked checkable: the tool named here checks it.

The folder answers "what happens when this fact is recorded?" with one listing: one folder holds every handler of that fact in that module. The subscriber is the module whose records the handler changes, or for a handler that changes nothing, the module that owns the fact. A folder named for the handler instead scatters one fact across as many folders as handlers.

Lending/UseCases/OnLoanBorrowed/SendDueNoticeOnLoanBorrowedHandler sends the due notice when a loan is borrowed.

Checked bylitespec model check reports code-placement-drift (level S) for an event handler declared outside the On{Fact} folder its event names.

Marked checkable: the tool named here checks it.

A short plural name hides which aggregate the variable guards: orders could be a list, a query, or the repository, and each reader guesses. Naming the variable after its interface keeps one name per repository at every use site, so a reviewer reads the dependency from the name alone.

A parameter of type IExpenseRepository is named expenseRepository, and a field of type ILoanRepository is named loanRepository.

Checked bydotnet build reports LS2010 for a repository parameter, field, or local whose name does not follow its interface, in the dotnet stack.

Marked checkable: the tool named here checks it.

A caller decides from the signature whether to await and what to cancel. Naming the asynchrony and accepting cancellation explicitly put both answers in the signature. An operation is cancelable when it performs I/O or awaits; anything else has nothing to cancel.

Reviewed forEach asynchronous operation name reveals asynchrony, and each cancelable operation signature takes cancellation explicitly; read the public signatures in apps/api/src.

Marked guidance: a reviewer answers this question.

An exception name is the first diagnosis: it states which rule failed on which type. {DomainType}{Reason}Exception puts both in the name. DomainType is the aggregate root or an anchored owned type, so the name always starts with the aggregate root.

Reviewed forEach exception name states its failed rule, with Domain rejections in {DomainType}{Reason}Exception form leading with the aggregate root.

Marked guidance: a reviewer answers this question.

A boolean answers a yes-or-no question, so its name asks one. Is, Has, Can, or a precise verb make the question explicit: HasLines and CanPublish state a condition. LinesPresent and CheckPublish state neither a question nor an answer, so the caller reads the body to learn the polarity.

Reviewed forEach boolean property and method name in apps/api/src starts with Is, Has, Can, or a precise verb.

Marked guidance: a reviewer answers this question.

A pinned language version gives every writer the same constructs. Using the current construct over its older equivalent keeps one idiom across the codebase instead of one per author. In the dotnet stack, collection expressions, pattern matching, and primary constructors express the same intent with less incidental code.

Reviewed forProduction code targets the pinned language version and uses its current constructs; read the toolchain pins and the language idioms in apps/api/src.

Marked guidance: a reviewer answers this question.

Kebab-case folders, PascalCase components with matching exports, and use-{name} hooks give every file one predictable name. One mapping lets a reader move between the documentation tree and the source tree without translation, and lets an agent derive the file from the feature name.

Reviewed forEach frontend folder uses kebab-case, each component file and export uses PascalCase, and each React hook file uses use-{name}.

Marked guidance: a reviewer answers this question.