Feature-Based Folder Structure

src/
├── components/
│   ├── LoginForm.tsx
│   ├── SignupForm.tsx
│   ├── Dashboard.tsx
│   ├── DashboardStats.tsx
│   ├── DashboardChart.tsx
│   ├── UserProfile.tsx
│   ├── UserAvatar.tsx
│   ├── CartItem.tsx
│   ├── CartSummary.tsx
│   ├── ProductCard.tsx
│   ├── ProductList.tsx
│   ├── SearchBar.tsx
│   ├── SearchResults.tsx
│   ├── Header.tsx
│   ├── Sidebar.tsx
│   └── ... (200+ more components)
├── hooks/
│   ├── useAuth.ts
│   ├── useDashboard.ts
│   ├── useCart.ts
│   ├── useSearch.ts
│   └── ... (50+ more hooks)
├── services/
│   ├── authService.ts
│   ├── dashboardService.ts
│   ├── cartService.ts
│   └── ... (30+ more services)
├── utils/
│   ├── authUtils.ts
│   ├── formatters.ts
│   └── validators.ts
├── types/
│   ├── auth.ts
│   ├── dashboard.ts
│   ├── cart.ts
│   └── ... (20+ more type files)
└── styles/
    ├── login.css
    ├── dashboard.css
    └── ... (40+ more stylesheets)

Task: "Fix a bug in the search feature"

With type-based structure, a developer must:
  1. Open components/ → find SearchBar.tsx, SearchResults.tsx
  2. Open hooks/ → find useSearch.ts
  3. Open services/ → find searchService.ts
  4. Open types/ → find search.ts
  5. Open utils/ → find searchUtils.ts (if it exists)
  6. Open styles/ → find search.css (if it exists)
  7. Figure out which other components import from search

  → 6+ directories, constant context-switching

Task: "Delete the search feature"

  → Hunt through every directory, hope you found everything,
     pray nothing else depends on searchUtils.ts

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   ├── SignupForm.tsx
│   │   │   └── AuthGuard.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── services/
│   │   │   └── authService.ts
│   │   ├── types/
│   │   │   └── auth.types.ts
│   │   └── index.ts              ← public API (barrel export)
│   │
│   ├── dashboard/
│   │   ├── components/
│   │   │   ├── Dashboard.tsx
│   │   │   ├── StatsCard.tsx
│   │   │   └── Chart.tsx
│   │   ├── hooks/
│   │   │   └── useDashboardData.ts
│   │   ├── services/
│   │   │   └── dashboardService.ts
│   │   └── index.ts
│   │
│   └── cart/
│       ├── components/
│       │   ├── CartItem.tsx
│       │   └── CartSummary.tsx
│       ├── hooks/
│       │   └── useCart.ts
│       ├── services/
│       │   └── cartService.ts
│       └── index.ts
│
├── shared/                        ← truly shared code
│   ├── components/
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Modal.tsx
│   ├── hooks/
│   │   └── useDebounce.ts
│   └── utils/
│       └── formatDate.ts
│
├── app/                           ← routing / pages
│   ├── layout.tsx
│   └── page.tsx
└── styles/
    └── globals.css

src/
├── components/          ← 150+ files, all mixed together
│   ├── LoginForm.tsx
│   ├── ProductCard.tsx
│   ├── CartItem.tsx
│   ├── CheckoutForm.tsx
│   ├── OrderSummary.tsx
│   ├── SearchBar.tsx
│   ├── UserProfile.tsx
│   ├── ReviewCard.tsx
│   └── ... (142 more)
├── hooks/               ← 40+ hooks, no grouping
│   ├── useAuth.ts
│   ├── useProducts.ts
│   ├── useCart.ts
│   ├── useCheckout.ts
│   ├── useSearch.ts
│   └── ... (35 more)
├── services/            ← 20+ services
│   ├── authService.ts
│   ├── productService.ts
│   ├── cartService.ts
│   └── ... (17 more)
├── types/               ← 25+ type files
└── utils/               ← 15+ utility files

