React Feature Module Architecture Guidelines

Architectural Principles

1. •All features modules should be create in modules repo
2. •Colocation: Code that changes together stays together. Assets, styles, tests, and components related to a specific feature reside within that feature's module.
3. •Encapsulation: Feature modules are "black boxes". They expose a strict public API (via index.ts) and hide internal implementation details. Other modules must not import from inside a module's private folders.
4. •Unidirectional Data Flow: Data flows down (Props), Events flow up (Callbacks). Side effects and state management are lifted to the integration layer (Containers).
5. •Separation of Concerns:
   • •Presentational Layer (Components): Pure UI, styling, and interaction. No business logic.
   • •Integration Layer (Containers/Pages): Connects UI to Data/Logic.
   • •Domain Layer (Hooks/Utils): Reusable business logic and data transformations.
   • •Data Layer (API/Store): Server state synchronization and client state management.

Feature Module Classification

Module Splitting Criteria

Choose module boundaries based on these principles (in order of priority):

1. •

   Domain/Business Boundaries (DDD)

   • •Independent business logic domains (e.g., checkout, identity, inventory).
   • •distinct data models and API requirements.
2. •

   Design Boundaries (Figma)

   • •Separate modules for distinct design sections/flows.
   • •Maintain design-code alignment.
3. •

   Route-Level Separation

   • •Each major route group = separate module.
   • •Constraint: Route-based modules should map to Domain boundaries where possible.

Module Granularity Guidelines

✅ Good Module Examples:

• •user-profile - User identity and preferences.
• •product-catalog - Browsing and filtering products.
• •order-processing - Checkout and payment flows.
• •analytics-dashboard - Data visualization domain.

❌ Avoid Over-nesting:

❌ dashboard/
   ├── analytics/
   ├── settings/
   └── user/

✅ Better Approach (Flat & Domain-Focused):

✅ analytics-dashboard/
✅ settings-manager/
✅ user-management/

Naming Conventions

Files

• •Components: kebab-case - user-card.tsx
• •Modules: kebab-case - user-profile/
• •Constants: kebab-case - api-endpoints.ts
• •Pages: kebab-case + -page suffix - profile-page.tsx
• •Containers: kebab-case + -container suffix - profile-details-container.tsx
• •Form Items: kebab-case + .form - address-input.form.tsx
• •Schemas: kebab-case + .schema - user-validation.schema.ts
• •Hooks: kebab-case with use prefix - use-permissions.ts
• •Utils: kebab-case - currency-formatter.ts
• •Context: kebab-case + -context suffix - auth-context.tsx
• •Store: kebab-case + .{suffix} - cart.store.ts (suffix: atom, store, slice)
• •Types: kebab-case + .types - user-profile.types.ts
• •Services/API: kebab-case + .service or .api - auth.service.ts

Folders

• •All folders use kebab-case.

Module Internal Structure

Each feature module must adhere to this structure. Empty folders should be omitted.

feature-module/
├── api/                # API definitions and mutation hooks (Data Layer)
├── assets/             # Module-specific static assets
├── components/         # Pure UI components (Presentational Layer)
│   └── form-items/     # Form-specific UI inputs
├── containers/         # Smart components connecting Data to UI (Integration Layer)
├── contexts/           # Module-level state (Dependency Injection)
├── hooks/              # Business logic extracted from components
├── pages/              # Route entry points (Lazy Load Boundaries)
├── stores/             # Complex state management (Global/Cross-component)
├── types/              # Domain interfaces and types
├── utils/              # Pure functions and transformations
└── index.ts            # PUBLIC INTERFACE (Exports only what other modules need)

Layer Guidelines

1. Data Layer (api/, stores/)

• •API:
  • •Define clear request/response schemas (Zod/Valibot recommended).
  • •Use explicit cache keys for Query/SWR (e.g., ['user', 'details', id]).
  • •Rule: Never export raw fetcher functions; export typed hooks or service objects.
  • •Handle data normalization here, not in the view.
• •Stores:
  • •Use for cross-component communication within the module.
  • •Use for high-frequency updates where React Context causes excessive re-renders.

2. Domain Layer (hooks/, utils/, types/, contexts/)

• •Hooks:
  • •Encapsulate stateful logic and side effects.
  • •Must be agnostic of the UI rendering.
• •Utils:
  • •Strict Rule: Pure synchronous functions only. No async usage.
  • •Must have 100% test coverage.
  • •Complex data transformations belong here.
• •Contexts:
  • •Dependency injection for the module.
  • •Avoid for high-frequency updates (use Store).
  • •No complex logic in Providers; delegate to hooks.

3. Integration Layer (containers/, pages/)

• •Pages:
  • •Entry point for the Router.
  • •Responsibilities: Reading URL parameters, SEO metadata, defining Layout structure.
  • •Restriction: No complex business logic. Delegate immediately to Containers.
• •Containers:
  • •Responsibilities: Fetching data, handling loading/error states, dispatching actions.
  • •Restriction: Minimal styling (layout only). No presentation logic (render HTML structure).
  • •Compose components to build the view.

4. Presentational Layer (components/)

• •Responsibilities: Rendering UI based on props.
• •Restriction: strict props-down, events-up flow.
• •State: Only ephemeral UI state (e.g., isHovered, isOpen). All data state comes from props.
• •Dependencies: Should not depend on stores or api directly.
• •Documentation: Complex components require Storybook stories.

Common Module (Shared Kernel)

The common module is a special project-level module for generic, domain-agnostic resources.

✅ Allowed in Common:

• •Design System primitives (Buttons, Inputs).
• •Generic hooks (useOnClickOutside, useMediaQuery).
• •Date/String formatting utilities.
• •Global types (ApiResponse<T>, UserRole).

❌ Forbidden in Common:

• •Business logic (e.g., calculateTax - belongs in billing module).
• •Domain components (e.g., UserCard - belongs in user module).

Cross-Module Communication

1. •Strict Boundary: Modules cannot import deep files from other modules.
   • •❌ import { InternalComp } from '../other-module/components/InternalComp'
   • •✅ import { PublicContainer } from '../other-module' (via index.ts)
2. •Data Sharing:
   • •URL: Prefer sharing state via URL parameters (Single Source of Truth).
   • •Global Store: For persistent session data (Auth, Theme).
   • •Events: For loose coupling (rarely needed in React, prefer State lifting).

Code Quality & Testing Standards

• •Testing:
  • •Utils: Unit tests (Jest/Vitest).
  • •Hooks: renderHook testing.
  • •Containers/Page: Integration tests (React Testing Library) mocking network requests.
  • •Components: Visual regression or interaction tests (Storybook/Playwright) if complex.
• •Performance:
  • •Enforce strict dependency arrays in hooks.
  • •Use React.memo or fine-grained signals only when profiling indicates need.
  • •Lazy load all Route components (Pages).