System Design Series Part 12: Low-Level Design (LLD) Fundamentals

# Bad: Exposed internal state
class BankAccount:
    def __init__(self):
        self.balance = 0  # Public - anyone can modify!

# Good: Encapsulated with controlled access
class BankAccount:
    def __init__(self, initial_balance=0):
        self._balance = initial_balance  # Protected
        self._transactions = []
    
    @property
    def balance(self):
        """Read-only access to balance"""
        return self._balance
    
    def deposit(self, amount):
        """Controlled mutation with validation"""
        if amount <= 0:
            raise ValueError("Deposit amount must be positive")
        self._balance += amount
        self._transactions.append(('deposit', amount))
    
    def withdraw(self, amount):
        """Controlled mutation with business logic"""
        if amount <= 0:
            raise ValueError("Withdrawal amount must be positive")
        if amount > self._balance:
            raise InsufficientFundsError()
        self._balance -= amount
        self._transactions.append(('withdraw', amount))
    
    def get_statement(self):
        """Controlled access to transaction history"""
        return list(self._transactions)  # Return copy, not reference

# Base class
class Shape:
    def __init__(self, color):
        self.color = color
    
    def area(self):
        raise NotImplementedError("Subclasses must implement area()")
    
    def perimeter(self):
        raise NotImplementedError("Subclasses must implement perimeter()")
    
    def describe(self):
        return f"A {self.color} {self.__class__.__name__}"

# Derived classes
class Rectangle(Shape):
    def __init__(self, color, width, height):
        super().__init__(color)
        self.width = width
        self.height = height
    
    def area(self):
        return self.width * self.height
    
    def perimeter(self):
        return 2 * (self.width + self.height)

class Circle(Shape):
    def __init__(self, color, radius):
        super().__init__(color)
        self.radius = radius
    
    def area(self):
        return 3.14159 * self.radius ** 2
    
    def perimeter(self):
        return 2 * 3.14159 * self.radius

# Polymorphism: Same interface, different behavior
def total_area(shapes: list[Shape]) -> float:
    """Works with ANY shape - polymorphism in action"""
    return sum(shape.area() for shape in shapes)

# Usage
shapes = [
    Rectangle('red', 10, 5),
    Circle('blue', 7),
    Rectangle('green', 3, 3)
]
print(total_area(shapes))  # Works for all shapes

Definition: Software entities should be open for extension but closed for modification.

# Bad: Must modify class to add new discount types
class DiscountCalculator:
    def calculate(self, order, discount_type):
        if discount_type == 'percentage':
            return order.total * 0.1
        elif discount_type == 'fixed':
            return 10.0
        elif discount_type == 'bogo':  # Adding new type requires modification
            return order.total * 0.5

# Good: Open for extension via new classes
from abc import ABC, abstractmethod

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, order) -> float:
        pass

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percent):
        self.percent = percent
    
    def calculate(self, order):
        return order.total * (self.percent / 100)

class FixedDiscount(DiscountStrategy):
    def __init__(self, amount):
        self.amount = amount
    
    def calculate(self, order):
        return min(self.amount, order.total)

class BuyOneGetOneDiscount(DiscountStrategy):
    def calculate(self, order):
        return order.total * 0.5

# Adding new discount = new class, no modification needed
class LoyaltyDiscount(DiscountStrategy):
    def calculate(self, order):
        return order.total * (order.customer.loyalty_years * 0.02)

# Calculator is closed for modification
class DiscountCalculator:
    def apply(self, order, strategy: DiscountStrategy):
        return strategy.calculate(order)

Definition: Objects of a superclass should be replaceable with objects of its subclasses without breaking the application.

# Bad: Square violates LSP for Rectangle
class Rectangle:
    def __init__(self, width, height):
        self._width = width
        self._height = height
    
    def set_width(self, width):
        self._width = width
    
    def set_height(self, height):
        self._height = height
    
    def area(self):
        return self._width * self._height

class Square(Rectangle):  # Square IS-A Rectangle?
    def set_width(self, width):
        self._width = width
        self._height = width  # Violates expected behavior!
    
    def set_height(self, height):
        self._width = height
        self._height = height

