How Senior Engineers Structure SaaS Codebases

[00:00:00]Most developers structure their apps by asking one simple question. Where should I put this file? But senior engineers ask a better question. Who should be allowed to know about this? Because once your app gets bigger, folders are not the hard part anymore. No, no, no. The hard part is ownership. Your UI shouldn't know about Stripe price IDs.

[00:00:25]Your API shouldn't own business logic.

[00:00:28]And your database shouldn't leak into your front end. Every layer should have one job and one job only. So in this video I want to walk through how a production SAS code base is structured so that every layer has a job, every boundary has a reason and every future change has an obvious place to go.

[00:00:49]Because a good code base doesn't just tell you where files are, it tells you where decisions belong. So let's dive into it. Now as you see here, this is my project or in other words repository.

[00:01:03]And you will quickly realize that there are a lot of files, a lot of folders and with that written code. In other words, this project is huge. That's what she said. But now you might say, Jan, who cares? I mean, this video is about the perfect project structure. And yes, that's totally correct. But here's something you should know. The bigger your project is, the harder it is to structure your project. Let me show it to you with this little chart. So on the yaxis we have bad project structure and on the xaxis we have lines of code on other words complexity. And here's something that is quite interesting. If your project is small, let's say 5, 10, 15, 20, 30,000 lines of code, it's relatively easy to structure your project in a relatively clean way that scales with time. And even if you start off the incorrect way, so let's say, hey, the first 20,000 lines are pure garbage, pure spaghetti code, pure slop, you can still turn the ship around and clean things up. But at some point you will hit a magic number. That's how I call it, a magic point, which is 100,000 lines of code. And once you hit this mark, things fundamentally change.

[00:02:25]Because at this point, your project isn't small anymore. It's officially in the medium-siz category. And this means you have another set of problems. You probably now have users, traction, revenue, and also certain conventions built up. Like for example, your front end directly calling your database without ever going through your back end or for example your front end directly talking to Stripe, which should never happen. Or here's another thing, your front end enforcing authorization rules.

[00:02:58]No, please stop. This is the job of your back end. At some point, you will have so many conventions, incorrect conventions built up that it will be impossible to turn things around. And that's why I call 100,000 lines of code the magic number. And here's also something I want to mention. When I talk about project structure, I don't mean the folder structure. Yes, the folder structure also plays a role, but it's relatively easy to update your folder structure. As an example, this is a trash folder structure. API, app, B, backup, copy, final, comp, components, component set. This is not something you would want to ship into production. But here's the thing, you can easily fix this no matter how big your project is.

[00:03:45]These are just files and folders or in other words, imports. But the code, this is the hard part of your project structure. And there is another problem.

[00:03:54]AI coding agents amplify bad project structure. So if you know take this project right here, it has a bad folder structure. It has a bad project structure. wrong conventions and stuff like that. And if you now ask your coding agent to create a billing feature, what will it do? It will go through your project and see ah these are the conventions. Let me directly call the database. Let me not use the back end. Ah, let's authorize the user on the front end. It will use these conventions and built on top of them.

[00:04:26]And that's the problem with AI coding.

[00:04:28]Code has become cheap. It has become easy to generate code. hitting 100,000 lines of code is not hard. So that's the big problem. So right now we essentially have an epidemic. I have never seen so many bad project structures as right now. And the core reason for that is because people don't understand fundamentals anymore and because AI agents don't care. They will just reuse what you already have. And that's why it's so important to start off right away with the correct structure in mind.

[00:05:02]This will allow you to scale easily without any big complexities. And this will also guarantee a second thing. Your AI agents will automatically write clean code, secure code, and scalable code.

[00:05:16]Something that a lot of people struggle with because the project structure is the foundation of your project. If it's set up correctly, then it's super easy to work on your project in the long run.

