Feature-Based Architecture Best Practices

Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 42 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions).

When to Apply

Reference these guidelines when:

• Creating new features or modules
• Organizing project directory structure
• Setting up import rules and boundaries
• Implementing data fetching patterns
• Composing components from multiple features
• Reviewing code for architecture violations

Rule Categories by Priority

Quick Reference

1. Directory Structure (CRITICAL)

• struct-feature-folders - Organize by feature, not technical type
• struct-feature-self-contained - Make features self-contained
• struct-shared-layer - Use shared layer for truly generic code only
• struct-flat-hierarchy - Keep directory hierarchy flat
• struct-optional-segments - Include only necessary segments
• struct-app-layer - Separate app layer from features

2. Import & Dependencies (CRITICAL)

• import-unidirectional-flow - Enforce unidirectional import flow
• import-no-cross-feature - Prohibit cross-feature imports
• import-public-api - Export through public API only
• import-avoid-barrel-files - Avoid deep barrel file re-exports
• import-path-aliases - Use consistent path aliases
• import-type-only - Use type-only imports for types

3. Module Boundaries (HIGH)

• bound-feature-isolation - Enforce feature isolation
• bound-interface-contracts - Define explicit interface contracts
• bound-feature-scoped-routing - Scope routing to feature concerns
• bound-minimize-shared-state - Minimize shared state between features
• bound-event-based-communication - Use events for cross-feature communication
• bound-feature-size - Keep features appropriately sized

4. Data Fetching (HIGH)

• fquery-single-responsibility - Keep query functions single-purpose
• fquery-colocate-with-feature - Colocate data fetching with features
• fquery-parallel-fetching - Fetch independent data in parallel
• fquery-avoid-n-plus-one - Avoid N+1 query patterns
• fquery-feature-scoped-keys - Use feature-scoped query keys
• fquery-server-component-fetching - Fetch at server component level

5. Component Organization (MEDIUM-HIGH)

• fcomp-single-responsibility - Apply single responsibility to components
• fcomp-composition-over-props - Prefer composition over prop drilling
• fcomp-container-presentational - Separate container and presentational concerns
• fcomp-props-as-data-boundary - Use props as feature boundaries
• fcomp-colocate-styles - Colocate styles with components
• fcomp-error-boundaries - Use feature-level error boundaries

6. State Management (MEDIUM)

• fstate-feature-scoped-stores - Scope state stores to features
• fstate-server-state-separation - Separate server state from client state
• fstate-lift-minimally - Lift state only as high as necessary
• fstate-context-sparingly - Use context sparingly for feature state
• fstate-reset-on-unmount - Reset feature state on unmount

7. Testing Strategy (MEDIUM)

• test-colocate-with-feature - Colocate tests with features
• test-feature-isolation - Test features in isolation
• test-shared-utilities - Create feature-specific test utilities
• test-integration-at-app-layer - Write integration tests at app layer

8. Naming Conventions (LOW)

• name-feature-naming - Use domain-driven feature names
• name-file-conventions - Use consistent file naming conventions
• name-descriptive-exports - Use descriptive export names

How to Use

Read individual reference files for detailed explanations and code examples:

• [Section definitions](references/_sections.md) - Category structure and impact levels
• Individual rules: references/{prefix}-{slug}.md

Related Skills

• For data fetching, see tanstack-query skill
• For React component patterns, see react skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md