Structuring Next.js Starter Kit with Clean Architecture

Implementing a layered architecture in Next.js, the speaker explains how to structure code for maintainability and separation of concerns.

### Implementing Clean Architecture in Next.js Starter Kits
* 🏗 Implementing a clean architecture approach involves structuring code into different layers like **controllers, use cases, entities, and persistence** to maintain code maintainability and prevent dependencies that make the project **hard to maintain**.
* 📦 The "presentation layer" or "controller" contains Next.js-specific code like server actions, and it should be kept separate from the business logic to the right of a **defined boundary** to maintain **clean separation**.
* 🧑 Server actions act as controllers in the presentation layer, and they are responsible for **handling user interactions** and **calling the corresponding use cases**.
* Use cases, located in the business layer, encapsulate the **core business logic** of the application and often include **authorization checks** and **business rules**.
* 💾 The persistence layer is responsible for providing methods to **store and query data** from the data store, abstracting away the details of **how data is persisted**.
* 🔄 Using a clean architecture approach allows for a **common pattern that the entire team can follow**, making it **easier to onboard new team members and maintain the codebase**.
* 📂 Co-locating related code in the same directory, such as **components with the pages that use them**, can help **improve code maintainability** and make the project **easier to understand**.
* 🛡 Applying the principle of "**separation of concerns**" helps prevent leaking sensitive information or implementation details between layers, and using **data transfer objects (DTOs)** can be a way to enforce this separation.

so I think it's been like a week since I've published a video on my channel, and I figured I should probably get something published out there before the YouTube algorithm thinks I'm no longer relevant. So I want to talk about the structure of my code and how I kind of architect the code for my next.js starter kit. Um, you can kind of take what you want from this. You can in the comments, you can say that this is dumb, you can say, hey, I agree with what you're doing, maybe we can have a discussion about it and just learn from it. A lot of the stuff I'm going to be showing in this video do come from an idea called clean architecture. There's a book called clean architecture written by Uncle Bob. We apply this, or we try to apply this as best as possible at work. So we have something called like controllers, use cases, entities, and you kind of structure your code in different layers. And there's certain rules that you follow so that you don't have dependencies that cause your project to be a little bit

more unmaintainable. There's also like a layered architecture approach where you basically have like a presentation layer, a business layer, a persistence layer, and a database layer. This is also kind of what I'm doing on my starter kit, which I'll kind of walk you through the different layers that I have applied. I highly recommend that you do something like this on your projects. Like I've seen a lot of videos and tutorials where people are just like doing uh Prisma calls or drizzle calls or SQL calls calls directly in their react server components when the page loads. And although that works, I just don't think it's a very long-term maintainable solution. Uh, what you want to do is just apply some type of layered architecture so that you have more control over like who can read the data, who can manipulate the data, and you can kind of test your business logic separately from all the nextjs code. Okay, so let's just draw a little bit. So in my project, I'm trying to do a layered architecture type of

thing right. So, we have Next.js. And to help kind of exemplify what we're doing, um, we are going to follow a use case where I'm an admin or an owner of this group, and I want an admin or owner to be able to modify the text on the info page. Like over here, if I say hello world, I save this. I want other users who are not admins or owners to be able to see this text when they go and view this group directly. So, in terms of that use case, what we just did in Next.js is what you probably know is I'm using server action. So, let's just go ahead and say we have a server action. I'll make a little box here. I'll say server action, and this is one of the layers. I'll call this a presentational layer. You may also call this a controller. It doesn't really matter. The point is you want to keep all your Next.js specific code to the left of this line, right? You don't want React cache methods or unstable cache.

methods bleeding over onto the right side of the line. You don't want revalidate path or revalidate tag bleeding over cuz now at this point you don't have nice clean uh separations between like what's in charge of the presenting and the controlling of your code and what's in charge of the actual business logic. So that leads me to my next point. If I consider a server action kind of like a controller, if you were to look at this layer architecture, the presentational layer would probably be like react or your react server components that render out the page when you invoke an action. Again, that's kind of calling a presentational layer controller. Again, if you were to look at the clean architecture Circle, your controllers in your presenters are all in this interface adapters, right? So the user needs to do something. They are going to invoke some type of controller, invoke some type of adapter, and in our case, I'm basically going to say that a server action is a form of a controller. Again, feel free to call me out in the