# This breaks with Square:
def test_rectangle(rect: Rectangle):
    rect.set_width(5)
    rect.set_height(4)
    assert rect.area() == 20  # Fails for Square!

# Good: Separate hierarchy
class Shape(ABC):
    @abstractmethod
    def area(self) -> float:
        pass

class Rectangle(Shape):
    def __init__(self, width, height):
        self.width = width
        self.height = height
    
    def area(self):
        return self.width * self.height

class Square(Shape):  # Square is NOT a subtype of Rectangle
    def __init__(self, side):
        self.side = side
    
    def area(self):
        return self.side ** 2

Definition: Clients should not be forced to depend on interfaces they don't use.

# Bad: Fat interface
class Worker(ABC):
    @abstractmethod
    def work(self): pass
    
    @abstractmethod
    def eat(self): pass
    
    @abstractmethod
    def sleep(self): pass

class Robot(Worker):
    def work(self):
        print("Working...")
    
    def eat(self):
        pass  # Robots don't eat! Forced to implement.
    
    def sleep(self):
        pass  # Robots don't sleep! Forced to implement.

# Good: Segregated interfaces
class Workable(ABC):
    @abstractmethod
    def work(self): pass

class Eatable(ABC):
    @abstractmethod
    def eat(self): pass

class Sleepable(ABC):
    @abstractmethod
    def sleep(self): pass

class Human(Workable, Eatable, Sleepable):
    def work(self):
        print("Human working...")
    
    def eat(self):
        print("Human eating...")
    
    def sleep(self):
        print("Human sleeping...")

class Robot(Workable):  # Only implements what it needs
    def work(self):
        print("Robot working...")

Definition: High-level modules should not depend on low-level modules. Both should depend on abstractions.

# Bad: High-level depends on low-level
class MySQLDatabase:
    def save(self, data):
        print(f"Saving to MySQL: {data}")

class UserService:
    def __init__(self):
        self.db = MySQLDatabase()  # Tight coupling!
    
    def create_user(self, data):
        self.db.save(data)  # Locked to MySQL

# Good: Both depend on abstraction
class Database(ABC):
    @abstractmethod
    def save(self, data): pass
    
    @abstractmethod
    def find(self, id): pass

class MySQLDatabase(Database):
    def save(self, data):
        print(f"Saving to MySQL: {data}")
    
    def find(self, id):
        return {"id": id, "source": "mysql"}

class MongoDatabase(Database):
    def save(self, data):
        print(f"Saving to MongoDB: {data}")
    
    def find(self, id):
        return {"id": id, "source": "mongodb"}

class UserService:
    def __init__(self, db: Database):  # Depends on abstraction
        self.db = db
    
    def create_user(self, data):
        self.db.save(data)

# Flexible - can swap implementations
mysql_service = UserService(MySQLDatabase())
mongo_service = UserService(MongoDatabase())

Encapsulates object creation logic, allowing the client to request objects without knowing the concrete class.

# Factory Pattern
class NotificationFactory:
    @staticmethod
    def create(notification_type: str, message: str):
        if notification_type == 'email':
            return EmailNotification(message)
        elif notification_type == 'sms':
            return SMSNotification(message)
        elif notification_type == 'push':
            return PushNotification(message)
        else:
            raise ValueError(f"Unknown type: {notification_type}")

# Usage - client doesn't know concrete classes
notification = NotificationFactory.create('email', 'Hello!')
notification.send()

Allows incompatible interfaces to work together by wrapping an object with a compatible interface.

# Adapter Pattern
# Legacy payment system
class LegacyPaymentGateway:
    def make_payment(self, account_number, amount_in_cents):
        print(f"Legacy: Charging {amount_in_cents} cents to {account_number}")
        return True

# Modern interface we want to use
class PaymentProcessor(ABC):
    @abstractmethod
    def charge(self, card: dict, amount: float) -> bool:
        pass

# Adapter bridges the gap
class LegacyPaymentAdapter(PaymentProcessor):
    def __init__(self, legacy_gateway: LegacyPaymentGateway):
        self.legacy = legacy_gateway
    
    def charge(self, card: dict, amount: float) -> bool:
        # Convert modern call to legacy format
        account = card['number'].replace('-', '')
        cents = int(amount * 100)
        return self.legacy.make_payment(account, cents)

