# File and folder structure follows framework conventions

- **Pattern:** `ab-000663` (`code-maintainability.code-organization.file-folder-structure`)
- **Severity:** critical
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000663
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000663)

## Why it matters

Misorganized directory structure forces every contributor to build a mental map from scratch. When components live in the root, API logic lives inside component files, and the `src/` wrapper is applied inconsistently, adding a feature means hunting across the entire tree. ISO 25010 maintainability.analysability degrades directly: the time to locate where a change belongs rises sharply. New contributors — or future you — lose hours before writing a single line. Framework conventions exist precisely to make projects predictable.

## Severity rationale

Critical because a fractured directory structure makes every subsequent change slower and riskier, compounding across the entire development lifecycle.

## Remediation

Adopt your framework's conventional layout and migrate incrementally — one directory at a time, verifying the build passes after each move. For Next.js App Router:

```
src/
  app/          ← routes and page components
  components/   ← shared UI components
  lib/          ← utilities, helpers, third-party wrappers
  hooks/        ← custom React hooks
  types/        ← TypeScript type definitions
```

Use your IDE's "Move file" refactor to update imports automatically. Commit each directory move separately so the diff stays reviewable.

## Detection

- **ID:** `file-folder-structure`
- **Severity:** `critical`
- **What to look for:** Examine the top-level directory structure and compare against the detected framework's conventions. For Next.js: check that pages/routes are in `app/` or `pages/`, shared components in `components/`, utilities in `lib/` or `utils/`, types in `types/`. For Express/Fastify: check for `routes/`, `controllers/`, `middleware/`, `models/` or similar separation. Look for files placed in clearly wrong locations (e.g., React components scattered in the root, API logic inside component files, unrelated files in `public/`). Count how many top-level directories exist and whether their naming is purposeful. Also check whether the `src/` wrapper is used consistently — either all source in `src/` or none, not mixed.
- **Pass criteria:** Count all top-level directories in the project. The project directory structure matches the detected framework's conventional layout. Source files are organized into at least 3 purposeful directories with consistent naming. No obviously misplaced files (e.g., business logic in `public/`, components in the root). Report the count even on pass: "X of Y top-level directories follow framework conventions." Before evaluating, extract and quote the first directory name you find that follows or violates the convention.
- **Fail criteria:** Three or more of the following are true: framework-conventional directories are absent, source files are scattered at the root level, the `src/` wrapper is used inconsistently, directories have ambiguous or generic names (`stuff/`, `misc/`, `temp/`), or files are in clearly wrong locations for their content type. Do NOT pass when directories exist but contain misplaced files (e.g., a `components/` directory full of API logic).
- **Skip (N/A) when:** The project is a single-file script or CLI tool with no directory structure to evaluate. Signal: `package.json` has a `bin` field and fewer than 5 source files total.
- **Cross-reference:** For import path consistency related to directory structure, see the import-organization check in this audit.
- **Detail on fail:** Describe which conventions are violated and where. Example: `"Components scattered across root, pages/, and src/ with no consistent pattern. No lib/ or utils/ directory — helper functions mixed into component files."`
- **Remediation:** A consistent directory structure is the first thing any new contributor (or your future self) looks for. Misorganized projects cost time every time someone needs to find or add code.

  Start by deciding on the structure for your framework. For Next.js App Router:
  ```
  src/
    app/          ← routes and page components
    components/   ← shared UI components
    lib/          ← utilities, helpers, third-party wrappers
    hooks/        ← custom React hooks
    types/        ← TypeScript type definitions
    styles/       ← global styles (if not in app/)
  ```

  Reorganize files incrementally — move one directory at a time, update imports, verify the build passes after each move. Your IDE's "Move file" refactor can update imports automatically.

## External references

- iso-25010 maintainability.analysability
- iso-25010 maintainability.modularity

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000663