comments if anything I'm explaining doesn't seem right but this is just how I kind of think about it. So when a user clicks on the save changes, that invokes a server action, which again is still in this Next.js layer over here. So let's kind of look at the code. I have a page, and I click on a button, and it calls an action. Let's try to figure out where that's happening. I have an action here called update group info action. Now, something that I'm doing in my codebase is I want to make sure that everything that goes in and out of this action is parsed right. I want to make sure that the stuff that's sent in it matches a certain type of structure. I want to make sure that the group ID sent in is a number. There is an info that's sent in that is defined. And once I get that information, I can kind of trust it and start running some controller type of code. And again, notice that my actions, this is where I keep revalidate path or revalidate tag.

or redirect all of the next.js SL uh react specific code. I would probably keep it inside of This Server action. Now if you're curious how I'm using an authenticated action, I'm using a library called Zsa, which allows you to basically create middlewares. Where, for example, I have this authenticated action, I create a procedure, and anytime I want to create an action that requires authentication, all I do is I just run some code, make sure that the, you know, the cookie set, the session is set. I also do some rate limiting just so that all my authenticated endpoints are just rate limited by that user ID. I don't want people trying to maliciously abuse my systems, and then I return the user, right? So again, this is still all in the controller presentational layer. If we were to go back to this diagram now, at some point you'll see that after I've done the parsing of the input, which comes from a form or whatever, I'm calling something called a use case. This is just my nomac claure of like how I

like to denote this stuff, and this comes heavily from the Clean Architecture book. So all of my actions invoke use cases, and these use cases lead us to the next point I want to make out, and that is the business, uh, business layer. A business layer, and then inside of this business layer, the Clean Architecture believes that it calls them use cases or slash interactors. Okay, let's just look at this little diagram real quick, and you'll see he calls the little orange-red circle use cases, and then that points to application business rules. Okay, so from my perspective, what is a business rule? What are concerns of the business logic? Well, the action, all it's in charge of, is basically taking in, figuring out what the authentication methods are, maybe you're using JWT. Maybe using session storage, doesn't matter. The business layer does not care about that. All it cares about is that you're passing in the correct data, um, that it would expect. So in our case, this update group info use case, this needs a group ID and an info, and it also takes in an

authenticated user again. This thing doesn't know if we're using JTS or sessions. It just gives me a user object, and I'm going to use that user information to figure out if a user should have access to update the group info. So what this does is basically we're going to pass over some user information, the group ID, whatever, and we're going to invoke a use case again that I called update group info use case. I might as well go back to this one and change this one to have a name. Just call it this action here. So this action is going to invoke this business layer use case interactor, and this is where you want to run some type of authorization check. So in my group finder application, I have a lot of role-based authorization checks in place. You can be an owner or an admin of a group, or you can just be a member of a group. If you're an owner or an admin, an owner can actually go and delete the entire group. An admin just has the ability to modify some info.

they have the ability to come in here and maybe promote other users to an admin or demote users, etc. But the owner has, you know, very special privileges that you have to encode this in business logic somewhere. And so, how this works is basically this use case is where you're going to run your, you know, authorization checks. Is this user an owner or an admin? And then if they are, you want to be able to allow them to update this information. So, let's look at the code because it's actually super, super simple. So, basically, we first fetch the group by group ID. If there is no group, I throw an error. And again, you should not be throwing any type of Next.js specific errors here. You should not be calling redirects or anything. Keep it simple, throw errors or return some type of like error objects if you need to. And then finally, I do another check that says if I'm not the group owner, go ahead and throw an error that has unauthorized. And then finally, if everything passes, we just go ahead and

update that group info using that info that was passed in. Now, technically, there is more to clean architecture. If you look at this diagram, there's something called entities. And I'm avoiding entities just to keep it simple for my, you know, one-man team starter kit project. But at some point, you may want to encode business rules to say info can only be 1,000 characters, right? That is business rules that the business people can define. And I know when I say business, like I'm just talking about myself because this is like a one-man project. But when you work on a bigger team, like there's people who are going to define how large, how much data some of the stuff can be, what is the shape of this data? Is it a first name? Does it need to be all capitalized? Does it need to be proper case, stuff like that? And so sometimes what you want to do is you want to encode this information in something called business entities. And those entities can have validation rules themselves. Okay, now I'm not going to

