This repo is an example of how to achieve Clean Architecture in Next.js. There's a video tutorial that goes through this project. Click on the image to check it out on YouTube:

You can run the project just by running npm install and npm run dev.

I strongly recommend you to read the original article by Uncle Bob if this is your first time hearing about Clean Architecture, but I'll try to summarize it for you below.

Clean Architecture is a set of rules that help us structure our applications in such way that they're easier to maintain and test, and their codebases are predictable. It's like a common language that developers understand, regardless of their technical backgrounds and programming language preferences.

Clean Architecture, and similar/derived architectures, all have the same goal - separation of concerns. They introduce layers that bundle similar code together. The "layering" helps us achieve important aspects in our codebase:

• Independent of UI - the business logic is not coupled with the UI framework that's being used (in this case Next.js). The same system can be used in a CLI application, without having to change the business logic or rules.
• Independent of Database - the database implementation/operations are isolated in their own layer, so the rest of the app does not care about which database is being used, but communicates using Models.
• Independent of Frameworks - the business rules and logic simply don't know anything about the outside world. They receive data defined with plain JavaScript, use plain JavaScript, Services and Repositories to define their own logic and functionality. This allows us to use frameworks as tools, instead of having to "mold" our system into their implementations and limitations. If we use Route Handlers in our app, and want to refactor some of them to Server Actions, all we need to do is just invoke the specific controllers in a server action instead of a route handler, but the core business logic remains unchanged.
• Testable - the business logic and rules can easily be tested because it does not depend on the UI framework, or the database, or the web server, or any other external element that builds up our system.

Clean Architecture achieves this through defining a dependency hierarchy - layers depend only on layers below them, but not above.

• app - Frameworks & Drivers Layer - basically everything Next.js (pages, server actions, components, styles etc...) or whatever "consumes" the app's logic
• di - Dependency Injection - a folder where we setup the DI container and the modules
• drizzle - Everything DB - initializing the DB client, defining schema, migrations
• src - The "root" of the system
  • application - Application Layer - holds use cases and interfaces for repositories and services
  • entities - Entities Layer - holds models and custom errors
  • infrastructure - Infrastructure Layer - holds implementations of repositories and services, and pulls in the interfaces from application
  • interface-adapters - Interface Adapters Layer - holds controllers that serve as an entry point to the system (used in Frameworks & Drivers layer to interact with the system)
• tests - Unit tests live here - the unit subfolder's structure matches src
• .eslintrc.json - Where the eslint-plugin-boundaries plugin is defined - this stops you from breaking the dependency rule
• vitest.config.ts - Take note of how the @ alias is defined!

• Frameworks & Drivers: keeps all the UI framework functionality, and everything else that interacts with the system (ex. AWS Lambdas, Stripe webhooks etc...). In this scenario, that's Next.js Route Handlers, Server Actions, Components (Server and Client), Pages, Design System, etc...
  • This layer should only use Controllers, Models, and Errors, and must not use Use Cases, Repositories, and Services.
• Interface Adapters: defines Controllers:
  • Controllers perform authentication checks and input validation before passing the input to the specific use cases.
  • Controllers orchestrate Use Cases. They don't implement any logic, but define the whole operations using use cases.
  • Errors from deeper layers are bubbled up and being handled where controllers are being used.
  • Controllers use Presenters to convert the data to a UI-friendly format just before returning it to the "consumer". This helps us ship less JavaScript to the client (logic and libraries to convert the data), helps prevent leaking any sensitive properties, like emails or hashed passwords, and also helps us slim down the amount of data we're sending back to the client.
• Application: where the business logic lives. Sometimes called core. This layer defines the Use Cases and interfaces for the services and repositories.
  • Use Cases:
    • Represent individual operations, like "Create Todo" or "Sign In" or "Toggle Todo".
    • Accept pre-validated input (from controllers) and handle authorization checks.
    • Use Repositories and Services to access data sources and communicate with external systems.
    • Use cases should not use other use cases. That's a code smell. It means the use case does multiple things and should be broken down into multiple use cases.
  • Interfaces for Repositories and Services:
    • These are defined in this layer because we want to break out the dependency of their tools and frameworks (database drivers, email services etc...), so we'll implement them in the Infrastructure layer.
    • Since the interfaces live in this layer, use cases (and transitively the upper layers) can access them through Dependency Injection.
    • Dependency Injection allows us to split up the definitions (interfaces) from the implementations (classes) and keep them in a separate layer (infrastructure), but still allow their usage.
• Entities: where the Models and Errors are defined.
  • Models:
    • Define "domain" data shapes with plain JavaScript, without using "database" technologies.
    • Models are not always tied to the database - sending emails require an external email service, not a database, but we still need to have a data shape that will help other layers communicate "sending an email".
    • Models also define their own validation rules, which are called "Enterprise Business Rules". Rules that don't usually change, or are least likely to change when something external changes (page navigation, security, etc...). An example is a User model that defines a username field that must be at least 6 characters long and not include special characters.
  • Errors:
    • We want our own errors because we don't want to be bubbling up database-specific errors, or any type of errors that are specific to a library or framework.
    • We catch errors that are coming from other libraries (for example Drizzle), and convert those errors to our own errors.
    • That's how we can keep our core independent of any frameworks, libraries, and technologies - one of the most important aspects of Clean Architecture.
• Infrastructure: where Repositories and Services are being defined.
  • This layer pulls in the interfaces of repositories and services from the Application Layer and implements them in their own classes.
  • Repositories are how we implement the database operations. They are classes that expose methods that perform a single database operation - like getTodo, or createTodo, or updateTodo. This means that we use the database library / driver in these classes only. They don't perform any data validation, just execute queries and mutations against the database and either throw our custom defined Errors or return results.
  • Services are shared services that are being used across the application - like an authentication service, or email service, or implement external systems like Stripe (create payments, validate receipts etc...). These services also use and depend on other frameworks and libraries. That's why their implementation is kept here alongside the repositories.
  • Since we don't want any layer to depend on this one (and transitively depend on the database and all the services), we use the Dependency Inversion principle. This allows us to depend only on the interfaces defined in the Application Layer, instead of the implementations in the Infrastructure Layer. We use an Inversion of Control library like ioctopus to abstract the implementation behind the interfaces and "inject" it whenever we need it. We create the abstraction in the di directory. We "bind" the repositories, services, controllers, and use cases to Symbols, and we "resolve" them using those symbols when we need the actual implementation. That's how we can use the implementation, without needing to explicitly depend on it (import it).