- Clean architecture is a software design approach where business logic is independent of frameworks, databases, and external services. SOLID principles are the foundation that makes this independence possible. - 62% of developers cite technical debt as their biggest frustration. Clean architecture and SOLID are the preventative. - Each SOLID principle addresses one specific way code becomes rigid and painful to change. You do not need all five everywhere — start with S and D. - The examples in this guide are in plain JavaScript. The principles apply regardless of framework. - Clean architecture and SOLID can be overapplied. Abstractions have a cost. Prototypes and small scripts should stay simple.

## What Is Clean Architecture? **Clean architecture is a software design approach where business logic stays independent of frameworks, databases, user interfaces, and external services.** Robert C. Martin (Uncle Bob) introduced it to solve a problem every developer hits eventually: core logic becomes so tangled with infrastructure that changing one thing breaks three others. Clean architecture is the structural answer. The core idea: dependencies point inward. The outer layers (HTTP handlers, database clients, UI components) know about the inner layers. The inner layers (business logic, domain rules) know nothing about the outer layers. The result is a codebase where you can swap your database without rewriting business logic, test your core logic without spinning up a real server, and add new delivery mechanisms (REST API, GraphQL, CLI) without touching the rules that govern your product. SOLID principles are what make this possible in practice. They are the design rules that, when followed consistently, produce the separation of concerns clean architecture requires. You cannot have clean architecture without SOLID. And once you understand SOLID, clean architecture becomes a natural extension of what you are already doing. This guide covers all five SOLID principles with JavaScript examples, explains how each one connects to clean architecture, and is honest about when to apply them and when they add unnecessary complexity.

## S: Single Responsibility Principle **A class or function should have one reason to change.** Uncle Bob's more precise formulation: a module should be responsible to one, and only one, actor: meaning one stakeholder whose requirements drive changes to that code. In clean architecture terms, this is what keeps the layers separate. Business logic changes for business reasons. Database access changes for infrastructure reasons. HTTP handlers change for delivery reasons. When these concerns are mixed into a single class, a change in any one of them ripples through the others. **Before — one class doing too much:** ```js class Invoice { constructor(items) { this.items = items; } calculateTotal() { return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0); } saveToDatabase() { // Infrastructure concern inside a business logic class db.query("INSERT INTO invoices ...", this.items); } printInvoice() { // Presentation concern inside a business logic class console.log(`Invoice total: ${this.calculateTotal()}`); } } ``` This class has three reasons to change. A database schema change, a formatting change, or a calculation change all force you to open the same file and risk breaking the other two concerns. **After — each concern in its own class:** ```js // Business logic. changes only when calculation rules change class Invoice { constructor(items) { this.items = items; } calculateTotal() { return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0); } } // Infrastructure concern. changes only when persistence changes class InvoiceRepository { save(invoice) { db.query("INSERT INTO invoices ...", invoice.items); } } // Presentation concern. changes only when output format changes class InvoicePrinter { print(invoice) { console.log(`Invoice total: ${invoice.calculateTotal()}`); } } ``` In clean architecture, this separation is structural. The `Invoice` class lives in the domain layer. The `InvoiceRepository` lives in the infrastructure layer. The `InvoicePrinter` lives in the presentation layer. Each layer changes independently. **The practical test:** If describing what a class does requires the word "and," it is doing too much.

## O: Open/Closed Principle **Code should be open for extension but closed for modification.** In clean architecture, the inner layers define interfaces (abstractions). Outer layers provide implementations. When you need new behaviour, you add a new implementation of an existing interface. you do not touch the core. This is what makes clean architecture extensible without being fragile. **Before — adding a new payment method requires editing existing code:** ```js class PaymentProcessor { processPayment(payment) { if (payment.type === "credit_card") { // credit card logic } else if (payment.type === "paypal") { // PayPal logic } // Adding Stripe means opening this file // Every new method = more branches = more risk to existing logic } } ``` **After — new payment methods extend without touching existing code:** ```js class CreditCardPayment { process(amount) { /* credit card logic */ } } class PayPalPayment { process(amount) { /* PayPal logic */ } } class StripePayment { process(amount) { /* Stripe logic. added without changing anything above */ } } class PaymentProcessor { constructor(paymentMethod) { this.paymentMethod = paymentMethod; } processPayment(amount) { this.paymentMethod.process(amount); } } // Swap the implementation without touching PaymentProcessor const processor = new PaymentProcessor(new StripePayment()); processor.processPayment(100); ``` In clean architecture terms, `PaymentProcessor` is the use case. It depends on an abstraction, not a concrete implementation. New payment providers are added in the infrastructure layer without touching the use case. **The practical test:** When adding a feature, count how many existing files you had to modify. More than one or two is a signal OCP was violated.