dive into that because again I'm not doing that. So basically, I just call a method called update group, and this is something called a persistence method. So this is going to lead us to the next section of our code, which is the persistence layer. Okay, let's look at the layered architecture. We are over here. We just talked about the business layer a little bit. Now we're at the persistence layer, and the persistence layer's goal is to basically give you methods that you can invoke for storing and querying data from your data store, whether that be in Postgres, whatever. So we have a method over here called update group. So I'll just go ahead and make a little box here that's going to call update group, going to pass in some information such as a group ID, some info, and there's different ways you can do this. A lot of people use something called like a repository pattern where they'll have like an object called, I don't know, groups, and they'll say update, and they'll pass it whatever information. Something like this, I think, is just not

as friendly to read versus something update group that's just a personal preference. It doesn't really matter, but the point is, is that this layer is responsible for knowing how to write to your database, which in case I'm using drizzle. But something I want to point out is that you don't even know I'm using drizzle, right? The business layer has no concept of what omm you're using, what libraries you're using to actually persist the data. All it knows is that I need to call some method to save this group information, okay? That's been abstracted away about how that actually happen. So let's dive into this code real quick, and you'll see over here I have a data access folder with like all of my tables. I basically have like a one-to-one mapping of a file maps to a table in my SQL database. You can structure this however you want, but the way I typically do this is I have a groups file, and this has an update group function which allows you to basically take any group

ID and just update any parts of it right. And so now you start seeing some code that might look familiar to you, which is drizzle orm. So if you go up to the top here, you'll see that I am just defining like a drizzle orm connection. And in fact, let me, uh, how do I go to the definition here? I think just scroll up. You'll see I'm importing this from DB, which is bringing us some drizzle orm stuff, okay? So this persistence method, this persistence layer knows about how to write and persist the data, which if you look at a layered architecture, now we're hitting the database layer, something that we're using a library we're using knows how to write data. Let's just go ahead and put another line here. And this is going to write directly to a database. Just draw a database symbol here. Here we go. I'll just say post CR 'cause that's what I'm using. So if we zoom out a little bit, this is the pattern that I try to follow in my applications. This is just the way

I've been brought up when learning how to code. People smarter than me have taught me this pattern. I believe them and I follow the pattern too, not blindly, but I do try to follow it because I personally think it is useful. Some of the reasons why I think following either clean architecture or layered architecture or some type of pattern is, everyone on the team has a common pattern they can follow. If you're working on a project by yourself, I mean you could just raw dog SQL right in your react server components if you want to. I probably would not recommend that because if your project actually takes off and grows, you're going to want to bring in other engineers, and you want a Common Language, such as an architecture, that you can all discuss things about. Now, some teams and projects like to make this even more complex, which I'm on the fence of. A lot of teams will, in between these two layers, they'll do something called data transfer objects (DTOs) to make sure that certain things Never Bleed over. So, what I mean by bleeding

over so for example in the business layer. Let's say you're fetching something from a persistence layer. An update group happens to update the group, but then return the whole group object back. You could potentially have a bunch of extra fields on this database that you haven't actually like cleaned up. You could have like a group name, a group display name, all this other stuff, and you may not want that to ever bleed over into your business layer, right? So, sometimes what you do is you'll create a data transfer object so that all the data is basically sent through a mapper to make sure that you only return the things that are necessary from your persistence layer back to your business layer. And again, you want to make sure that you only return certain things from your business layer back to your controller or back into your react server component so that you don't leak sensitive information or information that's not a concern of any of these layers. One good example I've seen is a lot of people who use MongoDB a lot of the times the unique

identifier for your IDs is underscore ID, and they'll start bleeding that over into every single layer. You can actually look at the network request and see, Oh, all the entities have an underscore ID on them. I'm going to assume you guys are using MongoDB, right? Because that wasn't really abstracted way too well, and using something like a DTO could potentially help prevent leaking information about your underlying architecture of your system. Maybe you don't want people to know you're using MongoDB because that opens up more security attack vectors of how they can abuse your system, stuff like that. So that's kind of how I would recommend at least loosely following a project. The only DTO stuff I end up doing is with these actions over here. I can actually put an output as well, and I can specify what the output needs to look like. So over here, I can say, Well, I just want this to return nothing. I could say void or undefined or something, and that at least gives me a little bit of certainty because Zod is going to

