Clean Architecture layers in LLD - System Design Guide

Problem Statement

When application code mixes business logic with UI or database details, changes in one area cause bugs in others. This tight coupling makes the system hard to test, maintain, and evolve as requirements grow or technologies change.

Solution

Clean Architecture separates the system into layers with clear rules: inner layers contain business rules, outer layers handle details like UI and databases. Dependencies only point inward, so core logic stays independent and easy to test or replace.

Architecture

UI Layer

(Controllers, Views)

↓

Application Layer

(Use Cases, Services)

↓

Domain Layer

(Entities, Business

↓

Infrastructure Layer

(Database, Frameworks)

This diagram shows the four main layers of Clean Architecture with arrows pointing inward, indicating dependencies flow from outer layers to inner layers only.

Trade-offs

✓ Pros

→

Keeps business logic independent from UI and database changes.

→

Improves testability by isolating core logic from external concerns.

→

Facilitates easier maintenance and evolution of the system.

→

Supports parallel development by separating concerns clearly.

✗ Cons

→

Adds initial complexity and more code structure to simple projects.

→

Requires discipline to maintain strict layer boundaries.

→

May introduce some performance overhead due to abstraction layers.

Use when building medium to large applications with complex business rules or when expecting frequent changes in UI or infrastructure components.

Avoid for very small or simple projects where added layers increase complexity without clear benefit.

Real World Examples

Amazon

Uses Clean Architecture principles to keep their core order processing logic independent from various front-end platforms and database technologies.

Netflix

Applies layered architecture to isolate business rules from delivery mechanisms, enabling rapid UI experimentation without risking core logic.

Uber

Separates domain logic from infrastructure to support multiple client apps and evolving backend services independently.

Code Example

The before code mixes validation, database saving, and UI printing in one class, making changes risky. The after code splits responsibilities: Order holds business rules, OrderService handles use cases, OrderRepository manages data storage, and OrderController manages UI interaction. This separation follows Clean Architecture layers and dependency rules.

LLD

### Before: Business logic mixed with database and UI
class OrderProcessor:
    def __init__(self, db):
        self.db = db

    def process_order(self, order_data):
        # Validate order
        if not order_data.get('items'):
            raise ValueError('No items')
        # Save to DB
        self.db.save(order_data)
        # Print confirmation
        print('Order processed')


### After: Clean Architecture layers separated

# Domain Layer
class Order:
    def __init__(self, items):
        if not items:
            raise ValueError('No items')
        self.items = items

# Application Layer
class OrderService:
    def __init__(self, order_repo):
        self.order_repo = order_repo

    def place_order(self, order):
        self.order_repo.save(order)

# Infrastructure Layer
class OrderRepository:
    def __init__(self, db):
        self.db = db

    def save(self, order):
        self.db.save(order)

# UI Layer
class OrderController:
    def __init__(self, order_service):
        self.order_service = order_service

    def submit_order(self, order_data):
        order = Order(order_data.get('items'))
        self.order_service.place_order(order)
        print('Order processed')

Alternatives

Layered Architecture

Layers are organized by technical roles but may allow dependencies between layers in both directions.

Use when: When the system is simpler and strict dependency rules are not critical.

Hexagonal Architecture

Focuses on ports and adapters around the domain, emphasizing input/output boundaries rather than strict layers.

Use when: When you want to isolate the domain with clear input/output interfaces.

Onion Architecture

Similar to Clean Architecture but emphasizes concentric circles with domain at the core and infrastructure at the outermost layer.

Use when: When you want a strong focus on domain model purity and dependency rules.

Summary

Clean Architecture separates software into layers with strict inward dependencies to isolate business logic.

This separation improves maintainability, testability, and flexibility to change UI or infrastructure independently.

It is best suited for medium to large systems with complex business rules and evolving requirements.