Problems:
  • "Where is the checkout code?" → scattered across 5 directories
  • "Who owns components/?" → everyone (nobody)
  • "Can I safely delete ReviewCard?" → check every import in 150 files
  • Adding a feature = editing 5+ directories

src/
├── features/
│   ├── auth/
│   │   ├── LoginForm.tsx
│   │   ├── SignupForm.tsx
│   │   ├── useAuth.ts
│   │   ├── authService.ts
│   │   ├── auth.types.ts
│   │   └── index.ts
│   │
│   ├── products/
│   │   ├── ProductCard.tsx
│   │   ├── ProductList.tsx
│   │   ├── ProductDetail.tsx
│   │   ├── useProducts.ts
│   │   ├── productService.ts
│   │   ├── product.types.ts
│   │   └── index.ts
│   │
│   ├── cart/
│   │   ├── CartItem.tsx
│   │   ├── CartSummary.tsx
│   │   ├── useCart.ts
│   │   ├── cartService.ts
│   │   ├── cart.types.ts
│   │   └── index.ts
│   │
│   ├── checkout/
│   │   ├── CheckoutForm.tsx
│   │   ├── PaymentStep.tsx
│   │   ├── OrderSummary.tsx
│   │   ├── useCheckout.ts
│   │   ├── checkoutService.ts
│   │   └── index.ts
│   │
│   ├── search/
│   │   ├── SearchBar.tsx
│   │   ├── SearchResults.tsx
│   │   ├── useSearch.ts
│   │   ├── searchService.ts
│   │   └── index.ts
│   │
│   └── reviews/
│       ├── ReviewCard.tsx
│       ├── ReviewForm.tsx
│       ├── useReviews.ts
│       └── index.ts
│
├── shared/
│   ├── ui/              ← reusable primitives
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   ├── Modal.tsx
│   │   └── Spinner.tsx
│   ├── hooks/
│   │   ├── useDebounce.ts
│   │   └── useLocalStorage.ts
│   └── utils/
│       ├── formatCurrency.ts
│       └── formatDate.ts
│
└── app/                 ← routing layer
    ├── layout.tsx
    ├── page.tsx
    └── (routes)/

Benefits:
  • "Where is the checkout code?" → features/checkout/
  • "Who owns cart?" → the cart team
  • "Can I delete reviews?" → delete features/reviews/, done
  • Adding a feature = adding one folder

// features/auth/index.ts — the public API
// Only export what other features need

export { LoginForm } from "./LoginForm";
export { SignupForm } from "./SignupForm";
export { AuthGuard } from "./AuthGuard";
export { useAuth } from "./useAuth";
export type { User, AuthState } from "./auth.types";

// Internal implementation details are NOT exported:
// - authService.ts (used only by useAuth internally)
// - authUtils.ts (helper functions, not needed externally)
// - AuthContext.tsx (internal context provider)

// Other features import from the barrel:
// import { useAuth, LoginForm } from "@/features/auth";
// They never reach into internal files.