[00:05:29]And with that you might also say but Chan what about the actual project structure? What about your project structure? How did you organize this repository? What about the folder structure? What about the dependency rule? How is everything connected? Well, these are all very good questions. And before we dive into all of them, I want to answer one question first. What even is this project? And what did I even build? Well, this is Syntax Kit, my own AI native SAS starter kit. I've been building it for about 6 months now, and it's basically everything I ever wanted for shipping products real fast. This here is not a toy demo. It's a real production ready mono repo with off multi-tenency, stripe billing, an AI integration, file uploads, transactional email support, analytics, internalization, an admin panel, docs, all of that wired together and ready to be extended. And the AI native part isn't even marketing fluff. The repo ships with agent instructions, skills, and guard rails baked in. So when you or a coding agent add a feature, there's an obvious safe path to follow. Oh, and by the way, since this here essentially is the launch video for Syntax Kit, the first five people who use the code YouTube, which you will now see on the screen, will get 50% off. Yes, you heard right. Five people 50%. So use the code while it's available. But now, let's continue with the video. And since you now know what this project even is, what I built, we can finally dive into the project structure. So with what should we start? You know what? Let's start with the basics. The general folder layout or other words folder structure.

[00:07:22]So first things first, what you have to realize is that this here is a monor repo setup built with turbo repo and of course PNPM workspaces. And what you will also probably already see is that this repository, this monor repo is broken down into two separate packages or you could call them gloss if you come from the PNPM world. So first of all we have the apps package which contains deployable surfaces in this case docs and web. And then there is also the packages package. I know sounds a bit weird. And this here contains focused product modules. So analytics API of brand core database etc. And if you now specifically look at the PNPM workspace file then you will see the same thing inside of here. There are two packages and now you will see something interesting minimum release age. Huh?

[00:08:16]What is that? So this here is a supply chain god. Essentially, if you want to install a package, it will never resolve to a version published less than 7 days ago and the value is set in minutes.

[00:08:28]This means 10,080.

[00:08:30]So, here's the thing. In the past, we had a lot of supply chain attacks, which targeted the latest version of a package. But using this minimum release age, I can make sure that I never installed the latest version because compromised packages usually get caught and with that yanked within days. So, less than 7 days. And here's the thing, most people don't do it because they don't even know about it. So, if you want to take away something from this video, then please set a minimum release age of 7 days. It will instantly make your application 10 times secure. And then you will see another thing that's quite interesting. Only build dependencies. And five dependencies are listed here. And this means these five packages are allowed to run installed scripts. and every other dependency is blocked from executing post install code like for example better offc etc. So this means this whole mono repo setup this whole repository this whole project is locked down by default which is very important especially at scale.

[00:09:35]Another interesting file is the turbo.json file because it explains how the repository is operated not just built. So in this case the build depends on build and DB generate. These are the environment variables which could affect a build. Then for example when a type check is run the Prisma client is generated so that types are never stale.

[00:09:57]This here is a very important file for the whole orchestration. Another thing I want to look at is the general naming uniformity. So please look at these files here. The content is not important just the file names and tell me what do you see. So active organization.ts active session.ts of abuse.ts billing urls.ts. Then we have an image URL schema file save redirect. What is interesting here? Well, these are all Typescript files. Surprise surprise. But that's not interesting. The interesting thing here is the naming format. What do I mean by that? Every file here uses kebab case name-ame etc. Not camel case, not snake case. I did not mix and match. No, I chose kebab case and I stuck to it. And this is true for every file. So, React components, hooks, routers, schemas, tests, every file looks the same. Every file has the same format. And does that mean that you should use kebab case? No, definitely not. Choose one format and stick to it.

[00:11:06]I don't care if it's kebab case, camel case, snake case, they are all the same thing. They all just look a bit different. But choose one and stick to it. Don't mix and match. This is one thing that I see a lot of beginners do, which is a huge mistake. And this is also something that LMs love to do. They love to mix and match. And that's why it's so important to review code. But now you might say, "Wait, Chan, let me again collapse this. Here you have an uppercased PR file. Readme. What else do we have here? Claw MD, agents.m MD. They are all uppercased. They don't use kebab case. And yes, that's true. But that's because these are not my conventions.

[00:11:44]Agents.md is not something that I created or invented. This is a very specific convention that needs to be used for the LMS to pick up this file.

[00:11:53]The same thing is also true for the readme.md.

[00:11:57]These are just you could say standards.

[00:11:59]These are conventions which have been set a long time ago and I'm just reusing them these conventions. But for my own files, I always use kebab case to stay consistent. The one thing that is interesting is that I right here use these underscores. But now you might say, "Wait, Chan, underscores, isn't that snake case?" No, this here is the first letter, this underscore. And the thing why I use this underscore is because in X.js you have a convention called private folders. And this here essentially just says, "Hey, Nex.js, this is a private folder. Don't expose it to the public." This is not really needed with the app router anymore.

