The Vertical Codebase
17 hours ago
- #software-architecture
- #developer-experience
- #codebase-structure
- The author argues against horizontal codebase structures that group by type (components, hooks, types, utils) because it separates related code by domain, making navigation and maintenance difficult as the codebase grows.
- Horizontal structures increase cognitive load and reduce cohesion, as code that changes together doesn't live together, leading to poor scalability and discoverability issues, exemplified by Sentry's codebase with over 200 files in a top-level components directory.
- The proposed alternative is a vertical structure, where code is grouped by domain or feature (e.g., src/widgets/) rather than technical type, aligning with team ownership and logical groupings to improve cohesion and reduce unnecessary coupling.
- Vertical grouping requires thoughtful organization, often tied to routes or pages, and may involve creating separate verticals for shared components like PageFilters, with clear public interfaces to manage dependencies and enforce boundaries.
- Implementing vertical structures can involve tools like monorepos with pnpm workspaces, eslint-plugin-boundaries, or Nx to enforce dependencies and define public interfaces, though it requires more communication and effort to avoid duplication and ensure correct grouping.