## L: Liskov Substitution Principle **Subclasses should be substitutable for their parent class without breaking the program.** In clean architecture, your business logic works against abstractions, not specific implementations. Liskov substitution is what guarantees that any implementation of that abstraction behaves consistently. If a subclass breaks the contract of its parent, the calling code has to check which type it is dealing with. which defeats the purpose of the abstraction. **Before — subclass breaks the parent's contract:** ```js class Shape { area() { throw new Error("area() must be implemented"); } } class Rectangle extends Shape { constructor(width, height) { super(); this.width = width; this.height = height; } area() { return this.width * this.height; } setWidth(width) { this.width = width; } } class Square extends Shape { constructor(side) { super(); this.side = side; } area() { return this.side * this.side; } setWidth(width) { // Breaks Rectangle's contract. setting width also changes height this.side = width; } } function resize(shape) { shape.setWidth(10); // Works correctly for Rectangle, breaks for Square console.log(shape.area()); } ``` **After — each shape fulfils its contract independently:** ```js class Shape { area() { throw new Error("area() must be implemented"); } } class Rectangle extends Shape { constructor(width, height) { super(); this.width = width; this.height = height; } area() { return this.width * this.height; } } class Square extends Shape { constructor(side) { super(); this.side = side; } area() { return this.side * this.side; } } function printArea(shape) { // Works correctly for any Shape. no type checking needed console.log(shape.area()); } printArea(new Rectangle(4, 5)); // 20 printArea(new Square(4)); // 16 ``` **The practical test:** If calling code uses `instanceof` checks before using a subclass, LSP has been violated.

## I: Interface Segregation Principle **No code should be forced to depend on methods it does not use.** In clean architecture, the boundaries between layers are defined by interfaces (or shared contracts). ISP keeps those interfaces small and focused so that implementing a boundary contract does not force you to implement behaviour that is irrelevant to your use case. JavaScript does not have formal interfaces, but the principle still applies through class contracts and duck typing. **Before — one large contract forces irrelevant implementations:** ```js class Worker { work() { throw new Error("Not implemented"); } eat() { throw new Error("Not implemented"); } sleep(){ throw new Error("Not implemented"); } } class Robot extends Worker { work() { console.log("Robot working"); } eat() { // Robots don't eat. forced to implement an irrelevant method throw new Error("Robots don't eat"); } sleep() { // Robots don't sleep. forced to implement another irrelevant method throw new Error("Robots don't sleep"); } } ``` **After — smaller, focused contracts:** ```js class Workable { work() { throw new Error("Not implemented"); } } class Feedable { eat() { throw new Error("Not implemented"); } } class Robot extends Workable { work() { console.log("Robot working"); // Robot only implements what it actually needs } } class Human { work() { console.log("Human working"); } eat() { console.log("Human eating"); } sleep(){ console.log("Human sleeping"); } } ``` **The practical test:** If a class has methods that throw "not implemented" because they are required by the contract but irrelevant to this class, ISP has been violated.

## D: Dependency Inversion Principle **High-level modules should not depend on low-level modules. Both should depend on abstractions.** This is the most important of the five. It is the mechanism that keeps the dependency direction pointing inward. The actual implementation of clean architecture's core rule. When business logic directly creates and uses concrete implementations (a specific database client, a specific email service), those infrastructure details leak into the core of the application. Clean architecture's dependency rule (outer layers depend on inner layers, not the reverse) is implemented through dependency inversion. Business logic defines what it needs (an abstraction). The infrastructure layer provides the implementation. The business logic never knows which implementation it is using. **Before — business logic tightly coupled to a concrete implementation:** ```js class MySQLDatabase { save(data) { console.log("Saving to MySQL:", data); } } class UserService { constructor() { // UserService creates its own database // Switching databases means rewriting UserService // Testing requires a real MySQL connection this.db = new MySQLDatabase(); } createUser(user) { this.db.save(user); } } ``` **After — business logic depends on an abstraction, implementation injected from outside:** ```js class UserService { constructor(database) { // UserService doesn't know or care what database this is // This is the clean architecture boundary in code this.database = database; } createUser(user) { this.database.save(user); } } // Infrastructure layer implementations class MySQLDatabase { save(data) { console.log("Saving to MySQL:", data); } } class PostgresDatabase { save(data) { console.log("Saving to Postgres:", data); } } // Test implementation. no real database required class MockDatabase { constructor() { this.saved = []; } save(data) { this.saved.push(data); } } // Production const service = new UserService(new MySQLDatabase()); service.createUser({ name: "Pablo" }); // Tests. inject a mock, run without any infrastructure const mockDb = new MockDatabase(); const testService = new UserService(mockDb); testService.createUser({ name: "Pablo" }); console.log(mockDb.saved); // [{ name: "Pablo" }] ``` This is clean architecture's dependency rule made concrete. `UserService` is in the domain layer. `MySQLDatabase` is in the infrastructure layer. The domain layer defines what it needs. The infrastructure layer fulfils it. The dependency arrow points inward. **The practical test:** If your tests require a real database, a real email server, or a real third-party API to run, DIP has likely been violated.

