Vertical Slice Architecture for Web Apps

Explore vertical slice architecture, a practical approach that simplifies codebases, speeds feature delivery, and makes web apps easier to maintain.

Introduction

Vertical slice architecture organizes code by business feature rather than by technical layer. Each feature—like “Create User” or “Submit Order”—contains its UI, API endpoint, business logic, and data access in one place. That reduces context switching, lowers integration bugs, and helps teams deliver value faster.

Why layered architectures slow teams down

Many teams still use layered architectures: presentation, business logic, and data access. While clear in theory, this layout often scatters a single feature’s code across multiple directories. That scattering increases cognitive load and makes small changes risky. A single UI tweak can require edits in several unrelated places, which creates fragile dependencies and slows delivery¹.

The ripple effect of changes

Developers end up bouncing between parts of the codebase to complete one task. This increases the chance of regressions and lengthens development cycles. The common consequences include:

• Slower feature delivery because engineers spend more time locating code than delivering value.
• Higher bug rates when small changes trigger failures elsewhere.
• Harder onboarding since new hires must learn many layers before contributing.
• Weaker AI assistance because scattered context limits helpful suggestions.

For a comparison of architecture patterns, see our guide on software architecture patterns.

What is vertical slice architecture?

Vertical slice architecture flips the mental model from horizontal concerns to vertical, business-focused slices. Picture an app as a pizza: each slice contains everything needed to support one end-to-end feature—UI components, API handlers, business logic, and data access.

This grouping improves feature cohesion and developer experience. When all code for a feature lives together, teams find, change, and test functionality faster. A single directory can contain everything needed to understand and modify a feature, reducing context switching and mental overhead.

This approach is used in production at several companies and maps well to later service decomposition when teams choose to move from a monolith to microservices².

“Group code that changes together.” Organize your code around features to align engineering work with business value.

See also our post on the concentric circle model for related domain-centric design thinking.

Vertical slices vs layered architecture

Managing dependencies between slices

Keep slices independent and avoid direct calls between them. When functionality must be shared, use well-defined interfaces or an explicit shared library for generic technical concerns only. This discipline prevents a web of ad hoc dependencies and lets teams work in parallel with fewer merge conflicts.

Business impact of vertical slices

Organizing by feature is a business decision as much as a technical one. Teams that adopt feature-focused organization typically see measurable improvements in speed, quality, and maintainability. Research into high-performing software teams shows strong correlations between low coupling, rapid delivery, and operational stability⁵.

Ship faster, spend less

When each feature is self-contained, teams can build, test, and ship without coordinating across many horizontal teams. Studies and case reports indicate faster delivery and fewer integration failures for teams that move to feature-based structures². Co-located feature code also reduces long-term maintenance effort because it’s easier to find and fix bugs.

Organizing by feature ties engineering work directly to delivered value. Each slice becomes a testable and shippable unit of product.

Faster onboarding and team autonomy

Vertical slices flatten the learning curve for new hires. Give a new developer one small slice and they can contribute quickly without understanding the entire app. This model supports small, cross-functional teams that own features end-to-end and improves predictability.

AI-friendly codebases

AI coding assistants work best with tight, relevant context. When a slice contains UI, API, and data code for a feature, AI tools can offer much more accurate suggestions because the context window is coherent and focused. In layered systems, scattered context often produces generic or incorrect suggestions from tools like GitHub Copilot³.

How to structure a vertical-slice TypeScript project

Below is a practical example using Next.js, React, and Node.js. The key idea is to keep each feature self-contained so developers don’t jump between many directories to follow a request’s flow.

Example feature folder

For a “Create Blog Post” feature you might have:

• src/features/CreateBlogPost/
  • index.ts — barrel export
  • CreateBlogPost.tsx — React component and form
  • CreateBlogPost.api.ts — API route handler
  • CreateBlogPost.command.ts — business logic to create a post
  • CreateBlogPost.types.ts — TypeScript types for the feature
  • CreateBlogPost.repository.ts — database code for posts

This mirror of business capability makes it easy to find the code you need and to reason about feature changes.

Commands vs queries

Separate files by intent: commands mutate state and handle validation, while queries focus on efficient reads. This lightweight split is inspired by CQRS but keeps things pragmatic and approachable.

Handling shared code without creating new layers

Use a disciplined shared or core directory for generic, cross-cutting concerns only—authentication middleware, logging utilities, UI primitives, or a database client. Avoid placing business logic in shared, because that creates hidden coupling. If logic belongs to the domain, keep it inside the relevant slice.

Testing vertical slices

Vertical slices change how you test. Instead of many brittle unit tests that rely on mocks, prefer feature-level integration tests that exercise the slice end-to-end. That gives higher confidence that the feature actually works in concert.

Test the feature, not the layers

A typical integration test flow for a CreateBlogPost slice:

1. Set up a predictable database state (in-memory DB or test container).
2. Make an HTTP request to the slice’s API endpoint with a valid payload.
3. Assert on the response status and body.
4. Verify the database record was created with correct values.

This approach reduces fragile unit tests and improves coverage of real behavior. Teams moving to feature testing have reported clearer end-to-end coverage and fewer brittle tests⁴.

On the front end, use React Testing Library to simulate user interactions for the slice’s UI and assert the expected UX after the API call completes.

Common pitfalls and how to avoid them

Vertical slices bring clarity, but watch for these anti-patterns:

• The “fat” slice — one slice grows to cover many features. Fix by splitting into smaller, single-purpose slices.
• Leaky business logic — rules placed in shared. Fix by moving business rules back into the slice they belong to.
• Inconsistent slice structure — different folder layouts across features. Fix by agreeing on project conventions for naming and structure.

Avoid premature abstraction

Prefer duplication over the wrong abstraction. Wait for a stable pattern across several features before extracting shared code. Premature abstractions often add hidden coupling and complexity.

Practical migration strategy for legacy apps

Don’t rewrite everything. Build new features as vertical slices, and refactor small, contained parts of the legacy app into slices using a strangler approach. This incremental path modernizes the codebase without halting feature delivery.

At Clean Code Guy, we help teams adopt pragmatic patterns like vertical slices to build software that lasts. Our AI-Ready Refactors and Codebase Audits provide expert guidance to modernize your application safely. Learn more at https://cleancodeguy.com.

Frequently asked questions

How is vertical slice architecture different from microservices?

Vertical slices organize code inside a single application by feature. Microservices split a system into separate services. A monolith organized into vertical slices is often easier to break into microservices later, since each slice maps cleanly to a candidate service.

Is it okay to share code between slices?

Yes, for truly generic technical concerns in a disciplined shared or core folder. Keep business logic inside slices. When two slices need similar business rules, prefer duplication until a stable pattern emerges.

Can I introduce vertical slices into a legacy app?

Yes. Start by building new features as slices and refactor small, self-contained legacy features into slices over time using a strangler pattern.

Quick Q&A — Key concerns answered

Q: Will vertical slices slow down teams when first introduced?

A: Adoption takes discipline, but teams typically see faster delivery within a few sprints as feature work becomes more isolated and testable.

Q: How do I keep shared code safe?

A: Limit shared to technical utilities only. Keep domain rules inside slices and extract common code only after multiple features converge on the same pattern.

Q: What testing strategy works best?

A: Favor feature-level integration tests that exercise the slice end-to-end, supplemented by small, focused unit tests for complex logic.