1. Top-Level Structure
react-app/
├── app/
├── shared/
├── assets/
└── features/
Folder
Purpose
app/
App bootstrapping — layout, root component, routing
shared/
Reusable code shared across features (components, utils, api, services)
assets/
Static assets — fonts, images, icons, etc.
features/
Feature-based modules (domain-driven slices of the app)
2. app/ — App Shell
app/
├── layout/
├── App.jsx (or App.tsx)
└── routers/
Item
Purpose
layout/
App-level layout components (Navbar, Sidebar, Footer, page shells)
App.jsx / App.tsx
Root component — wires up providers, layout, and routing
routers/
Route definitions / route config (e.g. React Router setup)
3. shared/ — Cross-Feature Reusables
shared/
├── components/
├── utils/
├── api/
└── services/
Item
Purpose
components/
Shared/reusable UI components used across multiple features (buttons, modals, inputs)
utils/
Generic helper functions (formatters, validators, constants)
api/
Shared/base API layer (axios instance, base API config, interceptors)
services/
Shared business logic used across features
4. assets/ — Static Files
assets/
├── fonts/
├── images/
└── ...
Item
Purpose
fonts/
Custom font files
images/
Images, icons, illustrations
...
Other static asset types as needed (svgs, videos, etc.)
5. features/ — Feature Modules
Each feature is self-contained and organized by domain (e.g. user, order).
features/
├── user/
│ ├── components/
│ ├── hooks/
│ ├── api/
│ ├── pages/
│ ├── services/
│ └── README.md (if needed)
└── order/
├── components/
├── hooks/
├── api/
├── pages/
├── services/
└── README.md (if needed)
Item
Purpose
components/
UI components specific to this feature — render only, no business logic
hooks/
Custom hooks specific to this feature
api/
API calls for this feature — handles API requests only
pages/
Page-level components for this feature (route targets)
services/
Business logic for this feature
README.md
Optional notes/docs specific to the feature (when complexity warrants it)
6. Layer Responsibility Rules (Important)
These rules apply both in shared/ and inside each features/* module:
Layer
Responsibility
Must NOT do
components/
Render UI only
❌ No business logic
api/
Handle API calls only (requests/responses)
❌ No business logic
services/
Contains all business logic
—
Rule of thumb: components → calls services → services use api Business logic always lives in the service layer, never in components or the api layer.
7. Full Tree (Reference)
react-app/
├── app/
│ ├── layout/
│ ├── App.jsx
│ └── routers/
│
├── shared/
│ ├── components/
│ ├── utils/
│ ├── api/
│ └── services/
│
├── assets/
│ ├── fonts/
│ └── images/
│
└── features/
├── user/
│ ├── components/
│ ├── hooks/
│ ├── api/
│ ├── pages/
│ ├── services/
│ └── README.md
│
└── order/
├── components/
├── hooks/
├── api/
├── pages/
├── services/
└── README.md