code-placement

name	code-placement
description	Use BEFORE `domain-development`/`feature-development` when the target layer (domain, aggregate, feature, widget, shared) is uncertain — multi-layer changes, new abstractions, promoting code out of a feature, or "where should this live?". Skip when the layer is obvious.

Code Placement

Decide layer BEFORE writing code. Wrong layer = expensive to undo because dependents accumulate.

Layer dependency rule (read up-the-graph): shared ← domains / aggregates ← features / widgets / routes. Never the reverse.

Decision table

What you have	Where it goes
Persistent, entity-shaped data; stateless rules over an entity	src/domains/{domain}/
Cross-feature runtime state (active selection, in-progress flow, user context)	src/aggregates/{aggregate}/
Single-feature transient state (wizard step, draft, focus, dropdown)	src/features/{feature}/state/
One or a few tightly-coupled user flows + their UI	src/features/{feature}/
State-aware composite UI reused by 3+ features	src/widgets/{Name}/
Stateless reusable UI / generic helper / primitive	src/shared/{library}/

Sharper checks

• Logic mentions a specific entity (account, chain, product, message, tab) → domain.
• Question is "what is currently selected/active/in-progress" → aggregate.
• Component reads/writes app state but is needed by 3+ features → widget.
• Component is purely presentational (props in, JSX out) → @/shared/components.
• Two features need to talk → DI, never a direct import. Other feature is host → inject. This feature is host → define the extension point.
• An "aggregate" whose only public surface is a Subject / RxEvent → not an aggregate. Use createSideEffect or keep it inside the feature.

When the table doesn't answer — run event storming

If you can't pick a row, the model is ambiguous. Don't guess — run event storming with the user, then re-enter the table. Read docs/abstract/event-storming.md for the technique, the worked example, and the narrowing questions.

Trigger conditions:

• The actor, trigger, or post-state of the action is unclear.
• Two vocabularies are showing up in one description (e.g. "chain" and "staking", "message" and "catalog").
• You can't describe the user action in a single sentence using one domain's vocabulary.
• A piece of code seems to fit two layers equally well.

What to do with the result:

• New vocabulary cluster appears → it is its own domain. Extract first, depend on it second.
• Events of two flows interlock (shared trigger / command / state) → one feature.
• Events of two flows don't cross → two features. Sharing UI between them goes through DI / widget / aggregate, not a cross-feature import.

Hard "no"s

• Domain depending on aggregate / feature / widget / route. One-way only.
• Aggregate defining resources, repositories, or persistence schemas — those belong to a domain.
• Feature importing from another feature. Promote the shared piece (DI / widget / aggregate / domain) or merge the features.
• Module under a domain having its own index.ts. The domain root index.ts is the only entry point.
• Shared code referencing entities, business rules, or app state.

See also

• Going to src/domains/ → also see the domain-development skill.
• Going to src/features/ → also see the feature-development skill.
• Full decision framework (which layer / which file per layer / cut rules / binding hooks): docs/code/code-placement.md.
• Layer definitions and per-file contracts: docs/code/project-structure.md.
• How these artifacts interact at runtime: docs/code/architecture.md.