verify that whatever I'm returning here, it has to match undefined. If I were to accidentally take the group that was being returned here and let's just say like name is Bomb, notice that I get some typescript errors that says, Hey, you're returning some information where you're not supposed to be returning that, because you specified an output of undefined. Something like that can be very useful. And again, this is basically a DTO. It's just that we're using libraries that just automatically do it for us, and I don't want to waste a bunch of time writing the mapping code and writing the DTO objects with classes and stuff like that. Now, before I wrap up this video, I do want to kind of touch a little bit about the directory structure of my projects. I try to collocate as much as possible. So if I'm looking at a page right here, for example, I'm on my group info page, everything that's on this page should be in the same directory as my info route. I don't like having a separate components.

folder where I put all those, and then I import them. I want all my components that are related to co-occur in this directory because I think it makes the project a little easier to maintain. At work, we do an approach where we have like every folder holds different things, and those things are separated by type, and you end up having this folder that has 500 different files in them, and there's like no good way to really understand like what is using this thing, okay so if it's not an actual res sharable reusable thing then I would just co-locate it. For example, typically server actions have stuff like this, like revalidate path, which means they are very tightly coupled to the page or the route that you're on, so it makes sense to just put your actions directly in this folder. Also, with components, this is the only place in this entire application I have a component that looks like this, so I'm not going to go and find my components directory and put it in there. I'm going to co-locate it so that if I were to

onboard someone under this project. They can also have a common Convention of like okay. I'm looking at the info page. I have 95% certainty that every component that's needed for this info panel is probably going to be right in this directory. Now another thing I'm still trying to figure out how I want to approach this is basically the react server components. When you hit a page, you typically need to load some data. And so the way I've been doing this is I'll just call these use cases directly here before I call the use case. I will basically get the current user from a session and then I'll call the use case and pass it the current session. And then also I'll pass it the um whatever arguments I might need. And that'll return some data for me right. And I can kind of throw errors inside the react server component where I could actually have like an errors. TS file handle that and display something else. The kind of exemplify what I mean. So this is the info page. It takes in a group ID which

is loaded from the URL here, and I basically take that and I call a git Group by ID use case. Let's just go ahead and go through the whole flow real quick. Quick so you understand, uh, I call this git Group by ID use case. In our case, I probably should do some type of authorization here to make sure that there's no like sensitive data being leaked. But um, again, you can kind of search for a lot of these groups publicly, and that ends up calling a get group by ID method, which calls a drizzle method to get the first group by an ID. Okay, and I don't see any issues with doing this as long as you just, you know, make sure you're passing in the user sessions again because you're calling the use case during your react server component, and all the business logic is kind of encapsulated there. Now, something that I might at some point end up needing is when you have a complex tree and you have to call the same method multiple times in your react server components. Typically, what you want to do

is you want to call a cache method which is built into next. I'm sorry this is built into react actually um so you can bring in a cache method from react and you can wrap your functions with this cach uh Factory function basically so that as it's traversing your react server components if it finds the same method it's just going to use the cach results for that individual request that your user made and then on the next request if a new user comes in it hits the same page brand new cache it's not going to reuse the old stuff okay so in some cases you may want to do that and I might actually add a new folder here or a new file called loaders and then I would probably just make a new fun function here called like uh get group by ID loader and then you could basically um you want to do this I could just set this to Cache like this and then I could just have this taken a group ID like so and then you know call the use case in here goad and say return get

group by ID use case, something like that. And then also in the loader, you could potentially get the user. So get current user like this so that I can pass it in. And then obviously, we want this to be an asynchronous function. So we do this. If for some reason you do end up needing to like wrap stuff with the Next.js, like try to avoid going into your use cases, your business layer, and like trying to add cache methods here because again you're breaking that convention of like now you're running a React code inside your business layer. Okay, so technically if I were to do that refactoring, I could just call that loader here. And then I can get that information, information and use it. So I want to talk on one last point as to why I think this is more maintainable. And the reason is if you keep all your Next.js code out of your business layer, what you can do is if down the road you decide that you know what server actions isn't it server actions is just not