## How SOLID Builds Clean Architecture The five principles are not independent rules. They describe the same goal from five angles: keeping your core logic independent of external concerns so it can change, be tested, and be extended without cascading effects. In clean architecture terms: **SRP** ensures each layer has a clear, single purpose. Business logic, data access, and presentation never share a file. **OCP** ensures new features are added by extending outer layers, not modifying inner ones. Your domain logic is stable. Your infrastructure is pluggable. **LSP** ensures any implementation of a boundary interface behaves consistently. Your business logic never needs to check which implementation it is working with. **ISP** keeps boundary interfaces small so implementing them does not force irrelevant behaviour onto adapters. **DIP** is the mechanism that implements the dependency rule itself. Business logic depends on abstractions. Infrastructure provides implementations. The dependency arrow always points inward. Apply S and D first. They give the most immediate return and create the structure where the other three follow naturally.

## When Not to Apply Clean Architecture and SOLID Clean architecture and SOLID add structure. Structure has a cost. more files, more abstractions, more cognitive overhead for new developers joining the project. For small scripts, one-off tools, and early prototypes, that cost is not worth the benefit. A 50-line data migration script does not need dependency injection. A prototype validating whether an idea works should be as simple as possible. Apply clean architecture and SOLID when: You need to write tests and the code is currently untestable because of tight coupling. Multiple developers are working on the same codebase and stepping on each other's changes. You are adding features and keep having to modify code that should be stable. You switched a dependency (database, email service, external API) and it required touching more files than it should have. Those are the signals that architectural investment will pay off. Until then, keep it simple and refactor toward clean architecture as complexity demands it.

## Wrap Up Clean architecture is not a specific folder structure or a framework. It is the result of consistently applying SOLID principles: keeping business logic independent of infrastructure, letting dependencies point inward, and building systems where each layer has one clear purpose. The most direct path to clean architecture is through the D and S principles. Inject your dependencies instead of creating them inside business logic. Give each class one job. The rest follows from there. If you are building a web product and want your project management, deployment tracking, and analytics in one workspace while you focus on shipping clean code, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

## What is clean architecture in software development? Clean architecture is a software design approach where business logic is independent of frameworks, databases, user interfaces, and external services. Dependencies point inward. outer layers (HTTP handlers, database clients) know about inner layers (business rules), but not the reverse. This means you can swap your database without rewriting business logic, test core logic without real infrastructure, and add new delivery mechanisms without touching domain rules. SOLID principles are the foundation that makes this independence achievable in practice. ## What are SOLID principles and how do they relate to clean architecture? SOLID is five design principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion. Together they describe how to structure code so each part has one clear purpose, is extensible without modification, and depends on abstractions rather than concrete implementations. These are the specific rules that produce the separation of concerns clean architecture requires. Dependency Inversion is particularly direct. it is the mechanism that implements clean architecture's dependency rule in code. ## How do I implement clean architecture in JavaScript? Start with dependency inversion: pass dependencies (database clients, email services, external APIs) into your classes through the constructor rather than creating them inside. This keeps your business logic independent of infrastructure and makes testing possible without real services. Then apply single responsibility: split classes that do multiple things into focused units. Structure your code in layers (domain, application, infrastructure) where each layer only imports from layers closer to the center. The domain layer should have no imports from external libraries. ## What is the dependency inversion principle in JavaScript? The dependency inversion principle means business logic should not directly create and use concrete implementations. Instead, pass implementations in from outside. through the constructor or a configuration layer. In JavaScript this looks like: `class UserService { constructor(database) { this.database = database; } }`. The service does not know or care whether `database` is MySQL, Postgres, or a test mock. This is the pattern that makes unit testing possible without real infrastructure and makes switching dependencies a config change rather than a code rewrite. ## What is the single responsibility principle with a JavaScript example? The single responsibility principle means a class or function should have one reason to change. An `Invoice` class that calculates totals, saves to a database, and formats output for printing has three reasons to change. Split it into `Invoice` (calculation), `InvoiceRepository` (persistence), and `InvoicePrinter` (formatting). Now a database schema change only touches `InvoiceRepository`. A formatting change only touches `InvoicePrinter`. The calculation logic is never at risk from either change. ## When should I not use clean architecture? Clean architecture adds structure at a cost. more files, more abstractions, more cognitive overhead. For small scripts, one-off tools, and early prototypes, that cost is not worth the benefit. A data migration script does not need dependency injection. A prototype validating an idea should be kept simple. Apply clean architecture when you need tests but the code is untestable, when multiple developers keep stepping on each other's changes, or when adding features keeps requiring modifications to stable code. Those are the signals the investment will pay off. ## What is the difference between clean architecture and MVC? MVC (Model-View-Controller) is a pattern for separating presentation concerns from data and business logic. Clean architecture is a broader set of principles for structuring the entire application so business logic is independent of all external concerns, including databases, frameworks, and UI. MVC can exist inside a clean architecture. the Controller is an adapter that translates HTTP requests into use case calls, the View is a presenter, and the Model maps to domain entities. Clean architecture does not replace MVC. it provides the larger structure within which MVC and other patterns operate.