Context and Problem Statement¶

As our React application grows in complexity, we need a scalable and maintainable folder structure. How should we organize our codebase to support better code organization, team collaboration, and feature development?

Decision Drivers¶

• Need for better separation of concerns
• Improved maintainability as the application scales
• Support for team collaboration on different features
• Clear distinction between reusable components and feature-specific components
• Reduced cognitive load when navigating the codebase

Considered Options¶

• Technical Folders (organizing by technical concern)
• Feature Folders (organizing by business domain/feature)
• Hybrid Approach (combination of both)
• Page-driven Structure

Decision Outcome¶

Chosen option: "Feature Folders", because it provides better organization around business domains, enables teams to work on features independently, and clearly separates reusable components from feature-specific ones.

Positive Consequences¶

• Teams can work on specific features without touching files across the project
• Clear separation between reusable components and feature-specific ones
• Related code (components, services, hooks) is co-located by feature
• Improved maintainability as the application grows
• Better organization for large-scale applications

Negative Consequences¶

• Potential learning curve for developers used to technical folder structures
• May require refactoring of existing code
• Could lead to some duplication if feature boundaries aren't well defined

Pros and Cons of the Options¶

Technical Folders¶

Organizing code by technical concern (components, hooks, services, etc.)

• Good, because it follows a simple and intuitive structure
• Good, because it's familiar to many React developers
• Bad, because it scatters related feature code across multiple directories
• Bad, because it becomes unwieldy as the application grows

Feature Folders¶

Organizing code by business domain/feature

• Good, because it co-locates related code by feature
• Good, because it supports team autonomy when working on specific features
• Good, because it scales well for large applications
• Bad, because it may require more thought on where to place shared components

Hybrid Approach¶

Combination of both technical and feature organization

• Good, because it allows flexibility in organization
• Good, because it can adapt to different parts of the application
• Bad, because it may lead to inconsistent organization patterns
• Bad, because it could create confusion about where to place new code

Page-driven Structure¶

Organizing by pages/routes

• Good, because it maps directly to the user's navigation experience
• Good, because it's intuitive for simple applications
• Bad, because it doesn't scale well for complex applications with shared features
• Bad, because it can lead to code duplication across pages

Implementation Details¶

Our Feature Folders structure will follow this pattern:

📦 src
┣ 📂 components               # global shared UI components
┃ ┣ 📂 App                    # main App component
┃ ┃ ┣ 📂 components
┃ ┃ ┃  ┗ 📜 App.tsx
┃ ┃ ┣ 📜 App.tsx
┃ ┃ ┣ 📜 AppRouter.tsx
┃ ┃ ┣ 📜 AppState.tsx
┃ ┃ ┗ 📜 index.tsx
┃ ┗ 📂 Layout                 # Layout component
┃   ┣ 📂 components
┃   ┃ ┣ 📂 Header             # Header component
┃   ┃ ┗ 📜 PremierTheme.tsx   # Theme
┃   ┣ 📜 index.tsx
┃   ┗ 📜 Layout.tsx           # Layout component
┣ 📂 core                     # global shared services
┣ 📂 Features                 # feature components
┣ 📂 hooks                    # global shared hooks
┣ 📂 models                   # global shared models
┣ 📂 routes                   # Page route definitions
┗ 📜 main.tsx                 # application entry point

Key principles:

1. Reusable UI components go in the shared /components folder
2. Feature-specific components go in their respective feature folders
3. Services, hooks, or contexts tightly coupled to a feature should be in that feature's folder
4. Global/shared technical concerns remain in their respective root folders

Links¶

• Reference Article