docs: add scalable application structure guidance

[ncthuc2004]

Closes #42

Adds a dedicated "Scalable Application Structure" section with:

• feature-first foldering goals
• an example feature module layout
• dependency direction rules to keep boundaries stable and pluggable

---

IssueHunt Summary

Referenced issues

This pull request has been submitted to:

• #42: [Section] Scalable Application Structure

---

[gemini-code-assist]

Code Review

This pull request introduces a new section titled "Scalable Application Structure" to the documentation, providing guidelines on feature-based file organization and dependency directions. The reviewer suggests several improvements to maintain consistency with the rest of the guide, such as including global Redux plumbing files (root-action.ts, root-epic.ts) in the directory examples, renaming types.ts to models.ts, and explicitly defining rules for cross-feature communication and selector dependencies.

[gemini-code-assist]

To maintain consistency with the rest of the guide (which references RootAction and RootEpic in the Store Configuration section), it is recommended to include these files in the app/ folder example. This clarifies where the global Redux plumbing resides.

Suggested change

	app/
	store.ts
	root-reducer.ts
	app/
	store.ts
	root-reducer.ts
	root-action.ts
	root-epic.ts

[gemini-code-assist]

The dependency direction rules mention services, but this file is missing from the example layout. Also, for consistency with existing examples in this guide (e.g., lines 1545, 1600), models.ts is preferred over types.ts for feature-specific type definitions.

Suggested change

	actions.ts
	constants.ts
	epics.ts
	reducer.ts
	selectors.ts
	types.ts
	components/
	containers/
	index.ts
	actions.ts
	constants.ts
	epics.ts
	reducer.ts
	selectors.ts
	services.ts
	models.ts
	components/
	containers/
	index.ts

[gemini-code-assist]

Adding a rule for selectors and an explicit rule for cross-feature communication would make this guide more robust. It ensures that developers know how to handle dependencies between different features while maintaining isolation.

Suggested change

	- dumb components -> feature static types
	- smart/connected components -> feature selectors + actions -> feature static types
	- reducer -> feature actions -> feature static types
	- side-effects (epics/thunks/sagas) -> feature actions + selectors + services -> feature static types
	- services -> feature static types
	- dumb components -> feature models
	- smart/connected components -> feature selectors + actions -> feature models
	- selectors -> feature models
	- reducer -> feature actions -> feature models
	- side-effects (epics/thunks/sagas) -> feature actions + selectors + services -> feature models
	- services -> feature models
	- cross-feature imports -> other feature public API (index.ts)

[gemini-code-assist]

To maintain consistency with the rest of the guide, it is recommended to include root-action.ts and root-epic.ts in the app/ folder example.

Suggested change

	app/
	store.ts
	root-reducer.ts
	app/
	store.ts
	root-reducer.ts
	root-action.ts
	root-epic.ts

[gemini-code-assist]

Including services.ts and using models.ts (for consistency with other examples) would improve the clarity of the feature module layout.

Suggested change

	actions.ts
	constants.ts
	epics.ts
	reducer.ts
	selectors.ts
	types.ts
	components/
	containers/
	index.ts
	actions.ts
	constants.ts
	epics.ts
	reducer.ts
	selectors.ts
	services.ts
	models.ts
	components/
	containers/
	index.ts

[gemini-code-assist]

Expanding the dependency rules to include selectors and cross-feature boundaries helps in building truly scalable applications.

Suggested change

	- dumb components -> feature static types
	- smart/connected components -> feature selectors + actions -> feature static types
	- reducer -> feature actions -> feature static types
	- side-effects (epics/thunks/sagas) -> feature actions + selectors + services -> feature static types
	- services -> feature static types
	- dumb components -> feature models
	- smart/connected components -> feature selectors + actions -> feature models
	- selectors -> feature models
	- reducer -> feature actions -> feature models
	- side-effects (epics/thunks/sagas) -> feature actions + selectors + services -> feature models
	- services -> feature models
	- cross-feature imports -> other feature public API (index.ts)

[ncthuc2004]

Updated based on review suggestions:\n- feature layout now uses models.ts + includes services.ts\n- dependency direction now explicitly includes selectors and cross-feature public API rules\n- app folder example includes root action/epic files for consistency\n\nPushed in latest commit on issuehunt-42-scalable-application-structure.