A feature is a cohesive domain area that:

  ✅ Has its own UI (one or more pages/components)
  ✅ Has its own data/state (API calls, local state)
  ✅ Can be described in 1-2 words (auth, cart, search)
  ✅ Could theoretically be developed by one team
  ✅ Has clear boundaries (you know what's "in" and "out")

Good features:                    Bad features:
  ├── auth/                         ├── buttons/        (too granular)
  ├── dashboard/                    ├── api/            (technical layer)
  ├── cart/                         ├── data/           (too vague)
  ├── checkout/                     ├── misc/           (catch-all)
  ├── search/                       ├── helpers/        (technical layer)
  ├── user-profile/                 └── new-stuff/      (meaningless)
  ├── notifications/
  ├── settings/
  └── analytics/

E-commerce App:
  features/
  ├── auth/           → login, signup, password reset, session management
  ├── products/       → product listing, detail, filtering, sorting
  ├── cart/           → add to cart, update quantity, remove, cart summary
  ├── checkout/       → shipping, payment, order confirmation
  ├── orders/         → order history, order detail, tracking
  ├── reviews/        → write review, view reviews, ratings
  ├── search/         → search bar, results, filters, suggestions
  ├── user-profile/   → profile view, edit profile, avatar
  └── notifications/  → notification list, preferences, real-time updates

SaaS Dashboard:
  features/
  ├── auth/           → login, SSO, team invites
  ├── dashboard/      → overview stats, charts, recent activity
  ├── projects/       → project list, create, settings
  ├── editor/         → document editor, toolbar, collaboration
  ├── billing/        → plans, payment methods, invoices
  ├── settings/       → account settings, team management
  └── analytics/      → usage charts, export, date range picker

Is this code used by MORE THAN ONE feature?
  │
  ├─ NO → Put it in the feature folder
  │       features/cart/CartItem.tsx
  │       features/cart/useCart.ts
  │       features/cart/cartService.ts
  │
  └─ YES → Put it in shared/
           shared/ui/Button.tsx        (used by every feature)
           shared/hooks/useDebounce.ts (used by search + autocomplete)
           shared/utils/formatDate.ts  (used everywhere)

Important: Start in the feature folder. Move to shared ONLY when
a second feature needs it. Don't pre-optimize.

  ❌ "This hook MIGHT be useful elsewhere" → put in shared/
  ✅ "This hook IS used by auth and cart" → move to shared/

shared/
├── ui/                    ← design system primitives
│   ├── Button.tsx
│   ├── Input.tsx
│   ├── Modal.tsx
│   ├── Spinner.tsx
│   ├── Badge.tsx
│   └── index.ts
│
├── hooks/                 ← generic utility hooks
│   ├── useDebounce.ts
│   ├── useLocalStorage.ts
│   ├── useMediaQuery.ts
│   └── index.ts
│
├── utils/                 ← pure utility functions
│   ├── formatDate.ts
│   ├── formatCurrency.ts
│   ├── cn.ts              (className merger)
│   └── index.ts
│
├── services/              ← shared infrastructure
│   ├── apiClient.ts       (base fetch/axios wrapper)
│   └── analytics.ts       (tracking service)
│
├── types/                 ← shared type definitions
│   └── common.types.ts
│
└── constants/
    └── routes.ts

Rules for shared/:
  • No business logic — only generic utilities
  • No feature-specific code
  • Should be stable — changes here affect every feature
  • Could theoretically be extracted into an npm package

src/
├── app/                           ← Next.js routing layer
│   ├── layout.tsx
│   ├── page.tsx                   → redirects to /dashboard
│   ├── login/
│   │   └── page.tsx               → renders <LoginForm />
│   ├── dashboard/
│   │   └── page.tsx               → renders <Dashboard />
│   ├── projects/
│   │   ├── page.tsx               → renders <ProjectList />
│   │   └── [id]/
│   │       └── page.tsx           → renders <ProjectDetail />
│   └── settings/
│       └── page.tsx               → renders <Settings />
│
├── features/
│   ├── auth/
│   │   ├── LoginForm.tsx
│   │   ├── useAuth.ts
│   │   ├── AuthProvider.tsx
│   │   ├── authService.ts
│   │   ├── auth.types.ts
│   │   └── index.ts
│   │
│   ├── dashboard/
│   │   ├── Dashboard.tsx          ← composes child components
│   │   ├── StatsGrid.tsx
│   │   ├── ActivityFeed.tsx
│   │   ├── QuickActions.tsx
│   │   ├── useDashboardData.ts
│   │   ├── dashboardService.ts
│   │   └── index.ts
│   │
│   ├── projects/
│   │   ├── ProjectList.tsx
│   │   ├── ProjectCard.tsx
│   │   ├── ProjectDetail.tsx
│   │   ├── CreateProjectModal.tsx
│   │   ├── useProjects.ts
│   │   ├── projectService.ts
│   │   ├── project.types.ts
│   │   └── index.ts
│   │
│   ├── analytics/
│   │   ├── AnalyticsChart.tsx
│   │   ├── DateRangePicker.tsx
│   │   ├── MetricCard.tsx
│   │   ├── useAnalytics.ts
│   │   ├── analyticsService.ts
│   │   └── index.ts
│   │
│   └── settings/
│       ├── Settings.tsx
│       ├── ProfileSection.tsx
│       ├── TeamSection.tsx
│       ├── BillingSection.tsx
│       ├── useSettings.ts
│       ├── settingsService.ts
│       └── index.ts
│
├── shared/
│   ├── ui/
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Modal.tsx
│   │   ├── Table.tsx
│   │   └── index.ts
│   ├── hooks/
│   │   ├── useDebounce.ts
│   │   └── useMediaQuery.ts
│   ├── utils/
│   │   ├── formatDate.ts
│   │   └── cn.ts
│   └── services/
│       └── apiClient.ts
│
└── styles/
    └── globals.css

// app/dashboard/page.tsx — thin routing layer
// The page just imports and renders the feature component

import { Dashboard } from "@/features/dashboard";
import { AuthGuard } from "@/features/auth";

export default function DashboardPage() {
  return (
    <AuthGuard>
      <Dashboard />
    </AuthGuard>
  );
}

// features/dashboard/Dashboard.tsx — the actual feature
import { StatsGrid } from "./StatsGrid";
import { ActivityFeed } from "./ActivityFeed";
import { QuickActions } from "./QuickActions";
import { useDashboardData } from "./useDashboardData";

export function Dashboard() {
  const { stats, activity, isLoading } = useDashboardData();

  if (isLoading) return <Spinner />;

  return (
    <div>
      <StatsGrid stats={stats} />
      <div className="grid grid-cols-2 gap-6">
        <ActivityFeed items={activity} />
        <QuickActions />
      </div>
    </div>
  );
}

// Key insight: the page (routing layer) is thin.
// The feature (Dashboard) owns all the logic and UI.
// Pages compose features. Features compose components.

── Stage 1: Small App (5-15 files) ────────────────

  src/
  ├── components/
  │   ├── LoginForm.tsx
  │   ├── Dashboard.tsx
  │   └── Header.tsx
  ├── hooks/
  │   └── useAuth.ts
  └── app/
      └── page.tsx

  At this size, type-based is fine. Don't over-engineer.

── Stage 2: Growing App (30-80 files) ─────────────

  src/
  ├── features/
  │   ├── auth/
  │   │   ├── LoginForm.tsx
  │   │   ├── useAuth.ts
  │   │   └── index.ts
  │   └── dashboard/
  │       ├── Dashboard.tsx
  │       ├── StatsCard.tsx
  │       └── index.ts
  ├── shared/
  │   └── ui/
  │       └── Button.tsx
  └── app/

  Features emerge naturally. Migrate incrementally.

── Stage 3: Large App (200+ files) ────────────────

  src/
  ├── features/
  │   ├── auth/
  │   │   ├── components/
  │   │   │   ├── LoginForm.tsx
  │   │   │   └── SignupForm.tsx
  │   │   ├── hooks/
  │   │   │   └── useAuth.ts
  │   │   ├── services/
  │   │   │   └── authService.ts
  │   │   ├── __tests__/
  │   │   │   └── useAuth.test.ts
  │   │   └── index.ts
  │   └── ... (10+ features)
  ├── shared/
  └── app/

  Features get sub-directories when they grow beyond 8-10 files.

── Stage 4: Monorepo (500+ files, multiple teams) ─

  packages/
  ├── features/
  │   ├── auth/           → separate package
  │   ├── dashboard/      → separate package
  │   └── cart/           → separate package
  ├── shared-ui/          → design system package
  └── app/                → shell that composes features

  Each feature becomes an independent package with its own
  package.json, tests, and build. Teams deploy independently.