# Usage - modern interface, legacy implementation
adapter = LegacyPaymentAdapter(LegacyPaymentGateway())
adapter.charge({'number': '1234-5678-9012-3456'}, 99.99)

Defines a one-to-many dependency so that when one object changes state, all dependents are notified.

# Observer Pattern
class EventEmitter:
    def __init__(self):
        self._observers = {}
    
    def subscribe(self, event: str, callback):
        if event not in self._observers:
            self._observers[event] = []
        self._observers[event].append(callback)
    
    def unsubscribe(self, event: str, callback):
        if event in self._observers:
            self._observers[event].remove(callback)
    
    def emit(self, event: str, data=None):
        if event in self._observers:
            for callback in self._observers[event]:
                callback(data)

# Usage
class UserService(EventEmitter):
    def create_user(self, data):
        user = User(**data)
        self.emit('user_created', user)
        return user

# Subscribe to events
service = UserService()
service.subscribe('user_created', lambda u: print(f"Sending welcome email to {u.email}"))
service.subscribe('user_created', lambda u: print(f"Logging: User {u.id} created"))
service.subscribe('user_created', lambda u: print(f"Updating analytics..."))

service.create_user({'name': 'Alice', 'email': 'alice@example.com'})

-- B-Tree Index (default) - Equality and range queries
CREATE INDEX idx_orders_customer ON orders(customer_id);
CREATE INDEX idx_orders_created ON orders(created_at);

-- Composite Index - Multi-column queries
-- Order matters! (customer_id, status) supports:
--   WHERE customer_id = ?
--   WHERE customer_id = ? AND status = ?
-- But NOT: WHERE status = ?
CREATE INDEX idx_orders_cust_status ON orders(customer_id, status);

-- Partial Index - Index subset of rows
CREATE INDEX idx_pending_orders ON orders(created_at)
WHERE status = 'pending';

-- Expression Index - Index computed values
CREATE INDEX idx_orders_date ON orders(DATE(created_at));

-- Full-text Index - Text search
CREATE INDEX idx_products_search ON products 
USING gin(to_tsvector('english', name || ' ' || description));

-- Hash Index - Equality only (no range)
CREATE INDEX idx_users_email ON users USING hash(email);

# Clean Architecture / Layered Structure
"""
project/
+-- domain/              # Core business logic (no dependencies)
¦   +-- entities/
¦   ¦   +-- user.py
¦   +-- repositories/   # Interfaces only
¦   ¦   +-- user_repository.py
¦   +-- services/
¦       +-- user_service.py
+-- infrastructure/      # External integrations
¦   +-- database/
¦   ¦   +-- postgres_user_repository.py
¦   +-- external/
¦       +-- email_client.py
+-- application/         # Use cases, orchestration
¦   +-- use_cases/
¦       +-- create_user.py
+-- presentation/        # API, CLI, Web
    +-- api/
        +-- user_routes.py
"""

# Domain Layer - Pure business logic
class User:
    def __init__(self, email: str, name: str):
        self.email = email
        self.name = name
        self.validate()
    
    def validate(self):
        if '@' not in self.email:
            raise ValueError("Invalid email")

class UserRepository(ABC):
    @abstractmethod
    def save(self, user: User) -> User: pass
    
    @abstractmethod
    def find_by_email(self, email: str) -> User | None: pass

# Infrastructure Layer - Concrete implementations
class PostgresUserRepository(UserRepository):
    def __init__(self, connection):
        self.conn = connection
    
    def save(self, user: User) -> User:
        self.conn.execute(
            "INSERT INTO users (email, name) VALUES (%s, %s)",
            (user.email, user.name)
        )
        return user

# Application Layer - Use cases
class CreateUserUseCase:
    def __init__(self, repo: UserRepository, email_service: EmailService):
        self.repo = repo
        self.email_service = email_service
    
    def execute(self, email: str, name: str) -> User:
        existing = self.repo.find_by_email(email)
        if existing:
            raise UserAlreadyExistsError()
        
        user = User(email, name)
        self.repo.save(user)
        self.email_service.send_welcome(user)
        return user