Complete Layered Architecture Guide

Complete Layered Architecture Guide with Next.js

Introduction

Why layered architecture? Modern software systems demand maintainability, testability, and scalability. Without a clear separation of concerns, projects quickly become tangled, making changes risky and costly.
In this guide, we will demystify layered architecture, walk through a real‑world example using Next.js, and provide a Mermaid diagram that visualizes the flow between layers.

What You Will Learn

• The principles behind a layered architecture.
• How to organize a project into distinct layers using Next.js.
• A complete code example implementing the layers with Next.js and TypeScript.
• Best practices for dependency direction and testing in a Next.js project.
• How to visualize the architecture with Mermaid.

Understanding Layered Architecture

Core Principles

Separation of concerns is the cornerstone. Each layer has a single responsibility and communicates only with adjacent layers.

Layer	Responsibility	Typical Technologies
Presentation	UI, API endpoints, request handling	Next.js, React
Application	Orchestrates use‑cases, transaction control	Services, Handlers
Domain	Business rules, entities, validation	TypeScript, POCOs
Infrastructure	Data access, external services, logging	Prisma, Repositories

Dependency Rule

Higher layers must not depend on lower layers. Dependencies flow inward, from outer to inner.

Project Structure Example

src/
│
├── components/
│   └── ui/
│
├── services/
│   └── application/
│
├── domain/
│   └── entities/
│   └── interfaces/
│
└── infrastructure/
    └── data/
    └── repositories/

Mermaid Diagram

graph TD
    UI[Presentation Layer] -->|Calls| App[Application Layer]
    App -->|Uses| Domain[Domain Layer]
    Domain -->|Accesses| Infra[Infrastructure Layer]
    Infra -->|Persists| DB[(Database)]

Implementation Walkthrough (Next.js and TypeScript)

Domain Layer

// src/domain/entities/product.ts
export class Product {
    public id: string;
    public name: string;
    public price: number;

    constructor(id: string, name: string, price: number) {
        this.id = id;
        this.name = name;
        this.price = price;
    }

    public applyDiscount(percentage: number) {
        if (percentage <= 0 || percentage > 100)
            throw new Error('Invalid discount percentage');

        this.price -= this.price * (percentage / 100);
    }
}

Application Layer

// src/services/application/productService.ts
import { Product } from '../domain/entities/product';

export class ProductService {
    private readonly productRepository: any;

    constructor(productRepository: any) {
        this.productRepository = productRepository;
    }

    public async getProduct(id: string): Promise<Product> {
        return await this.productRepository.getProduct(id);
    }

    public async createProduct(product: Product): Promise<void> {
        await this.productRepository.createProduct(product);
    }
}

Infrastructure Layer

// src/infrastructure/data/productRepository.ts
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export class ProductRepository {
    public async getProduct(id: string): Promise<any> {
        return await prisma.product.findUnique({ where: { id } });
    }

    public async createProduct(product: any): Promise<void> {
        await prisma.product.create({ data: product });
    }
}

Presentation Layer (Next.js Page)

// pages/api/products/[id].ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { ProductService } from '../../services/application/productService';
import { ProductRepository } from '../../infrastructure/data/productRepository';

const productRepository = new ProductRepository();
const productService = new ProductService(productRepository);

export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
) {
    if (req.method === 'GET') {
        const id = req.query.id;
        const product = await productService.getProduct(id as string);
        return res.status(200).json(product);
    }
}

Insight: Notice how the Presentation layer only knows about the Application service interface. It never touches the
Infrastructure or Domain implementations directly, preserving the dependency rule.

Testing Strategy

• Unit tests target the Domain and Application layers using mocks for repositories.
• Integration tests spin up an in‑memory database for the Infrastructure layer.
• End‑to‑end tests exercise the Presentation layer via HTTP calls.

Common Pitfalls & How to Avoid Them

Pitfall	Remedy
Leaking infrastructure types into higher layers	Use interface abstractions and DI containers.
Over‑crowding a layer with unrelated responsibilities	Keep single responsibility; extract new layers if needed.
Circular dependencies	Enforce dependency direction via architecture reviews.

Conclusion

Layered architecture provides a robust scaffold for building maintainable, testable, and scalable applications with Next.js. By adhering to the dependency rule, organizing code into clear folders, and visualizing relationships with tools like Mermaid, teams can reduce technical debt and accelerate delivery.
Ready to level up your Next.js codebase? Start refactoring a small module using the patterns in this guide and share your experience in the comments below!