# nikolovlazar/nextjs-clean-architecture architecture

> Architecture diagram of the GitHub repository nikolovlazar/nextjs-clean-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikolovlazar/nextjs-clean-architecture
- Repository: https://github.com/nikolovlazar/nextjs-clean-architecture

## Overview

##### Main Components
- Frameworks & Drivers Layer: Represent the Next.js “app” folder. This layer includes route handlers, page components, server actions, React components (such as “sign-in”, “sign-up”, and UI components in app/_components), and global styles. It is the interface through which external clients interact.
- Interface Adapters Layer: This is the “src/interface-adapters” folder where controllers reside. These controllers are the bridge between the UI and the core business logic; they orchestrate use cases and transform responses for presentation.
- Application Layer: Capture the “src/application”. This contains the use cases (such as authentication actions and todo operations) and defines interfaces for repositories and services. It is the orchestration layer where business rules are applied.
- Entities Layer: Found under “src/entities”. This folder contains the domain models (such as cookies, sessions, todos, and users) along with custom error definitions. This layer ensures that business rules and validations remain independent from external concerns.
- Infrastructure Layer: Represented by “src/infrastructure”. It implements the repository and service interfaces defined in the Application Layer. This layer also abstracts away any direct dependencies on technologies like databases or external services. Note also the “drizzle” folder which provides database schema definitions, migrations, and configurations.
- Dependency Injection (DI): The “di” directory in the root configures the dependency injection container and modules. It binds interfaces with their respective implementations for services (authentication, todos, users, monitoring, and more).
- Testing: Don’t forget the “tests” folder which maps to the structure of your Application and Interface Adapters layers, ensuring that each use case and controller is covered by unit tests.

##### Relationships and Interactions
- How the Use Cases in the Application Layer interact with both the Entities (domain models and errors) and the Infrastructure (via repositories and services). This keeps the domain model pristine and independent from framework or database concerns.
- How database access is provided by the Drizzle layer (schema, migration scripts) and how these interact with the Infrastructure repositories.

##### Architectural Patterns and Design Principles
- Dependency Rule: Components only depend inwardly (for example, controllers depend on use cases, which depend on the repository/service interfaces, not directly on the implementation).
- Separation between the UI (Frameworks & Drivers) and the business logic (Application and Entities) ensuring testability and maintainability.
- DI mechanism (using “ioctopus” as referenced in the README) which abstracts away implementation details from the use cases and controllers.

## Diagram (Mermaid)

```mermaid
graph TD
    UI["Frameworks & Drivers (Next.js UI)"]
    Controllers["Interface Adapters (Controllers)"]
    Application["Application (Use Cases & Interfaces)"]
    Entities["Entities (Domain Models & Errors)"]
    Infra["Infrastructure (Repository & Service Implementations)"]
    DI["Dependency Injection (DI Container)"]
    Drizzle["Drizzle (Database Schema & Migrations)"]
    Testing["Testing (Unit tests)"]

    UI -->|"routes"| Controllers
    Controllers -->|"delegates"| Application
    Application -->|"usesDomain"| Entities
    Application -->|"callsRepository"| Infra
    Infra -->|"managesSchema"| Drizzle

    DI ---|"wires"| Controllers
    DI ---|"wires"| Application
    DI ---|"wires"| Infra

    Testing ---|"tests"| Controllers
    Testing ---|"tests"| Application

    click UI "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/app"
    click Controllers "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/src/interface-adapters"
    click Application "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/src/application"
    click Entities "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/src/entities"
    click Infra "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/src/infrastructure"
    click DI "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/di"
    click Drizzle "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/src/infrastructure/drizzle"
    click Testing "https://github.com/nikolovlazar/nextjs-clean-architecture/tree/main/tests"

    classDef ui fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef adapters fill:#aed6f1,stroke:#1b4f72,stroke-width:2px;
    classDef app fill:#abebc6,stroke:#117a65,stroke-width:2px;
    classDef domain fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef infra fill:#f5b7b1,stroke:#943126,stroke-width:2px;
    classDef di fill:#d2b4de,stroke:#6c3483,stroke-width:2px;
    classDef test fill:#d5dbdb,stroke:#424949,stroke-width:2px;
    classDef drizzle fill:#d6eaf8,stroke:#21618c,stroke-width:2px;

    class UI ui;
    class Controllers adapters;
    class Application app;
    class Entities domain;
    class Infra infra;
    class DI di;
    class Testing test;
    class Drizzle drizzle;
```
