high-level domain-keyword organization

• high-level backend business behavior lives under domains/<keyword>/; <keyword> = the easiest, shortest project-scope word for the concept. lexical home, not a claim of an independent subsystem.
• lower-level mechanisms (persistence, providers, mapping, validation) follow layered source organization.
• one word loses a necessary relationship -> shortest exact compound: workflowStep, not providerWorkflowStep.
• keyword home is earned, not scaffolded: create domains/<keyword>/ when policy, use cases, or flows actually accumulate on the noun — never in advance.
• concept gains consumers in another workspace project -> extract a package named by the same keyword; ownership follows pnpm workspace boundaries.

• the folder tree is the first map a reader or agent consults.
• business behavior scattered across screen folders, vendor prefixes, or generic buckets -> the concept cannot be named from the tree; domain-noun searches return unrelated locations.
• one lexical home for high-level policy keeps business ownership visible, navigable, safe for concurrent refactors.

• make high-level business concepts navigable and searchable as one vocabulary.
• a reader tracing an outcome starts at the domain noun and reaches policy, use case, or flow without translating screen, vendor, or implementation names.

the folder answers "where would a new reader look first for this business decision?" it holds policy, invariant, use case, flow, and domain vocabulary sharing the canonical noun — not every technical mechanism the domain uses.

1. add the concept to the domain glossary.
2. choose the shortest easy word a project reader immediately associates with the concept.
3. place policies, use cases, flows, and business vocabulary under that keyword once such code exists.
4. extract a keyword-named package when consumers cross project boundaries.
5. route lower-level mechanisms to the layered source-organization owner.

• name a context after a screen, vendor, or temporary implementation.
• scaffold domains/<keyword>/ before any policy accumulates on the noun.
• put high-level business policy in a generic services/ bucket.
• keep a long technically precise name when it makes the domain list harder to navigate than the shortest exact glossary term.

bad

order behavior scattered by technical concern, no one high-level owner:

src/
  screens/orders/OrderListScreen.tsx
  vendor-portal/orders/VendorOrderList.tsx
  services/OrderService.ts
  services/OrderValidator.ts
  adapters/order-api-adapter.ts
  domains/reporting/             # scaffolded; no reporting code exists yet

• discovering the outcome requires searching several screen, vendor, and generic technical names.
• the business keyword does not identify one high-level owner.
• the empty reporting/ scaffold spends navigation cost on a decision no code has made yet.

good

order business behavior under one high-level domain keyword:

src/
  domains/order/
    submitOrder.ts
    orderPolicy.ts
    orderRoutes.ts

• rg "order" finds one high-level policy owner.
• a new developer tracing business behavior starts at domains/order/; the lower-level technical tree follows the linked layered source-organization standard.

• list the high-level domain folders without opening files: each must name a business keyword and contain code that earned it — no empty scaffolds.
• search a domain noun afterward: its policy, use cases, and flows should cluster under that lexical home, not under screen, vendor, or generic service folders.

domain glossary · shortest exact names · regex-friendly codebase · layered source organization · pnpm workspace boundaries · shortest-domain vocabulary