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
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Directory Structure | CRITICAL | struct- |
| 2 | Import & Dependencies | CRITICAL | import- |
| 3 | Module Boundaries | HIGH | bound- |
| 4 | Data Fetching | HIGH | fquery- |
| 5 | Component Organization | MEDIUM-HIGH | fcomp- |
| 6 | State Management | MEDIUM | fstate- |
| 7 | Testing Strategy | MEDIUM | test- |
| 8 | Naming Conventions | LOW | name- |
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-specskill - •For data fetching, see
tanstack-queryskill - •For React component patterns, see
react-19skill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md