Clean Architecture and Scalable Systems

# CHAPTER 17

Clean Architecture and Scalable Systems #

1. Introduction #

2. Learning Objectives #

• Define "Clean Architecture" as a macro-level system design.

• Understand the "Dependency Rule" (Dependencies only point inward).

• Implement a strict Layered Architecture (Entities, Use Cases, Interfaces).

• Differentiate between the core Domain Logic and external Infrastructure details.

• Map MVC (Model-View-Controller) into a clean enterprise structure.

3. The Goal of Clean Architecture #

• Independent of Frameworks: You can swap out Laravel for Symfony without rewriting the business rules.

• Testable: The business rules can be tested without the UI, Database, or Web Server.

• Independent of the UI: The UI can change from a Web View to a Console UI without changing the system.

• Independent of the Database: You can swap Oracle or SQL Server for MongoDB.

4. The Concentric Circles (The Layers) #

1. 1. Entities (The Center): The core business objects (e.g., A User object, a Loan calculation). They know absolutely nothing about the outside world.

1. 2. Use Cases (The Application Business Rules): The specific actions the system performs (e.g., RegisterUserUseCase). They orchestrate the Entities.

1. 3. Interface Adapters: Controllers, Gateways, and Presenters. They convert data from the format most convenient for the Use Cases, to the format most convenient for the external agencies (like the Web or DB).

1. 4. Frameworks & Drivers (The Outer Ring): The Web Server (Apache), the Database (MySQL), the UI Framework (React).

5. The Dependency Rule #

• Code in an inner circle can know *nothing* about code in an outer circle.

• The User Entity (Center) cannot import the UserController (Adapter).

• The RegisterUserUseCase cannot import the MySQLDatabase (Outer Ring). It must use an Interface (Dependency Inversion) so the dependency points inward.

6. MVC and Clean Architecture #

• The Traditional MVC Flaw: Developers put all the business logic inside the "Controller," or they tie the "Model" directly to the ORM database package.

• Clean MVC: The Controller is just an *Adapter* in the outer ring. It receives the HTTP request, and immediately hands it to a Use Case (Service) in the inner ring. The Model is an abstract Entity, independent of the database.

7. Diagrams/Visual Suggestions #

[ Outer Ring: Details ]    --> MySQL, React UI, AWS S3
           | (Points Inward)
[ Middle Ring: Adapters ]  --> Controllers, REST APIs, Repositories
           | (Points Inward)
[ Inner Ring: Domain ]     --> Use Cases, Core Business Entities, Pure Logic

*(Notice how the Core Domain never points out. It does not know it is on the Web).*

8. Best Practices #

• Screaming Architecture: When you look at the top-level directory structure of a project, it should scream what the application *does*, not what framework it *uses*.

• *Bad Folders:* /Controllers, /Views, /Models. (This screams "I am a web framework!").

• *Clean Folders:* /Billing, /Inventory, /UserManagement. (This screams "I am an E-Commerce system!").

9. Common Mistakes #

• Database-Driven Design: The most common architectural failure. The team designs the SQL tables first, and then builds the classes to exactly match the tables. The database dictates the architecture. In Clean Architecture, you design the inner business Entities first, completely ignoring how they will be saved. The database is added last, as a simple plugin to persist the objects.

10. Mini Project: Isolate the Domain #

// The business rule of applying a discount is trapped inside an HTTP Controller!
class OrderController {
    public function applyDiscount(HttpRequest $request) {
        $order = DB::find($request->id);
        $order->total = $order->total * 0.90; // The Core Business Rule
        $order->save();
        return new HttpResponse("Discount applied");
    }
}

*Clean (Isolated Domain):*

// The Core Business Rule is isolated in a pure class (No HTTP, No DB)
class ApplyDiscountUseCase {
    public function execute(OrderEntity $order): void {
        $order->applyPercentageDiscount(10);
    }
}
// The Controller just acts as a delivery mechanism.

11. Practice Exercises #

1. 1. Define the "Dependency Rule" in Clean Architecture. Why is it forbidden for an inner-ring Entity to import a class from an outer-ring Database package?

1. 2. Explain "Screaming Architecture." How should the folder structure of a medical records application differ from a standard MVC framework template?

12. MCQs with Answers #

13. Interview Questions #

• Q: Explain why the traditional MVC (Model-View-Controller) pattern is often insufficient for large enterprise applications, and how introducing a "Service/Use Case Layer" solves this problem.

• Q: "The database is a detail." Defend this statement from an architectural perspective. How do you design an application to defer the choice of the database engine until late in the development cycle?

• Q: Walk me through the concentric layers of Clean Architecture. If you need to send an email, in which layer does the actual SMTP code live, and how does the inner business logic trigger it without violating the Dependency Rule?

14. FAQs #

15. Summary #

16. Next Chapter Recommendation #