Clean Architecture: A Blueprint for Scalable and Maintainable Software

Clean Architecture is a software design philosophy that helps developers build flexible, maintainable, testable, and scalable applications. It emphasizes separation of concerns, ensuring that different parts of the application have clear responsibilities and do not mix unrelated logic.

Think of it like designing a beautiful city with a well-planned infrastructure—roads, districts, utilities, and zoning regulations all working together efficiently. A well-architected city makes daily operations smoother, just as a well-structured application makes development, testing, and maintenance easier.

Applying Clean Architecture to Simple App

For example, let’s consider my new application, Hui Shuo (会说), an application available on the App Store. The app is relatively simple (at least for now) :

• It fetches sentences from the internet and displays them as a list.
• It includes a detail screen.
• Users can search for specific sentences.
• A widget allows quick access to content.
• The app is a native Apple cross-platform app, running on iOS, iPadOS, and macOS.

In this series, we will explore how Clean Architecture fits this application and why it’s beneficial.

What Is Clean Architecture?

Clean Architecture is a broader concept that enforces certain principles to keep software organized and adaptable. It is not tied to any specific framework or platform and can be applied to any software project.

The Core of Clean Architecture: SOLID Principles

Clean Architecture must adhere to the SOLID principles, which stand for:

• SRP (Single Responsibility Principle): Each module or class should have only one reason to change.
• OCP (Open/Closed Principle): Code should be open for extension but closed for modification.
• LSP (Liskov Substitution Principle): Subtypes should be interchangeable with their base types without breaking functionality.
• ISP (Interface Segregation Principle): Clients should not be forced to depend on interfaces they do not use.
• DIP (Dependency Inversion Principle): High-level modules should not depend on low-level details; instead, both should depend on abstractions.

We will deep dive into each SOLID principle in the next article, so stay tuned!

Visualizing Clean Architecture with Onion Architecture

Clean Architecture can be visualized using Onion Architecture, a design proposed by Jeffrey Palermo in 2008. It follows a layered structure where dependencies always point inward, ensuring that business logic remains independent of external frameworks.

Here’s how it looks:

1. The Core (Domain Layer / Entities Layer)

At the center of the Onion Architecture is the Domain Layer, which contains enterprise-wide business rules. In the image, the Domain layer consist of at least 2 circles, the Entities and the UseCases. This is the heart of the application and remains completely independent of any frameworks, databases, or UI components. Both circles are closely related so it is better to keep it in one module, or folder, or group.

• This layer consists of entities (domain models) and core business rules.
• It must not depend on anything from the outer layers.
• Examples: Entities, Models, UserProfile, use case protocols.

2. Application Layer (Use Cases Layer)

This layer defines the business logic specific to application workflows. It acts as an intermediary between the core domain and the outer layers.

• Contains use cases (or services) that coordinate operations between entities.
• Implements application-specific rules but does not depend on frameworks or databases.
• Examples: FetchSentencesUseCase, SearchSentencesUseCase.

3. Infrastructure Layer (Adapters / Presentations / Use case implementation Layer)

The Infrastructure Layer serves as the bridge between the core business logic (domain & application layers) and external systems like databases, APIs, and UI frameworks. This is where we:

• Interact with HTTP clients, database clients, or external services and map the data into a usable format.
• Implement UI logic, such as ViewModels, data transformations, and state management, to make data ready for UI consumption.

4. Presentation Layer (UI Layer / Interface Layer)

The Presentation Layer is the outermost layer of the application, responsible for user interactions and handling data flow between the UI and business logic. It includes:

• UI components such as SwiftUI views and UIKit views.
• API clients and data persistence mechanisms, including Core Data and Firebase.

Key Responsibilities:

• User Interface Handling – Displays data and responds to user actions.
• Data Transformation for UI – Converts domain models into a UI-friendly format.
• External Communication – Interacts with databases, APIs, and third-party services.

Examples:

• UI Components (SwiftUI Views, UIKit Views)
• Adapters for External Systems (NetworkLoaders, CacheManagers, CoreData xcdatamodeld files, …)

Visualizing Clean Architecture with Dependency Diagram

When drawing the components using dependency diagrams, we can see that that onion architecture can be represented as the following diagram, nicely colored and grouped :

The grouping of layers follows a similar structure but is designed in a more component-oriented way. The green and yellow layers represent the Domain (Core) layer, which contains essential components such as Entities and high-level policies, including protocols or interfaces that define business rules.

The blue layer acts as an intermediary responsible for managing both presentation and data processing. It ensures that data is correctly formatted and transferred between other layers, such as the UI or external I/O components.

Finally, the purple layer consists of concrete implementations that interact directly with the blue layer. This layer serves as a bridge between business logic and external frameworks, including UI components, databases, and network services, ensuring seamless communication between the core application and its dependencies.

Conclusion

Clean Architecture provides a structured approach to software design, ensuring that applications remain maintainable, scalable, and testable over time. By separating concerns and enforcing SOLID principles, developers can build systems that are adaptable to change while keeping their core business logic independent of external dependencies.

In this article, we introduced the concept of Clean Architecture and how it applies. We also explored its relationship with Onion Architecture, another layered approach that follows similar principles.

Moving forward, we will dive deeper into each SOLID principle, discussing their real-world applications and how they contribute to Clean Architecture.

Stay tuned for the next article! 🚀

References

• Clean Architecture: A Craftsman’s Guide to Software Structure and Design – Robert C. Martin (Uncle Bob)

• The Onion Architecture: Part 1 – Jeffrey Palermo (2008) (link)