[00:12:37]Nevertheless, this is a convention I like to use. So yes, in this case, this kind of deviates a bit from kebab case.

[00:12:43]Nevertheless, this is an XJS standard and that's why it makes sense right here. But now you might say, Jan, okay, this all makes sense, but this also kind of sounds cosmetic. And yes, this is true, but also kind of not. So the thing is when every file follows one predictable pattern, you never spend any time guessing what something should be called and neither does an AI agent. And this creates consistency. It allows you to scale better because you have a standardized schema. And whenever you bring on new engineers or new AI agents, they instantly know how things should look like and how things should be created and with that structured. So now we looked at a lot of super important things like the folder structure, the monor repo setup, naming conventions, security conventions, and much more. But here's the thing, these are just the basics. This is what you need to create a great project structure. But there's much more needed. This here will essentially take you from 0 to 10. But you want to go from 0 to 100, or in other words, from 10 to 100. So what should we look at now? Well, it's code organization. How did I organize my code? How should you organize your code?

[00:13:58]Good question. So, I organized my code by responsibility. And this means every layer has a job. Every dependency has a direction and every change has a place to go. So, my architecture defines what each layer may know. And what layers do I even have? Well, I have an UI layer, transport layer, domain layer, capabilities, vendors, and finally supporting foundations. So, in total, I have six layers which are connected to each other, and there's one main dependency flow as you see here. And what I also mean by dependency flow is that for example, the domain layer does not talk to the UI layer. There is a certain dependency flow, a certain dependency rule. And this brings a few things to the table if that makes sense.

[00:14:48]Security, but also consistency because the UI layer strictly talks to the transport layer. The transport layer strictly talks to the domain layer and not the other way around. This means we are guaranteed to not make any mistakes like calling stripe from the front end or enforcing authorization from the front end. It does not work. There is one flow and only one flow, nothing else. But now you might say, "Okay, Jan, interesting. But what even are the individual layers? What do they do?" So let's start with the first layer, the UI layer. The UI layer knows about what the user did and it expresses intent. So it houses routes, screens, components, typed client usage, stuff like that.

[00:15:35]Then the second layer is the transport layer. The transport layer validates input. It checks authentication and permissions. And finally, it delegates work. So, let's imagine the following.

[00:15:47]The user wants to check out, meaning the user wants to subscribe to your pro plan, 20 bucks per month. What happens?

[00:15:54]Well, the user clicks a button, check out, and then a request is made to the transport layer. The transport layer gets the input. Kaboom. It validates the input. It checks if the user is authenticated, if the user has the correct permissions and then it delegates the work. And also this transport layer houses the typed client.

[00:16:16]The HTTP mount OPC proceed just in my case OPC is like a TRPC alternative.

[00:16:23]It's essentially just an RPC layer which is open API friendly. It also houses all validation and permissions. It's essentially our powerhouse which even makes this whole application work. The third layer is the domain layer and the domain layer makes the product and business decisions and it also houses all of them. Then we have the capabilities layer. The capabilities layer is interesting because it handles all of the integration details like payments, storage, email, analytics and much more. Let me give you an example.

[00:16:57]Let's say you create an AI application and this means you need a sandbox provider. Let's take the cell sandboxes.

[00:17:05]So what you will do is add a new vendor the cell sandboxes and now you have a new capability sandboxes. And this sandbox capability is now an integration boundary behind stable package APIs and this makes everything consistent and again safe. The next layer is the vendors layer and the vendors layer stays at the edge. It houses all of the external systems like stripe s3 an email provider or email providers like resent as an example post talk if you would now have a third party off service like kind or clerk. It would also go inside of here R2 and stuff like that. And this layer is directly connected to the capabilities. This is the example I made. So if you would have now sandboxes as a capability then you would also add a vendor here burcell sandboxes. And then finally we have the supporting foundations layer as you see here. And as already mentioned it houses the shared package and the database package.

