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 – Category structure and impact levels
• Rule template – Template for adding new rules
• Individual rules: references/{prefix}-{slug}.md

Related Skills

• For feature planning, see feature-spec skill
• For data fetching, see tanstack-query skill
• For React component patterns, see react-19 skill

Full Compiled Document

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