File and folder structure follows framework conventions

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.

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.

• ID: code-maintainability.code-organization.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.