If you did not read the previous post about how to visualize the software architecture with C4 model, I would recommend to read it to have a big picture of what/how this app was built.
As the Architecture Decisions Records were approved, the tech stack will be:
- Clean Architecture
- TypeScript
- Prisma
- Cloudflare Workers with a D1 Database.
- Hono Framework
Demo
To help you better understand the concepts and see Clean Architecture in action, I’ve prepared a demo application for you. This demo uses the Note Taker App as a real-world example.
Source code: You can explore the full source code on GitHub. Feel free to clone the repo, experiment with the code.
Live Demo:
Clean Architecture
This diagram makes more sense to me compared to the original circular one. The color code is still consistent with the original. I hope it works for you too.
Clean Architecture is a set of rules that help us structure our application in such way that it will be easier to maintain and test. It’s kind of like a common language that helps developers understand each other.
I would highly recommend to read Clean Architecture book, it can elevate your understanding of software design to a new level. Here’s a quick summary based on my experience. Let me know your thought — feedback is always welcome:
At high-level, Clean Architecture provides a structured and abstract way to interact with the core business logic, similar like how an ORM abstracts and organizes interactions with a database.
It prioritizes independence and loose coupling, allowing different parts of your system to function independently.
Clean Architecture helps to organize the system with the core business logic at the center.
Unlike traditional layered architectures (e.g., 3-Tier or N-Tier), Clean Architecture focuses on controlling dependencies to keep components decoupled and maintainable.
The business logic is not couple to any framework, meaning you could later create a CLI or any type application without modifying the business logic.
All communication with business logic is facilitated through interfaces (abstractions).
Testable - Since the business logic doesn’t rely on external dependencies, it’s easy to test. The Use Case Interactor (or just "Use Case") is the primary location where you should focus on testing business logic and application rules. It is the core component that orchestrates and enforces the application's business rules, making it the ideal layer for concentrated testing.
Note Taker App
Project Structure (important ones only)
How you organize your project is up to your team, as long as everyone stays on the same page and communicates effectively day to day. Here’s an example structure for this app:
core: Contains reusable classes that can be used across multiple domains.
controller/http: Whatever consuming the business logic will be here. In this demo, it’s the Hono framework.
provider.ts: Manages dependency injection, setting up the DI container and modules.
prisma: Handles schema definitions and migrations using Prisma ORM.
domain: The most critical folder—it contains the core business rules
entity: Holds the models
exceptions: Defines custom error handling.
interactor: Where business use cases are executed. Unit tests go here.
infra: Contains database implementations (e.g., D1 in this case) and third-party services.
port:
persistence: Acts as the Output Port in Clean Architecture. This is the repository interface, enabling the Use Case Interactor to query, save, or update data without knowing the details of the database implementation.usecase: Acts as the Input Port in Clean Architecture. It abstracts how external layers (like controllers) interact with business logic.
Summary
At first glance, Clean Architecture might seem like over-engineering, but it's really about creating discipline and predictability in your code base. By defining clear rules about where everything belongs, it simplifies feature development and makes your code easier to work with.
Without structure, your code base will eventually turn into a mess, slowing down progress and forcing you to come up with rules the hard way. Clean Architecture saves you from that pain by providing a proven approach that’s been tested over time. Learn it once, and you can use it in any project, making your code maintainable and scalable from the start.
You should NOT apply Clean Architecture to every project. For projects with strict time constraints or smaller scopes, the added complexity may outweigh the benefits. Additionally, if team members are unfamiliar with Clean Architecture, the learning curve can slow development and reduce efficiency. It's best suited for larger, long-term projects where maintainability and scalability are critical.
What’s Next?
Start by applying Clean Architecture principles to a real-world project, just start with a small one.
Deepen your understanding of related concepts like SOLID principles, Domain-Driven Design (DDD).
Explore advanced topics like Dependency Injection (DI), design patterns, and event-driven architecture to enhance your architectural skills.
Top comments (0)