Source: https://www.hype-stack.dev/docs/frontend/organize-features

# How to Organize Features

Features are organized by domain, then split into modules. Every module lives in
`src/features/<domain>/modules/<module>/`.

## Structure

```
src/features/<domain>/
  modules/
    <module>/
      <module>.tsx        # Module component
      components/          # Sub-components used only by this module
      hooks/               # Hooks scoped to this module
  hooks/                   # Hooks shared across modules in the domain
  utils/                   # Domain helpers
  types/                   # Domain types
  constants/               # Domain constants
```

## Example: notifications domain

```
src/features/notifications/
  modules/
    notification-dropdown/
      notification-dropdown.tsx
      components/
        notification-preview.tsx
      hooks/
        use-notification-dropdown.ts
    notification-list/
      notification-list.tsx
      components/
        notification-item.tsx
        invitation-item.tsx
      hooks/
        use-notification-list.ts
  hooks/
    use-unread-count.ts
  utils/
    index.ts
```

## Rules

1. **Always nest inside `<domain>/modules/<module>/`.** Even single-file modules get their own folder.
   `src/features/settings/modules/profile-tab/profile-tab.tsx`, not `src/features/settings/profile-tab.tsx`.

2. **Pages belong in `src/routes/`.** Route files import module components. Features never contain "page" files.

3. **Hooks are scoped to where they're used:**
   - Module-level: `<module>/hooks/` when only that module uses it
   - Domain-level: `<domain>/hooks/` when shared across modules in the same domain
   - Global: `src/hooks/` when truly app-wide

4. **Sub-components go in `<module>/components/`.** Anything a module renders but doesn't export lives next to it.

5. **No flat files at the domain level.** Only shared folders like `modules/`, `hooks/`, `utils/`, `types/`,
   `constants/`.

6. **Keep module code colocated.** Components, hooks, types, queries, schemas, and tests all live inside the module
   folder they belong to. Don't move things to a global `components/` or `hooks/` just because of file kind.

## Adding a new module

1. Create the folder: `src/features/<domain>/modules/<module>/`
2. Add your component: `<module>.tsx`
3. Add `components/`, `hooks/`, types, or helpers in subfolders as needed
4. Import the component from a route file in `src/routes/`