Folder structure is downstream of architectural decisions. Pick the principles first.

Principles

1. Code that changes together lives together. Tests next to components, hooks near consumers.
2. Features have explicit boundaries. Each feature exposes a public API via index.ts; everything else is private.
3. No circular dependencies between features. If A and B need each other, extract to shared/ or merge.
4. Server state lives in one place (React Query). Client state stays local.
5. The design system has no business logic. Just UI primitives.

Layout

src/
├── app/                       # app shell — entry, routing, providers
│   ├── routes.tsx
│   ├── providers.tsx          # QueryClient, ThemeProvider, AuthProvider
│   └── error-boundary.tsx
│
├── features/
│   ├── billing/
│   │   ├── api/               # React Query hooks per resource
│   │   ├── components/        # billing-specific UI
│   │   ├── hooks/             # useInvoice, useBillingForm
│   │   ├── pages/             # route components
│   │   ├── types.ts
│   │   ├── index.ts           # PUBLIC API
│   │   └── README.md          # what this feature owns
│   ├── users/
│   ├── reports/
│   └── ...
│
├── shared/
│   ├── ui/                    # design system (Button, Card, ...)
│   ├── lib/                   # utilities (formatDate, parseQuery)
│   ├── hooks/                 # cross-cutting hooks (useDebounced, useMediaQuery)
│   └── types/                 # cross-feature shared types
│
├── styles/                    # global CSS, tokens
└── main.tsx                   # entry

Public API rule

// features/billing/index.ts
export { BillingPage } from './pages/BillingPage';
export { useInvoice } from './hooks/useInvoice';
export type { Invoice } from './types';

Other features import from '@/features/billing' — never from internal paths.

Enforce with ESLint:

{
  "rules": {
    "no-restricted-imports": ["error", {
      "patterns": ["@/features/*/!(index)*"]
    }]
  }
}

Or use eslint-plugin-boundaries for richer rules.

Routing

// app/routes.tsx
const Billing = lazy(() => import('@/features/billing').then(m => ({ default: m.BillingPage })));
const Users   = lazy(() => import('@/features/users').then(m => ({ default: m.UsersPage })));

<Routes>
  <Route path="/billing/*" element={<Billing />} />
  <Route path="/users/*"   element={<Users />} />
</Routes>

Each top-level feature is a separate chunk.

Server state pattern

// features/billing/api/invoices.ts
export function useInvoices(filters: Filters) {
  return useQuery({
    queryKey: ['invoices', filters],
    queryFn: () => api.listInvoices(filters),
  });
}

Components never call fetch directly. The hook is the boundary.

Cross-cutting concerns

What goes in shared/

• Primitives: Button, Input, Dialog, Toast.
• Utilities: date, currency, string formatting.
• Hooks: useDebounced, useLocalStorage, useMediaQuery.
• Types: User, Permission, Tenant — anything that crosses features.

What does NOT go in shared/:

• Feature-specific components (InvoiceTable, UserCard).
• Business logic.
• API clients beyond a base fetch wrapper.

Monorepo vs single repo

For 5+ apps sharing UI, use a monorepo (turbo, pnpm workspaces, Nx). For one app, single repo with feature folders is plenty.

Migration path

Don't rewrite. Build the next feature in the new structure. After ~5 features, copy patterns and migrate the rest.

Anti-patterns

• Type-based folders at the top (components/, hooks/, utils/) — stops scaling around 15 pages.
• 'common/' that becomes a god folder.
• Pages importing from each other's internals.
• Mega-providers in app/ that re-render on every state change.

Senior framing

Folder structure is the visible expression of module boundaries. The structure should make accidental coupling expensive — that's its job. ESLint rules enforce the structure; without enforcement, the structure rots.