[00:18:08]The shared package provides shared contracts and schemas and then the database package provides persistence if that makes sense. But here's something quite interesting. The supporting foundations layer kind of has a divergence. What I mean by that is earlier I said hey we have a dependency rule a dependency flow. We start from the top and we go to the bottom. The vendors can't talk to the UI but the UI can talk to the transport layer. The supporting foundations on the other hand can go to the top. Meaning the supporting foundations the packages shared as an example can talk to the transport layer. The database package can talk to the core package and that's again because these are supporting foundations. They are needed in certain layers and that's why they are positioned at the bottom and can move to the top. So now you might say, "Uh-huh Jen, interesting." So instead of now thinking about file names, the alphabet, the day of the week or anything like that, we can think about responsibility.

[00:19:09]What is the code? What does the code do?

[00:19:11]And more importantly, what should the code know about and what should it not know about? And this essentially leads you to create layers six or more. Every layer with that has a job. Every dependency automatically has a direction and every change automatically also has a place to go. This here in my opinion is the best way to organize your project. It might seem a bit complicated at the start because you have to actually think about stuff, but once the foundation is set, it makes your life so much easier in the long run. But now you might say, Chan, this year was very theoretical. We now looked at the diagram, a few packages, and that's it.

[00:19:53]But how is everything defined in your codebase? How does everything work in real life? Good question. So here I have three package.json files. my package.json file that lives in the web folder in the web deployable, the package.json file that lives in the API package and the package.json file that lives in the core package. And if we go back to the diagram, you will probably quickly realize that I just showed you the top three layers UI, transport, and domain apps web packages API and packages core. And now let's think about one thing, the dependency rule. What should happen in theory? Well, the transport layer should be able to talk to the domain layer. The UI layer should be able to talk to the transport layer, but the UI layer should not be able to talk to the domain layer. And the transport layer should not be able to talk to the UI layer. We have a onedirectional flow. So, let's look at it again. This here is the web deployable. And as you see here, one dependency is syntax kit API. So our UI layer is able to talk to the transport layer. But here's the important thing.

[00:21:07]The web deployable does not depend on syntax kit/core.

[00:21:12]There is no dependency. So we can't just go to the domain layer. No, we have to go through the transport layer. So you know what? Let's now look at the transport layer to be specific our API package. So here we have all of the dependencies. And do you see some sort of UI dependency? No. But you will see something else syntax kit core. So the API package depends on the core package but it does not depend on the UI package because this would essentially create like a incorrect direction right we have a one directional flow and that's why it does not work the other way around. And then finally we have the core package our domain layer. And please again look at the dependencies. Do you see some sort of syntax kit UI dependency or syntax kit web dependency? No. Do you see some sort of syntax kit API dependency? No. But you will see something else. Syntax kit analytics database email i8n payments shared storage. What is this? Huh? Auntie's capabilities. Yes, correct. Our domain talks directly to our capabilities. And that's why we see them as dependencies but we don't see the vendors and we don't see our transport layer. That's the interesting thing. This means whenever we now work on our codebase it's not possible to call the UI layer from the capabilities layer. Our UI layer can only call the transport layer in a onedirectional flow. And that's super important because it a creates consistency which is needed in a huge project but more importantly it creates security. So when you now have an AI agent working on your codebase it's not able to create a direct call from the UI layer to your stripe layer which is a gamecher because that's something that I see quite often with AI agents. They love taking shortcuts GPT 5.6 specifically. But using these layers and a dependency rule, you never have this issue because it's not even possible to create such a huge mistake. And that's what I meant by yes, it's a bit annoying to set everything up at the start because it's not super easy. It's a bit complicated, but once the foundation is set, it's such a huge game changer because mistakes are not possible anymore, which is so cool. Another interesting thing I want to show you is how the vendor boundary is enforced. So this here is my eslint.config file which lives in the web deployable and I want you to look at this constant constant no payments internals in web and then we have a few paths. What does this do right here? Well, this constant essentially says hey the web may not use syntax kit payments payment server payments types payments catalog. This should only be invoked or in other words used on the server side but never in the web and with that in the client side.

