Folder Structure

Overview

Folder structure helps teams navigate code and understand ownership.

Why It Matters

Poor structure hides relationships and makes change slower than it should be.

Core Concepts

• Structure should reflect behavior and ownership.
• Keep related code close.
• Avoid a folder tree that only one person can explain.

Mental Models

The best structure reduces search time and clarifies which code changes together.

Best Practices

• Group by feature when it helps cohesion.
• Keep shared utilities limited and obvious.
• Revisit structure when the codebase grows.

Common Mistakes

• Organizing only by file type.
• Creating “misc” or “utils” dumping grounds.
• Moving files more often than the design changes.

Trade-offs

Feature-first structure improves locality, while layer-first structure can be better for highly shared systems.

Decision Framework

Examples

• features/settings/
• components/ui/
• lib/api/

Checklists

• Can someone find the code quickly?
• Does the structure match the product?
• Are shared utilities truly shared?

Senior Engineer Notes

Senior engineers treat structure as communication. The folder tree should answer “where does this belong?” without a meeting.

Further Reading

• Feature Architecture
• Component Architecture
• Clean Architecture