architecture-vertical-slices

title: Organize Code by Domain Using Vertical Slices
impact: CRITICAL
impactDescription: Dramatically improves discoverability and reduces cross-team conflicts
tags: architecture, vertical-slices, ddd, organization

Organize Code by Domain Using Vertical Slices

**Impact: CRITICAL**

Our codebase is organized by domain, not by technical layer. The `packages/features` directory is the heart of this architectural approach. Each folder inside represents a complete vertical slice of the application, driven by the domain it touches.

**Incorrect (traditional layered architecture):**

src/
  controllers/
    bookingController.ts
    availabilityController.ts
  services/
    bookingService.ts
    availabilityService.ts
  repositories/
    bookingRepository.ts
    availabilityRepository.ts

This creates problems: changes to one feature require touching files scattered across multiple directories, it's hard to understand what a feature does because its code is fragmented, and teams step on each other's toes.

**Correct (vertical slice architecture):**

packages/features/
  bookings/
    services/
    repositories/
    components/
    tests/
  availability/
    services/
    repositories/
    components/
    tests/

Each feature folder is a self-contained vertical slice that includes:

• Domain logic: Core business rules and entities specific to that feature
• Application services: Use case orchestration for that domain
• Repositories: Data access specific to that feature's needs
• DTOs: Data transfer objects for crossing boundaries
• UI components: Frontend components related to this feature
• Tests: Unit, integration, and e2e tests for this feature

**Benefits:**

• Everything related to a feature lives in one directory
• You can understand the entire feature by exploring one directory
• Teams can work on different features without conflicts
• Features are loosely coupled and can evolve independently

Reference: [Cal.diy Engineering Blog](https://cal.com/blog/engineering-in-2026-and-beyond)