[00:24:12]The only thing that is allowed to be called on the client side or on the web in general is syntax kit payments client. And if for example syntax kit payments is now imported on the web or on the client side then we will first of all get a boundary violation which becomes a lint error but also our CI enforces the rule which means even if we make a mistake even if we import this on the web it will be handled meaning the CI will throw an error and the application won't be deployed and I can even show it to you. So if I now go to this page.tsx tsx which lives in the web deployable. I can now import something from syntax kit payments and as you see here I instantly get this red squiggly line. Uh-huh. Interesting. What does it say? Syntax kit payments import is restricted from being used. Don't import payment internals from the web app. Use syntax kit payments client. And that's why this is such a huge gamecher. I'm not able to import the wrong thing. the dependency rule is set and it can't be circumvented if that makes sense. And this again is great for us normal people. If I want to now work on this project, I instantly see ah this does not work. Let me call the transport layer. And if an AI agent works on this project, it instantly sees the error and says ah okay, so I should probably call the transport layer. And that's why it's so important to enforce boundaries.

[00:25:39]Another thing that is quite interesting is this constant no payments internals in a web hook route. So here's something you should know. A web hook route is a server boundary. Meaning everything that gets executed inside of here will get executed on the server side. But using this eslint rule, I make sure that we have an exception because all of these packages should not be imported on the client side and also they should not be imported in web hook routes. even though a web hook route is a server boundary.

[00:26:09]So that's something I want you to remember. Your general code organization, your general code architecture does all of the heavy lifting. But defining extra earlint rules does not hurt. It's the complete opposite. It's very helpful and I would say it's a must, at least in my opinion, because it gives you one huge bonus point. It lets your coding agents fail fast. What do I mean by that? Why do you want your coding agent to fail fast?

[00:26:36]Imagine the following. Your coding agent is working on a billing feature. It now wrote 80% of the code and then it realizes, wait, I forgot something. I imported the wrong things. These things shouldn't be imported on the web or something like that. This means you don't want your coding agent to write 80% of the code and then realize that it made a mistake. No, your coding agent should fail fast. And with that, your coding agent is able to produce cleaner, safer, and more scalable code. But since we now already talked about billing, I want to also show you a complete flow from A to Z. And with that, how a request flows between each layer. So this here is the dashboard of syntax kit. I will click on billing. And you know what? These are all of the available plans. What I will now do is click on pro, get started, and it should now redirect me to Stripe. So, what I will now do is add all of the data. And what I can now do is subscribe to this plan. Stripe will now process the payment and redirect me back. And as you see here, billing details updated successfully. Now, this here might look super simple to you. I mean, what did we just do? We subscribed to a pro plan and we now got redirected. That's it. Super simple, right? Well, not quite. There is quite a big flow behind such a simple feature and there are a lot of requests made between all of these individual layers. So, let me show you this diagram right here. Because this diagram explains exactly how everything works.

[00:28:09]First of all, we have the UI intent. In other words, the billing plan CTA.

[00:28:14]That's this button right here. As a next step, we have the transport layer. The transport layer handles the request. So I call an OPC procedure and then we make a post request to the RPC handler. The API procedure in this case also validates, authorizes and delegates and then the domain gets the request. What does the domain do in this case? Well, the domain kind of owns the decision. So it calls the create checkout procedure.

[00:28:44]It uses then the create checkout schema.

[00:28:46]The create checkout schema is actually a supporting foundation because the schema is something we get from the shared package. This is what I meant like here we have a small divergence because this package is accessible from the domain layer. This is the only layer which can be diverged. And then if we go back to our diagram, you will see here that we then call the create checkout for orc function. Then resolve forward and then finally the request gets forwarded to our capabilities layer. In other words, payments. So this capability layer, our payments layer if that makes sense, now creates the checkout session. And then finally, Stripe, our vendor gets the request and then Stripe handles the external checkout. So if we again look at our original diagram, this is the flow. Everything starts with the UI. Let me make this a bit smaller. Everything starts with the UI billing plan CTA.

[00:29:40]Then we continue with the transport as you see here. The transport layer authorizes, validates, and of course delegates. Then our domain layer finally gets the request as you see here. The domain layer calls all of the necessary functions. The domain layer of course also owns all of the business decisions.

[00:29:58]And then finally, the request gets forwarded to the capabilities layer. The capabilities layer in this case houses our payments layer. Meaning we call the create checkout session function. And the create checkout session function forwards the request to our vendor layer. In other words, Stripe. And then Stripe does all of the other needed stuff. But we are still not finished because we then also have phase two. As you probably already know, payments are asynchronous. They are not synchronous.