worth doing. It's causing more headache. I'd rather go back to using form Hooks and go back to React Query and just hit API endpoints. Well, the refactoring involved with doing that is very simple because now you have this method that doesn't care about anything in Next.js. It doesn't care about how you're handling your actions or your post requests or mutations. It just needs some input. And so if later on you decide, you know what, I actually want to make this an API endpoint, well, it's super easy to just have a new API endpoint directory and invoke this, which makes it very convenient and a lot more maintainable. Another thing that I've seen in some projects is if you don't do some type of approach like this, you end up taking your business layer, like your logic that defines when a user should read something, and you end up putting it everywhere. Like you'll take this, you know, there's some certain rules that you need to check to see if a

user has access to get a group, and you're like, oh, I'll put it in this react server component, and then later on you'll decide that you need that same logic, and you'll put it in another place. Maybe you also need it in front of the API, but then you have all this business logic that's kind of sprinkled out throughout your controller and your presentational layer, which you'll start updating in one place, and you'll forget to update it somewhere else. And then it's just a big headache because you've basically spread out all of your core logic throughout your entire application. It becomes very, very hard to maintain and understand, and also to even switch off of in the future if you needed to for some reason. Um, anyway, I've been rambling for a while now, so I hope you guys enjoyed watching this video. Again, I just wanted to get something out there for you all, and hopefully this elevates your knowledge in coding a little bit. Again, leave a comment if there's a different approach you like to

make your applications. If you're using Next.js with server actions, let me know. We can have a discussion about it. Other than that, have a good day. Happy quing.

How I structure my next.js applications

This channel is a collection of various programming videos, tutorials, projects, talks, or anything software engineering and programming related.  If you are new to coding and want to learn how to program or get a job in the industry, be sure to subscribe to my channel.  There is a lot of great content on this channel to help you out in your coding goals.

Web Dev Cody

Architecting Code with a Layered Approach in Next.

The video discusses implementing a layered architecture, following the principles of clean architecture by Uncle Bob, to separate Next.

The presenter emphasizes the use of server actions as a form of controller in the presentational layer, keeping Next.

By applying this approach, the goal is to have better control over data manipulation and testing of business logic separately from Next.

When a user clicks "save changes," it triggers a server action in the Next.

The codebase focuses on parsing the input and ensuring it matches the expected structure before invoking use cases, following the principles of the Clean Architecture book.

The business layer, represented by the use cases, is concerned with the business logic and the expected data, independent of the authentication methods used in the actions.

Managing User Access and Authorization in Group Info Update

The process involves using the user information to determine their access rights for updating group info.

The authorization checks are based on the user's role (owner, admin, or member) within the group, with different privileges for each role.

The code follows a simple sequence of fetching the group, performing authorization checks, and then updating the group information based on the user's access level.

Understanding the Persistence Layer in Software Architecture

The persistence layer is responsible for providing methods to store and retrieve data from the database, abstracting the data storage details from the business layer.

It often involves using a repository pattern and is independent of the specific database or libraries being used.

In the demonstrated code, the persistence layer includes a file for each database table and utilizes the drizzle orm for data manipulation, ultimately writing directly to a PostgreSQL database.

The Importance of Following a Software Architecture Pattern

Following a common architecture pattern like clean architecture or layered architecture provides a common language for the team and facilitates future scalability.

Implementing data transfer objects (DTOs) can help prevent the leakage of sensitive information across different layers of the software.

Using DTOs also contributes to better abstraction and security, especially in cases like exposing MongoDB usage in network requests.

Structuring Projects and Managing Components

Using libraries for automatic DTO generation can help avoid writing mapping code.

Collocating related components in the same directory can make the project easier to maintain and onboard new team members.

When using React server components, directly calling use cases and handling errors within the component can be a potential approach for loading data.

js can help optimize the performance of react server components by reusing the cached results for the same method, thus improving efficiency for individual user requests.

js code separate from the business layer to maintain a more sustainable and organized structure, avoiding the incorporation of React code directly into the business layer.

Implementing a cache method through a loader function, such as "get group by ID loader," can help in effectively managing complex trees and multiple method calls in react server components.

The Benefits of Using a Unified Method in Next.

js allows for easy refactoring and maintainability, especially when transitioning to API endpoints.

This approach helps prevent the scattering of core logic throughout the application, making it more understandable and easier to maintain in the long run.

Implementing a unified method can ultimately streamline the development process and enhance coding knowledge for Next.