[00:30:27]It's not like, hey, let me quickly pay.

[00:30:29]Bum done. No, it often takes a few seconds, maybe even a minute or maybe even a day. And that's why it's important to use web hooks. And in phase two, that's exactly what we do. The web hook handler receives the checkout event or maybe even multiple events, who knows? And then we do a state sync meaning we sync the billing state with our local state with our database. And then finally our UI again refetches everything and updates the UI meaning we now show hey the user is subscribed to the pro plan. This is the next billing date. Cancel the subscription manage and stripe. This is how a fullon flow looks like with a correct project structure.

[00:31:09]So as you see here, instead of mixing and matching, everything went through the needed layers in one specific flow.

[00:31:16]We followed our dependency rule UI transport domain capabilities, vendors, and of course supporting foundations.

[00:31:24]And let me also show you everything in code. So this here is the use mutations hook. And this file houses the checkout mutation function. So the UI starts with intent and this then uses this hook or in other words this function. This function then calls an OPC procedure create checkout. We now went from the UI layer to the transport layer. But here's the important thing. This procedure this create checkout procedure does not decide stripe details. This here is just the transport layer not our domain layer. This request then enters through an RPC mount. This one right here RPC.

[00:32:03]Then we have this catch all route and this here is then essentially our HTTP entry point. One thing which is also interesting is that this procedure uses an input schema the create checkout schema and the create checkout schema lives in the shared package. What does that mean? Well, we now used layer six.

[00:32:22]So if I go back to the diagram supporting foundations schemas. So we now looked at the UI layer, the transport layer, and now we need the domain layer. So let's go back to the procedure. What do we do here? We have our input schema output. That's all fine. Assert billing enabled. Then await enforce RPC abuse policy. That's not super important. But look at this function. Return create checkout for orc. Now if we think about it again, the transport layer does not house any business logic. This means in theory this function should live in our domain layer, right? Hm. Let me open this function. And what do we have here? This function lives in the core package because this here is business logic. It defines business logic. So we now looked at the UI layer. The request was made to the transport layer. The transport layer made a request to the domain layer. And in theory, our function, our domain layer function should now make a request to our capabilities layer. So let's go back. What do we have here? Switch get checkout conflict. That's all fine.

[00:33:30]Let's continue. Await create checkout session. Hm. Let me open this. So this here is the function create checkout session. Payments server. Where does this payment server file live? Or this function. Uh-huh. Syntax kit payments.

[00:33:46]This is our capabilities layer. So if we now go back to our diagram, we now looked at the UI layer, transport layer, domain layer, and even capabilities layer. Our request made it to layer 4.

[00:33:59]And while doing so, it went through each individual layer. Layer 1, layer 2, layer three, and now layer four. And each layer has its own role, its own job. The transport layer made sure that everything looks good, that the user is authorized, that the input is correct.

[00:34:15]So we did input validation. The domain layer now added all of the business logic. The capabilities layer is now able to talk to Stripe. So let me show it to you. I will go back. So what do we have here? Create checkout session.

[00:34:28]Payments server create checkout session.

[00:34:31]What does this function do? Let's see.

[00:34:33]It should call stripe. So create stripe checkout session. And this function uses stripe. So we now finally landed in our vendors layer. Isn't that cool? This is how such a feature should work. Every layer should do its own job and every layer should then connect to each other in one specific order. You want to have a dependency rule. But yeah, this is how a flow looks like end to end. Everything starts with the UI and ends with the vendor. And what do you think? How do you structure your project? What do you think about my way of structuring projects? Of organizing code by responsibility, by putting specific packages into specific layers, by using a dependency rule, do not mix and match.

[00:35:21]Please let me know in the comments. I would love to know what you think and maybe we can learn of each other. But with that out of the way, I hope you enjoyed the video. Please don't forget to like and subscribe. It would mean a lot to me and my heart. So, please do it. Don't forget to check out Syntax Kit. Syntax Kit is my own starter kit. I have been building it now for already 6 months and it's literally the best one out on the market. And don't forget the coupon code down below in the YouTube description. It's valid for the first five people and it will give you 50% off. But with that, see you in the next video. Over and out. Bye-bye.