DEV Community: Madhukar Vissapragada

Simple Factory, Factory Method, Abstract Factory — Which One Do You Need?

Madhukar Vissapragada — Wed, 22 Jul 2026 16:06:20 +0000

The Problem

You're building a system that supports multiple databases — MySQL, PostgreSQL, MongoDB. Different services in your application need to create database-specific objects — queries, transactions, updators.

The naive approach? Let each service decide which object to create:

from abc import ABC, abstractmethod

class Database(ABC):
    @abstractmethod
    def create_connection(self): pass

    @abstractmethod
    def create_connection_pool(self): pass

    @abstractmethod
    def replication(self): pass


class Mysql(Database):
    def create_connection(self):
        print("Creating database connection for MySQL")

    def create_connection_pool(self):
        print("Creating database connection pool for MySQL")

    def replication(self):
        print("Managing replication of MySQL database")


class PgSQL(Database):
    def create_connection(self):
        print("Creating database connection for PostgreSQL")

    def create_connection_pool(self):
        print("Creating database connection pool for PostgreSQL")

    def replication(self):
        print("Managing replication of PostgreSQL database")


class MongoDB(Database):
    def create_connection(self):
        print("Creating database connection for MongoDB")

    def create_connection_pool(self):
        print("Creating database connection pool for MongoDB")

    def replication(self):
        print("Managing replication of MongoDB database")


class Query(ABC): pass
class SqlQuery(Query): pass
class MongoQuery(Query): pass


class UserService:
    def create_user(self, db: Database):
        if isinstance(db, Mysql):
            return SqlQuery()
        if isinstance(db, PgSQL):
            return SqlQuery()
        if isinstance(db, MongoDB):
            return MongoQuery()
        return None

Look at UserService.create_user. It has two jobs:

Creating a user
Deciding which query object to instantiate based on the database type

That's a Single Responsibility Principle violation — create_user should only create users, not make infrastructure decisions.

And every time you add a new database — say Cassandra — you open UserService and add another if. That's an Open/Closed Principle violation — you're modifying existing, working code to add new behaviour.

This is where the Factory pattern comes in.

Step 1: Simple Factory

The first fix is straightforward — extract the object creation logic into its own class. UserService delegates to it:

class DatabaseFactory:
    @staticmethod
    def create_query(db: Database):
        if isinstance(db, Mysql):
            return SqlQuery()
        if isinstance(db, PgSQL):
            return SqlQuery()
        if isinstance(db, MongoDB):
            return MongoQuery()
        return None


class UserService:
    def create_user(self, db: Database):
        return DatabaseFactory.create_query(db)

UserService is now clean — one responsibility. It doesn't know or care which query type gets created.

What Simple Factory gives you:

✅ SRP fixed — UserService has one job
✅ Centralised object creation — one place to look

What Simple Factory doesn't give you:

❌ OCP still violated — adding Cassandra means opening DatabaseFactory and adding another if

The if block didn't disappear. It just moved from UserService to DatabaseFactory. We need to go further.

Step 2: Factory Method

The real fix is to eliminate the if block entirely. Instead of a separate factory deciding which query to create — each database knows how to create its own query.

Add create_query as an abstract method on Database. Each subclass implements it and returns the right query for its family:

class Database(ABC):
    @abstractmethod
    def create_connection(self): pass

    @abstractmethod
    def create_connection_pool(self): pass

    @abstractmethod
    def replication(self): pass

    @abstractmethod
    def create_query(self): pass  # ← the factory method


class Mysql(Database):
    def create_connection(self):
        print("Creating database connection for MySQL")

    def create_connection_pool(self):
        print("Creating database connection pool for MySQL")

    def replication(self):
        print("Managing replication of MySQL database")

    def create_query(self):
        return SqlQuery()  # MySQL knows it needs SqlQuery


class PgSQL(Database):
    def create_connection(self):
        print("Creating database connection for PostgreSQL")

    def create_connection_pool(self):
        print("Creating database connection pool for PostgreSQL")

    def replication(self):
        print("Managing replication of PostgreSQL database")

    def create_query(self):
        return SqlQuery()  # PostgreSQL also uses SqlQuery


class MongoDB(Database):
    def create_connection(self):
        print("Creating database connection for MongoDB")

    def create_connection_pool(self):
        print("Creating database connection pool for MongoDB")

    def replication(self):
        print("Managing replication of MongoDB database")

    def create_query(self):
        return MongoQuery()  # MongoDB knows it needs MongoQuery


class Query(ABC): pass
class SqlQuery(Query): pass
class MongoQuery(Query): pass


class UserService:
    def create_user(self, db: Database):
        return db.create_query()  # no isinstance, no if blocks

No isinstance. No if blocks. UserService just calls db.create_query() and polymorphism handles the rest.

Adding Cassandra tomorrow? Create a new Cassandra class, implement create_query(), done. Zero changes to UserService or any existing class. OCP satisfied.

class CassandraQuery(Query): pass

class Cassandra(Database):
    def create_connection(self):
        print("Creating database connection for Cassandra")

    def create_connection_pool(self):
        print("Creating database connection pool for Cassandra")

    def replication(self):
        print("Managing replication of Cassandra database")

    def create_query(self):
        return CassandraQuery()

# UserService works with zero changes
print(type(UserService().create_user(Cassandra())).__name__)  # CassandraQuery

What Factory Method gives you:

✅ SRP fixed
✅ OCP satisfied — new databases don't touch existing code
✅ No if blocks — polymorphism does the work

What Factory Method doesn't give you:

❌ What if each database needs to create not just a query, but also a transaction handler, an updator, a migration runner? Dumping all of these as abstract methods on Database creates a fat interface — an Interface Segregation Principle violation. Classes that don't support transactions are forced to implement them anyway.

Step 3: Abstract Factory

When you have a family of related objects that must be consistent with each other — query, transaction, updator all from the same database ecosystem — Abstract Factory is the answer.

Instead of adding more abstract methods to Database, we give each database one method: create_factory(). It returns a factory specific to that database. The factory then produces the entire family of related objects:

from abc import ABC, abstractmethod


# ── Product families ──────────────────────────────────────────

class Query(ABC): pass
class SqlQuery(Query): pass
class MongoQuery(Query): pass

class Transaction(ABC): pass
class SqlTransaction(Transaction): pass
class NoSqlTransaction(Transaction): pass

class Updator(ABC): pass
class SqlUpdator(Updator): pass
class NoSqlUpdator(Updator): pass


# ── Abstract Factory ──────────────────────────────────────────

class AbstractFactory(ABC):
    @abstractmethod
    def create_query(self): pass

    @abstractmethod
    def create_transaction(self): pass

    @abstractmethod
    def create_updator(self): pass


# ── Concrete Factories ────────────────────────────────────────

class MysqlFactory(AbstractFactory):
    def create_query(self):
        return SqlQuery()

    def create_transaction(self):
        return SqlTransaction()

    def create_updator(self):
        return SqlUpdator()


class PgsqlFactory(AbstractFactory):
    def create_query(self):
        return SqlQuery()

    def create_transaction(self):
        return SqlTransaction()

    def create_updator(self):
        return SqlUpdator()


class MongodbFactory(AbstractFactory):
    def create_query(self):
        return MongoQuery()

    def create_transaction(self):
        return NoSqlTransaction()

    def create_updator(self):
        return NoSqlUpdator()


# ── Database hierarchy ────────────────────────────────────────

class Database(ABC):
    @abstractmethod
    def create_connection(self): pass

    @abstractmethod
    def create_connection_pool(self): pass

    @abstractmethod
    def replication(self): pass

    @abstractmethod
    def create_factory(self): pass  # ← one method, returns the whole family


class Mysql(Database):
    def create_connection(self):
        print("Creating database connection for MySQL")

    def create_connection_pool(self):
        print("Creating database connection pool for MySQL")

    def replication(self):
        print("Managing replication of MySQL database")

    def create_factory(self):
        return MysqlFactory()


class PgSQL(Database):
    def create_connection(self):
        print("Creating database connection for PostgreSQL")

    def create_connection_pool(self):
        print("Creating database connection pool for PostgreSQL")

    def replication(self):
        print("Managing replication of PostgreSQL database")

    def create_factory(self):
        return PgsqlFactory()


class MongoDB(Database):
    def create_connection(self):
        print("Creating database connection for MongoDB")

    def create_connection_pool(self):
        print("Creating database connection pool for MongoDB")

    def replication(self):
        print("Managing replication of MongoDB database")

    def create_factory(self):
        return MongodbFactory()


# ── Services ──────────────────────────────────────────────────

class UserService:
    def create_user(self, db: Database):
        factory = db.create_factory()
        return factory.create_query()


class TransactionService:
    def create_transaction(self, db: Database):
        factory = db.create_factory()
        return factory.create_transaction()


class UpdaterService:
    def create_updator(self, db: Database):
        factory = db.create_factory()
        return factory.create_updator()

Every service gets a factory from the database, then asks the factory for what it needs. The factory guarantees consistency — you'll never accidentally get a MongoQuery paired with a SqlTransaction.

Adding a New Database Family

Cassandra comes along. Zero changes to existing code:

class CassandraQuery(Query): pass
class CassandraTransaction(Transaction): pass
class CassandraUpdator(Updator): pass

class CassandraFactory(AbstractFactory):
    def create_query(self):
        return CassandraQuery()

    def create_transaction(self):
        return CassandraTransaction()

    def create_updator(self):
        return CassandraUpdator()

class Cassandra(Database):
    def create_connection(self):
        print("Creating database connection for Cassandra")

    def create_connection_pool(self):
        print("Creating database connection pool for Cassandra")

    def replication(self):
        print("Managing replication of Cassandra database")

    def create_factory(self):
        return CassandraFactory()


# All services work immediately — zero existing code touched
print(type(UserService().create_user(Cassandra())).__name__)          # CassandraQuery
print(type(TransactionService().create_transaction(Cassandra())).__name__)  # CassandraTransaction
print(type(UpdaterService().create_updator(Cassandra())).__name__)    # CassandraUpdator

The Progression — Why Each Pattern Exists

Pattern	What it solved	What it left broken
No pattern — `isinstance` in `UserService`	Nothing	SRP + OCP violated
Simple Factory — `DatabaseFactory` class	SRP fixed in `UserService`	OCP still violated inside factory
Factory Method — `create_query` on each DB	OCP fixed, no `if` blocks	Fat interface — ISP violated as methods grow
Abstract Factory — family of factories	ISP fixed, families consistent	Nothing — clean ✅

Each pattern solves the problem the previous one left behind. This is the progression you apply in the real world — start simple, upgrade when the pain demands it.

When to Use Each

Simple Factory — when object creation logic is straightforward and new types are unlikely. Centralises creation but accepts the OCP tradeoff. Good for small, stable systems.

Factory Method — when you have one product to create per type and want to eliminate if/else through polymorphism. Each subclass decides what it creates. Best when each class in the hierarchy creates exactly one related object.

Abstract Factory — when you have a family of related objects that must be consistent with each other, and new families might be introduced. Guarantees that objects from the same family always work together correctly.

One product per type?
    └── Factory Method

A family of related products per type?
    └── Abstract Factory

Simple, unlikely to change?
    └── Simple Factory

The Tradeoffs

Simple Factory

✅ Easy to understand, centralised creation
❌ OCP violated — every new type modifies the factory
❌ Factory grows indefinitely as types are added

Factory Method

✅ OCP satisfied — new types don't touch existing code
✅ No if blocks — polymorphism handles dispatch
❌ Fat interface risk — adding more products pollutes the base class
❌ Each subclass tightly coupled to its product type

Abstract Factory

✅ Families are consistent — no accidental mixing of SQL and NoSQL objects
✅ OCP fully satisfied — new families are entirely new classes
✅ ISP respected — Database has one factory method, not many product methods
❌ Most complex — more classes, more files
❌ Adding a new product to the family (e.g. create_migration) requires changes to every concrete factory — OCP violation within the family
❌ Overkill for simple systems with one or two object types

The SOLID Connection

Factory patterns are SOLID in action:

SRP — UserService creates users. DatabaseFactory or the concrete factory creates objects. One responsibility each.

OCP — Factory Method and Abstract Factory let you add new database types without touching existing classes. New family = new classes only.

LSP — UserService works with any Database subclass interchangeably. TransactionService works with any factory that implements AbstractFactory. Substitution guaranteed.

ISP — Abstract Factory avoids dumping all product creation methods on Database. One method — create_factory() — returns a focused factory interface.

DIP — UserService depends on Database and AbstractFactory abstractions, not on Mysql or MysqlFactory concretions. Swap the database, the service never changes.

Never Create an Invalid Object Again — The Builder Pattern

Madhukar Vissapragada — Wed, 22 Jul 2026 16:03:51 +0000

A real story from building a manuscript submission system at a scientific publishing company.

We were building a system at a Publishing Company that accepts a research manuscript and sends it through an automated scientific publishing pipeline.

Then we had to write the class that an API calls to create a submission.

class ManuscriptSubmissionService:
    def __init__(self, title, abstract, authors, affiliations, keywords,
                 references, funding, ethics, conflicts,
                 supplementary_files, cover_letter, supporting_files,
                 manuscript_attachment):
        self.title = title
        self.abstract = abstract
        self.authors = authors
        self.affiliations = affiliations
        self.keywords = keywords
        self.references = references
        self.funding = funding
        self.ethics = ethics
        self.conflicts = conflicts
        self.supplementary_files = supplementary_files
        self.cover_letter = cover_letter
        self.supporting_files = supporting_files
        self.manuscript_attachment = manuscript_attachment

And creating an object looked like this:

submission = ManuscriptSubmissionService(
    "Covid-19 study",
    "some random abstract goes here",
    "a1, a2, a3",
    "aff1, aff2, aff3",
    "keyword1, keyword2",
    "references1, references2",
    "funding1",
    "ethic1",
    "conflict1",
    "supplementary1",
    "manuscript1",
    "supporting_file1",
    "manuscript_attachment1",
)

Look at that. Thirteen positional arguments. No context. No idea what the fourth parameter is without scrolling back up to the constructor definition every single time.

This is called the monster constructor problem — one init that keeps growing until nobody can read it.

Fix 1: Named Parameters

The first instinct is to use named parameters with defaults:

class ManuscriptSubmissionService:
    def __init__(self, title: str = None, abstract: str = None,
                 authors: list = None, affiliations: list = None,
                 keywords: list = None, references: list = None,
                 funding: str = None, ethics: str = None,
                 conflicts: str = None, supplementary_files: list = None,
                 cover_letter: str = None, supporting_files: list = None,
                 manuscript_attachments: list = None):
        self.title = title
        self.abstract = abstract
        self.authors = authors
        self.affiliations = affiliations
        self.keywords = keywords
        self.references = references
        self.funding = funding
        self.ethics = ethics
        self.conflicts = conflicts
        self.supplementary_files = supplementary_files
        self.cover_letter = cover_letter
        self.supporting_files = supporting_files
        self.manuscript_attachments = manuscript_attachments


submission = ManuscriptSubmissionService(
    title="Covid-19 study",
    abstract="some random abstract goes here",
    authors="a1, a2, a3",
    affiliations="aff1, aff2, aff3",
)

This looks cleaner at the call site. But now everything is optional — None by default. A researcher can submit a manuscript with no title, no authors, no actual manuscript file. The system accepts it silently and breaks somewhere downstream.

The problem: no mandatory field enforcement.

Fix 2: Validation Inside the Constructor

Okay, so add validation:

class ManuscriptSubmissionService:
    def __init__(self, title: str = None, abstract: str = None,
                 authors: list = None, affiliations: list = None,
                 keywords: list = None, references: list = None,
                 funding: str = None, ethics: str = None,
                 conflicts: str = None, supplementary_files: list = None,
                 cover_letter: str = None, supporting_files: list = None,
                 manuscript_attachments: list = None):
        if title is None:
            raise IOError("ManuscriptSubmissionService requires a title")
        if abstract is None:
            raise IOError("ManuscriptSubmissionService requires an abstract")
        if not authors:
            raise IOError("ManuscriptSubmissionService requires authors")
        if not affiliations:
            raise IOError("ManuscriptSubmissionService requires affiliations")
        if not manuscript_attachments:
            raise IOError("ManuscriptSubmissionService requires a manuscript attachment")

        self.title = title
        self.abstract = abstract
        self.authors = authors
        self.affiliations = affiliations
        self.keywords = keywords
        self.references = references
        self.funding = funding
        self.ethics = ethics
        self.conflicts = conflicts
        self.supplementary_files = supplementary_files
        self.cover_letter = cover_letter
        self.supporting_files = supporting_files
        self.manuscript_attachments = manuscript_attachments

This looks like it works. But stop and think about what the constructor is doing now.

It's validating the input AND initialising the object's state. Two responsibilities. One method.

That's a Single Responsibility Principle violation.

And there's a deeper problem hiding here. By the time validation runs, the object already exists in memory. Python allocated space for it the moment ManuscriptSubmissionService(...) was called. You're validating an object that's already been born — and potentially destroying it right after.

An invalid manuscript should never exist in the first place.

Fix 3: Setters

What about an empty constructor and setters?

class ManuscriptSubmissionService:
    def __init__(self):
        self.title = None
        self.abstract = None
        self.authors = []
        self.affiliations = []
        self.keywords = []
        self.references = []
        self.funding = None
        self.ethics = None
        self.conflicts = None
        self.supplementary_files = []
        self.cover_letter = None
        self.supporting_files = []
        self.manuscript_attachments = []

    def set_title(self, title: str):
        self.title = title
        return self

    def set_abstract(self, abstract: str):
        self.abstract = abstract
        return self

    def set_author(self, author: str):
        self.authors.append(author)
        return self

    def set_affiliation(self, affiliation: str):
        self.affiliations.append(affiliation)
        return self

    def set_keyword(self, keyword: str):
        self.keywords.append(keyword)
        return self

    def set_references(self, reference: str):
        self.references.append(reference)
        return self

    def set_funding(self, funding: str):
        self.funding = funding
        return self

    def set_ethics(self, ethics: str):
        self.ethics = ethics
        return self

    def set_conflict(self, conflict: str):
        self.conflicts = conflict
        return self

    def set_supplementary_files(self, supplementary_file: str):
        self.supplementary_files.append(supplementary_file)
        return self

    def set_cover_letter(self, cover_letter: str):
        self.cover_letter = cover_letter
        return self

    def set_supporting_files(self, supporting_file: str):
        self.supporting_files.append(supporting_file)
        return self

    def set_manuscript_attachment(self, manuscript_attachment: str):
        self.manuscript_attachments.append(manuscript_attachment)
        return self

    def validate(self):
        if self.title is None:
            raise IOError("ManuscriptSubmissionService requires a title")
        if self.abstract is None:
            raise IOError("ManuscriptSubmissionService requires an abstract")
        if len(self.authors) == 0:
            raise IOError("ManuscriptSubmissionService requires authors")
        if len(self.affiliations) == 0:
            raise IOError("ManuscriptSubmissionService requires affiliations")
        if len(self.manuscript_attachments) == 0:
            raise IOError("ManuscriptSubmissionService requires a manuscript attachment")


# Usage
submission = ManuscriptSubmissionService()
submission.set_title("Covid-19 study")
submission.set_abstract("This paper studies...")
submission.set_author("Dr. Smith")
submission.set_affiliation("Oxford University")
submission.set_manuscript_attachment("covid19_paper.pdf")
submission.validate()

Now the object exists with no data. Nothing stops you from calling send_to_pipeline(submission) before calling any setters. The half-built object silently enters the publishing pipeline and breaks somewhere downstream.

The problem: object exists in an invalid state before validate() is ever called.

Three Approaches. Three Failures.

Approach	Problem
Monster constructor	Unreadable, positional confusion
Named params + validation in `__init__`	SRP violation, object born before validation
Setters	Invalid object state, nothing enforced

None of them fully solve it. What we actually need is a system that builds the object step by step and only creates it in memory when everything is in place.

This is exactly where the Builder pattern comes in.

What Is the Builder Pattern?

Builder is a creational design pattern — it falls under the umbrella of patterns that control how objects are created.

Its job: separate the construction and validation of an object from its representation. An object should only come to life when it has everything it needs.

Two classes. One job each:

ManuscriptSubmissionService — holds data. Nothing else.
ManuscriptBuilder — sets values, validates, and only then creates the object.

Building It Step by Step

Step 1: Separate the Classes

ManuscriptSubmissionService.__init__ does exactly one thing — stores what it receives. No validation. No logic. One responsibility.

class ManuscriptSubmissionService:
    def __init__(self, title: str, abstract: str, authors: list,
                 affiliations: list, keywords: list, references: list,
                 funding: str, ethics: str, conflicts: str,
                 supplementary_files: list, cover_letter: str,
                 supporting_files: list, manuscript_attachments: list):
        # just stores data — nothing else
        self.title = title
        self.abstract = abstract
        self.authors = authors
        self.affiliations = affiliations
        self.keywords = keywords
        self.references = references
        self.funding = funding
        self.ethics = ethics
        self.conflicts = conflicts
        self.supplementary_files = supplementary_files
        self.cover_letter = cover_letter
        self.supporting_files = supporting_files
        self.manuscript_attachments = manuscript_attachments

    @staticmethod
    def builder():
        return ManuscriptSubmissionService.ManuscriptBuilder()

Step 2: The Builder with Method Chaining

Every setter returns self. This enables method chaining — calling multiple setters in one readable fluent line.

Also notice: the builder initialises all fields to None or empty lists. This way, if someone calls build() without setting a field, our validation runs correctly — no AttributeError, just a clean IOError.

    class ManuscriptBuilder:
        def __init__(self):
            self.title = None
            self.abstract = None
            self.authors = []
            self.affiliations = []
            self.keywords = []
            self.references = []
            self.funding = None
            self.ethics = None
            self.conflicts = None
            self.supplementary_files = []
            self.cover_letter = None
            self.supporting_files = []
            self.manuscript_attachments = []

        def set_title(self, title: str):
            self.title = title
            return self

        def set_abstract(self, abstract: str):
            self.abstract = abstract
            return self

        def set_author(self, author: str):
            self.authors.append(author)
            return self

        def set_affiliation(self, affiliation: str):
            self.affiliations.append(affiliation)
            return self

        def set_keyword(self, keyword: str):
            self.keywords.append(keyword)
            return self

        def set_references(self, reference: str):
            self.references.append(reference)
            return self

        def set_funding(self, funding: str):
            self.funding = funding
            return self

        def set_ethics(self, ethics: str):
            self.ethics = ethics
            return self

        def set_conflict(self, conflict: str):
            self.conflicts = conflict
            return self

        def set_supplementary_files(self, supplementary_file: str):
            self.supplementary_files.append(supplementary_file)
            return self

        def set_cover_letter(self, cover_letter: str):
            self.cover_letter = cover_letter
            return self

        def set_supporting_files(self, supporting_file: str):
            self.supporting_files.append(supporting_file)
            return self

        def set_manuscript_attachment(self, manuscript_attachment: str):
            self.manuscript_attachments.append(manuscript_attachment)
            return self

Step 3: `build()` — Validate First, Create Second

This is the heart of the pattern. Validation happens entirely inside build() — before ManuscriptSubmissionService(...) is ever called. If validation fails, the object is never created. Not even for a millisecond.

        def build(self):
            if self.title is None:
                raise IOError("ManuscriptSubmissionService requires a title")
            if self.abstract is None:
                raise IOError("ManuscriptSubmissionService requires an abstract")
            if len(self.authors) == 0:
                raise IOError("ManuscriptSubmissionService requires authors")
            if len(self.affiliations) == 0:
                raise IOError("ManuscriptSubmissionService requires affiliations")
            if len(self.manuscript_attachments) == 0:
                raise IOError("ManuscriptSubmissionService requires a manuscript attachment")

            # only NOW does the object get created
            return ManuscriptSubmissionService(
                self.title, self.abstract, self.authors, self.affiliations,
                self.keywords, self.references, self.funding, self.ethics,
                self.conflicts, self.supplementary_files, self.cover_letter,
                self.supporting_files, self.manuscript_attachments
            )

Step 4: Block Direct Instantiation

There's still a loophole. Nothing stops someone from bypassing the builder entirely:

# bypasses all validation — object created in invalid state
submission = ManuscriptSubmissionService(None, None, [], [], [], [], None, None, None, [], None, [], [])

Python doesn't support private constructors. But we can enforce it with a UUID token and a custom exception:

from uuid import uuid4, UUID


class InitializationError(Exception):
    """Raised when ManuscriptSubmissionService is instantiated directly instead of via builder."""
    def __init__(self, message: str):
        super().__init__(message)


class ManuscriptSubmissionService:
    _Builder_token = uuid4()  # generated once at class definition time

    def __init__(self, token_: UUID, title: str, ...):
        if token_ != self._Builder_token:
            raise InitializationError(
                "ManuscriptSubmissionService cannot be initialized directly. "
                "Use ManuscriptSubmissionService.builder()"
            )
        # rest of init...

The token is generated once when the class is defined. The builder knows it. Nobody outside does. Direct instantiation raises InitializationError immediately.

Why a custom exception instead of ValueError? In production, specific exceptions mean:

Easier debugging — you know exactly what failed
Callers can catch InitializationError specifically
Cleaner, more descriptive logs

The Complete Implementation

from uuid import uuid4, UUID


class InitializationError(Exception):
    """Raised when ManuscriptSubmissionService is instantiated directly instead of via builder."""
    def __init__(self, message: str):
        super().__init__(message)


class ManuscriptSubmissionService:
    _Builder_token = uuid4()

    def __init__(self, token_: UUID, title: str, abstract: str, authors: list,
                 affiliations: list, keywords: list, references: list,
                 funding: str, ethics: str, conflicts: str,
                 supplementary_files: list, cover_letter: str,
                 supporting_files: list, manuscript_attachments: list):
        if token_ != self._Builder_token:
            raise InitializationError(
                "ManuscriptSubmissionService cannot be initialized directly. "
                "Use ManuscriptSubmissionService.builder()"
            )
        self.title = title
        self.abstract = abstract
        self.authors = authors
        self.affiliations = affiliations
        self.keywords = keywords
        self.references = references
        self.funding = funding
        self.ethics = ethics
        self.conflicts = conflicts
        self.supplementary_files = supplementary_files
        self.cover_letter = cover_letter
        self.supporting_files = supporting_files
        self.manuscript_attachments = manuscript_attachments

    @staticmethod
    def builder():
        return ManuscriptSubmissionService.ManuscriptBuilder()

    class ManuscriptBuilder:
        def __init__(self):
            self.title = None
            self.abstract = None
            self.authors = []
            self.affiliations = []
            self.keywords = []
            self.references = []
            self.funding = None
            self.ethics = None
            self.conflicts = None
            self.supplementary_files = []
            self.cover_letter = None
            self.supporting_files = []
            self.manuscript_attachments = []

        def set_title(self, title: str):
            self.title = title
            return self

        def set_abstract(self, abstract: str):
            self.abstract = abstract
            return self

        def set_author(self, author: str):
            self.authors.append(author)
            return self

        def set_affiliation(self, affiliation: str):
            self.affiliations.append(affiliation)
            return self

        def set_keyword(self, keyword: str):
            self.keywords.append(keyword)
            return self

        def set_references(self, reference: str):
            self.references.append(reference)
            return self

        def set_funding(self, funding: str):
            self.funding = funding
            return self

        def set_ethics(self, ethics: str):
            self.ethics = ethics
            return self

        def set_conflict(self, conflict: str):
            self.conflicts = conflict
            return self

        def set_supplementary_files(self, supplementary_file: str):
            self.supplementary_files.append(supplementary_file)
            return self

        def set_cover_letter(self, cover_letter: str):
            self.cover_letter = cover_letter
            return self

        def set_supporting_files(self, supporting_file: str):
            self.supporting_files.append(supporting_file)
            return self

        def set_manuscript_attachment(self, manuscript_attachment: str):
            self.manuscript_attachments.append(manuscript_attachment)
            return self

        def build(self):
            if self.title is None:
                raise IOError("ManuscriptSubmissionService requires a title")
            if self.abstract is None:
                raise IOError("ManuscriptSubmissionService requires an abstract")
            if len(self.authors) == 0:
                raise IOError("ManuscriptSubmissionService requires authors")
            if len(self.affiliations) == 0:
                raise IOError("ManuscriptSubmissionService requires affiliations")
            if len(self.manuscript_attachments) == 0:
                raise IOError("ManuscriptSubmissionService requires a manuscript attachment")

            return ManuscriptSubmissionService(
                ManuscriptSubmissionService._Builder_token,
                self.title, self.abstract, self.authors, self.affiliations,
                self.keywords, self.references, self.funding, self.ethics,
                self.conflicts, self.supplementary_files, self.cover_letter,
                self.supporting_files, self.manuscript_attachments
            )

Usage — Plain English at the Call Site

submission = (
    ManuscriptSubmissionService.builder()
        .set_title("Covid-19 and its effects on respiratory systems")
        .set_abstract("This paper studies the long-term effects of Covid-19...")
        .set_author("Dr. Smith")
        .set_author("Dr. Jones")
        .set_affiliation("Oxford University")
        .set_affiliation("Imperial College London")
        .set_keyword("covid")
        .set_keyword("pandemic")
        .set_keyword("respiratory")
        .set_funding("WHO Grant 2023")
        .set_manuscript_attachment("covid19_paper.pdf")
        .build()
)

print(submission.title)    # Covid-19 and its effects on respiratory systems
print(submission.authors)  # ['Dr. Smith', 'Dr. Jones']

The Director — Presets for Known Configurations

Builder has an optional companion — the Director. It doesn't build anything itself. It just knows the right combination of steps to create commonly used presets.

we had different submission types — standard journal, fast-track, open access. Each had different default configurations. Instead of copy-pasting builder chains everywhere, the Director encapsulates those presets.

The Director should get a fresh builder for every preset call — not reuse the same builder instance, which would cause state pollution across calls.

class ManuscriptDirector:
    def __init__(self, builder):
        self.__builder = builder

    def standard_submission(self):
        return self.__builder().set_ethics("standard-ethics-declaration").set_conflict("no-conflicts-declared")

    def fast_track_submission(self):
        return self.__builder().set_ethics("expedited-ethics").set_cover_letter("fast-track-request-letter")


    def open_access_submission(self):
        return self.__builder().set_funding("open-access-fund-2024").set_ethics("standard-ethics-declaration")


director = ManuscriptDirector(ManuscriptSubmissionService.builder)

submission = (
    director.standard_submission()
        .set_title("Effects of Climate Change on Biodiversity")
        .set_abstract("This paper explores...")
        .set_author("Dr. Patel")
        .set_affiliation("Cambridge University")
        .set_manuscript_attachment("climate_paper.pdf")
        .build()
)

When do you need a Director? When you have multiple known configurations of the same object and you want a single place to manage those presets. When you only have one configuration — skip it. Don't over-engineer.

The Tradeoffs

What Builder Gives You

✅ Readable object creation
✅ Mandatory field enforcement
✅ No SRP violation
✅ Object never exists in an invalid state
✅ Optional fields with sensible defaults in the builder
✅ Method chaining

What Builder Costs You

1. Boilerplate — the OCP violation

Every new mandatory field means changes in 5 places:

ManuscriptSubmissionService.__init__ — add the parameter
ManuscriptBuilder.__init__ — add default None
Add a new setter method
Add validation in build()
Pass it when calling ManuscriptSubmissionService(...)

This is an Open/Closed Principle violation — adding a field forces modification of existing code in multiple places.

2. More Code for Simple Cases

A class with 2-3 fields doesn't need a Builder. You've added a nested class, a static method, and 3 setters for what could have been a simple constructor with keyword arguments. Apply Builder when the complexity justifies it.

3. Direct Instantiation is Not Truly Private

The UUID token trick works in practice, but it's a convention enforced at runtime — not a language feature. Python doesn't support private constructors. A determined developer can inspect ManuscriptSubmissionService._Builder_token and bypass the guard. This is an accepted limitation of the pattern in Python.

5. No Compile-Time Safety

Unlike Java or Kotlin where you can enforce mandatory fields at compile time, Python's Builder enforcement is entirely at runtime. A missing mandatory field only surfaces when build() is called — not when the setter is forgotten. Type checkers and tests help, but they don't eliminate the gap.

SOLID Design Principles: Stop Writing Code That Breaks When You Touch It

Madhukar Vissapragada — Wed, 22 Jul 2026 12:26:17 +0000

What is SOLID?

SOLID is a set of software design guidelines — not hard rules, but principles that guide how we organise our code.

The goal is simple: as your codebase grows and your team scales, things should get easier to change, not harder. SOLID is what makes that possible.

Five principles. One goal. Let's walk through each one with a real, working example.

The Example

We're building an order processing system for a ticket marketplace. When a customer buys a ticket, the system needs to:

Process the payment
Save the order to the database
Send a confirmation to the buyer
Generate an invoice

There are three order types — Standard, VIP (with SMS notification), and Resale (with seller notification).

We'll start with the naive implementation and fix it one principle at a time.

The Naive Version

One class. Everything inside it. No abstractions, no separation.

import enum
import uuid
from dataclasses import dataclass

class OrderType(enum.Enum):
    STANDARD = 1
    VIP = 2
    RESALE = 3

@dataclass
class Order:
    event_name: str
    start_seat: str
    end_seat: str
    order_type: int
    customer_id: uuid.UUID
    seller_id: uuid.UUID
    seller_email: str
    order_id: uuid.UUID = uuid.uuid4()


class OrderProcessingSystem:
    def save_order(self, order: Order):
        print(f"Saving order {order.order_id} to database")

    def process_payment(self, order: Order):
        print(f"Processing payment for order {order.order_id}")

    def send_confirmation(self, order: Order):
        print(f"Sending confirmation for order {order.order_id}")

    def generate_invoice(self, order: Order):
        print(f"Generating invoice for order {order.order_id}")

    def process(self, order: Order):
        self.process_payment(order)
        self.save_order(order)
        self.send_confirmation(order)
        self.generate_invoice(order)

This works. But as requirements grow, this class becomes a nightmare to maintain. Let's fix it, one principle at a time.

S — Single Responsibility Principle

A class, function, or method should have one and only one reason to change.

OrderProcessingSystem has four responsibilities — payment, persistence, confirmation, and invoice generation. That's four reasons to change. If the invoice format changes, you touch this class. If the payment gateway changes, you touch this class. If the email template changes, you touch this class.

The fix — split into focused classes:

import enum
import uuid
from dataclasses import dataclass

class OrderType(enum.Enum):
    STANDARD = 1
    VIP = 2
    RESALE = 3

@dataclass
class Order:
    event_name: str
    start_seat: str
    end_seat: str
    order_type: int
    customer_id: uuid.UUID
    seller_id: uuid.UUID
    seller_email: str
    order_id: uuid.UUID = uuid.uuid4()


class InventoryManager:
    def save_order(self, order: Order):
        print(f"Save order {order.order_id} for customer {order.customer_id}")


class PaymentManager:
    def process_payment(self, order: Order):
        print(f"Process payment for order {order.order_id}")


class InvoiceGenerator:
    def generate_invoice(self, order: Order):
        print(f"Generate invoice for order {order.order_id}")


class TicketConfirmation:
    def send_confirmation(self, order: Order):
        print(f"Send confirmation for order {order.order_id} to customer {order.customer_id}")


class OrderProcessor:
    def process(self, order: Order):
        PaymentManager().process_payment(order)
        InventoryManager().save_order(order)
        TicketConfirmation().send_confirmation(order)
        InvoiceGenerator().generate_invoice(order)

Now each class has one responsibility and one reason to change. OrderProcessor is a clean orchestrator — it coordinates the flow but holds no logic itself.

O — Open/Closed Principle

A class should be open for extension but closed for modification.

Our three order types have different flows:

Standard — payment, save, confirmation, invoice
VIP — all of the above + SMS notification
Resale — all of the above + notify the seller

The naive fix is if/else blocks inside OrderProcessor.process():

def process(self, order: Order):
    if order.order_type == 1:
        # standard flow
    elif order.order_type == 2:
        # VIP flow
    elif order.order_type == 3:
        # resale flow

Every new order type means opening OrderProcessor and adding another elif. That's an OCP violation — you're modifying existing, working code to add new behaviour.

The fix — an abstract base class and a type map:

from abc import ABC, abstractmethod

class OrderCategorySchema(ABC):
    @abstractmethod
    def payment_processor(self, order: Order): pass

    @abstractmethod
    def save_order(self, order: Order): pass

    @abstractmethod
    def send_confirmation(self, order: Order): pass

    @abstractmethod
    def generate_invoice(self, order: Order): pass

    def process(self, order: Order):
        self.payment_processor(order)
        self.save_order(order)
        self.send_confirmation(order)
        self.generate_invoice(order)


class StandardOrder(OrderCategorySchema):
    def payment_processor(self, order): PaymentManager().process_payment(order)
    def save_order(self, order): InventoryManager().save_order(order)
    def send_confirmation(self, order): TicketConfirmation().send_confirmation(order)
    def generate_invoice(self, order): InvoiceGenerator().generate_invoice(order)


class VipOrder(OrderCategorySchema):
    def payment_processor(self, order): PaymentManager().process_payment(order)
    def save_order(self, order): InventoryManager().save_order(order)
    def send_confirmation(self, order): TicketConfirmation().send_confirmation(order)
    def generate_invoice(self, order): InvoiceGenerator().generate_invoice(order)

    def process(self, order: Order):
        self.payment_processor(order)
        self.save_order(order)
        self.send_confirmation(order)
        print(f"Sending SMS to customer {order.customer_id}")
        self.generate_invoice(order)


class ResaleOrder(OrderCategorySchema):
    def payment_processor(self, order): PaymentManager().process_payment(order)
    def save_order(self, order): InventoryManager().save_order(order)
    def send_confirmation(self, order): TicketConfirmation().send_confirmation(order)
    def generate_invoice(self, order): InvoiceGenerator().generate_invoice(order)

    def process(self, order: Order):
        self.payment_processor(order)
        self.save_order(order)
        self.send_confirmation(order)
        print(f"Notifying seller {order.seller_id} at {order.seller_email}")
        self.generate_invoice(order)


type_map = {
    1: StandardOrder,
    2: VipOrder,
    3: ResaleOrder
}


class OrderProcessor:
    def process(self, order: Order):
        order_class = type_map[order.order_type]
        order_class().process(order)

Adding a new order type tomorrow is just a new class and one entry in type_map. OrderProcessor never changes.

L — Liskov Substitution Principle

A child class should be fully substitutable for its parent. Wherever you use the parent, the child must work correctly — no surprises, no broken contracts.

With our current implementation, OrderProcessor calls process() on whatever OrderCategorySchema subclass it receives. Let's verify all three are truly substitutable:

schemas = [StandardOrder(), VipOrder(), ResaleOrder()]
order = Order('Event', 'A1', 'A2', 1, uuid.uuid4(), uuid.uuid4(), 'seller@test.com')

for schema in schemas:
    schema.process(order)  # all three work correctly — LSP satisfied ✅

LSP is violated when a subclass throws NotImplementedError, silently does nothing, or changes the behaviour a caller depends on. The classic example is a Penguin inheriting from a Bird class that has a fly() method. Penguins can't fly — so Penguin.fly() either crashes or does nothing. The contract is broken.

In our case, every order type honours the process() contract. LSP satisfied.

I — Interface Segregation Principle

An interface should only contain methods that are genuinely related to each other.

Imagine a new order type arrives — DigitalTicketOrder. It's an online-only ticket. No physical seat, no PDF invoice needed.

With our current OrderCategorySchema, DigitalTicketOrder is forced to implement generate_invoice() even though it has no business generating one. That's an ISP violation — the interface has a method that not all implementors need.

The fix — split into focused interfaces:

from abc import ABC, abstractmethod

class Notificator(ABC):
    @abstractmethod
    def notify(self, order: Order): pass

class SMSNotification(Notificator):
    def notify(self, order: Order):
        print(f"Send SMS to customer {order.customer_id}")

class NotifySeller(Notificator):
    def notify(self, order: Order):
        print(f"Notify seller {order.seller_id} at {order.seller_email}")


class Invoiceable(ABC):
    @abstractmethod
    def generate_invoice(self, order: Order): pass

class PDFInvoiceGenerator(Invoiceable):
    def generate_invoice(self, order: Order):
        print(f"Generate PDF invoice for order {order.order_id}")


class TicketConfirmation(ABC):
    @abstractmethod
    def send_confirmation(self, order: Order): pass

class EmailTicketConfirmation(TicketConfirmation):
    def send_confirmation(self, order: Order):
        print(f"Email confirmation for order {order.order_id} to customer {order.customer_id}")

class WhatsappTicketConfirmation(TicketConfirmation):
    def send_confirmation(self, order: Order):
        print(f"WhatsApp confirmation for order {order.order_id} to customer {order.customer_id}")


class OrderCategorySchema(ABC):
    @abstractmethod
    def save_order(self, order: Order): pass

    @abstractmethod
    def process(self, order: Order): pass


class StandardOrder(OrderCategorySchema, PDFInvoiceGenerator):
    def save_order(self, order): InventoryManager().save_order(order)
    def process(self, order):
        PaymentManager().process_payment(order)
        self.save_order(order)
        EmailTicketConfirmation().send_confirmation(order)
        self.generate_invoice(order)


class VipOrder(OrderCategorySchema, PDFInvoiceGenerator, SMSNotification):
    def save_order(self, order): InventoryManager().save_order(order)
    def process(self, order):
        PaymentManager().process_payment(order)
        self.save_order(order)
        EmailTicketConfirmation().send_confirmation(order)
        self.notify(order)
        self.generate_invoice(order)


class ResaleOrder(OrderCategorySchema, NotifySeller, PDFInvoiceGenerator):
    def save_order(self, order): InventoryManager().save_order(order)
    def process(self, order):
        PaymentManager().process_payment(order)
        self.save_order(order)
        WhatsappTicketConfirmation().send_confirmation(order)
        self.notify(order)
        self.generate_invoice(order)


# DigitalTicketOrder — no invoice needed, doesn't implement Invoiceable
class DigitalTicketOrder(OrderCategorySchema):
    def save_order(self, order): InventoryManager().save_order(order)
    def process(self, order):
        PaymentManager().process_payment(order)
        self.save_order(order)
        EmailTicketConfirmation().send_confirmation(order)
        # no invoice — and nothing forces it to generate one ✅

Each interface is focused and justified. Classes implement only what they need.

D — Dependency Inversion Principle

Classes should not depend directly on each other — they should both depend on an abstraction.

Look at what's still hardcoded inside the order classes:

PaymentManager().process_payment(order)       # concrete class
EmailTicketConfirmation().send_confirmation() # concrete class

If the payment gateway changes from Stripe to Razorpay, you touch every order class. If confirmation switches from email to WhatsApp, same story. These are concrete dependencies baked into business logic.

The fix — define abstractions and inject from outside:

from abc import ABC, abstractmethod
import enum
import uuid
from dataclasses import dataclass


class OrderType(enum.Enum):
    STANDARD = 1
    VIP = 2
    RESALE = 3


@dataclass
class Order:
    event_name: str
    start_seat: str
    end_seat: str
    order_type: int
    customer_id: uuid.UUID
    seller_id: uuid.UUID
    seller_email: str
    order_id: uuid.UUID = uuid.uuid4()


# ── Notification abstractions ─────────────────────────────────

class Notificator(ABC):
    @abstractmethod
    def notify(self, order: Order): pass

class SMSNotification(Notificator):
    def notify(self, order: Order):
        print(f"Send SMS to customer {order.customer_id}")

class NotifySeller(Notificator):
    def notify(self, order: Order):
        print(f"Notify seller {order.seller_id} at {order.seller_email}")


# ── Payment abstraction ───────────────────────────────────────

class PaymentService(ABC):
    @abstractmethod
    def process_payment(self, order: Order): pass

class StripeService(PaymentService):
    def process_payment(self, order: Order):
        print(f"Stripe: processing payment for order {order.order_id}")

class RazorPayService(PaymentService):
    def process_payment(self, order: Order):
        print(f"RazorPay: processing payment for order {order.order_id}")


# ── Inventory ─────────────────────────────────────────────────

class InventoryManager(ABC):
    @abstractmethod
    def save_order(self, order: Order): pass
    @abstractmethod
    def update_order(self, order: Order): pass
    @abstractmethod
    def delete_order(self, order: Order): pass
    @abstractmethod
    def create_order(self, order: Order): pass

class OrderManager(InventoryManager):
    def save_order(self, order: Order):
        print(f"Save order {order.order_id} for customer {order.customer_id}")
    def update_order(self, order: Order):
        print(f"Update order {order.order_id}")
    def delete_order(self, order: Order):
        print(f"Delete order {order.order_id}")
    def create_order(self, order: Order):
        print(f"Create order {order.order_id}")


# ── Invoice abstraction ───────────────────────────────────────

class Invoiceable(ABC):
    @abstractmethod
    def generate_invoice(self, order: Order): pass

class PDFInvoiceGenerator(Invoiceable):
    def generate_invoice(self, order: Order):
        print(f"Generate PDF invoice for order {order.order_id}")


# ── Confirmation abstraction ──────────────────────────────────

class TicketConfirmation(ABC):
    @abstractmethod
    def send_confirmation(self, order: Order): pass

class EmailTicketConfirmation(TicketConfirmation):
    def send_confirmation(self, order: Order):
        print(f"Email confirmation for order {order.order_id} to {order.customer_id}")

class WhatsappTicketConfirmation(TicketConfirmation):
    def send_confirmation(self, order: Order):
        print(f"WhatsApp confirmation for order {order.order_id} to {order.customer_id}")


# ── Order base ────────────────────────────────────────────────

class OrderCategorySchema(ABC):
    def __init__(self, payment_gateway: PaymentService, confirmation_manager: TicketConfirmation):
        self.payment_gateway = payment_gateway
        self.confirmation_manager = confirmation_manager

    @abstractmethod
    def save_order(self, order: Order): pass

    @abstractmethod
    def process(self, order: Order): pass


# ── Concrete order types ──────────────────────────────────────

class StandardOrder(OrderCategorySchema, PDFInvoiceGenerator):
    def save_order(self, order: Order):
        OrderManager().save_order(order)

    def process(self, order: Order):
        self.payment_gateway.process_payment(order)
        self.save_order(order)
        self.confirmation_manager.send_confirmation(order)
        self.generate_invoice(order)


class VipOrder(OrderCategorySchema, PDFInvoiceGenerator, SMSNotification):
    def save_order(self, order: Order):
        OrderManager().save_order(order)

    def process(self, order: Order):
        self.payment_gateway.process_payment(order)
        self.save_order(order)
        self.confirmation_manager.send_confirmation(order)
        self.notify(order)
        self.generate_invoice(order)


class ResaleOrder(OrderCategorySchema, NotifySeller, PDFInvoiceGenerator):
    def save_order(self, order: Order):
        OrderManager().save_order(order)

    def process(self, order: Order):
        self.payment_gateway.process_payment(order)
        self.save_order(order)
        self.confirmation_manager.send_confirmation(order)
        self.notify(order)
        self.generate_invoice(order)


# ── Wiring ────────────────────────────────────────────────────

type_map = {
    1: StandardOrder,
    2: VipOrder,
    3: ResaleOrder
}


class OrderProcessor:
    def process(self, order: Order):
        order_class = type_map[order.order_type]
        payment_service = RazorPayService()
        confirmation_manager = WhatsappTicketConfirmation()
        order_class(payment_service, confirmation_manager).process(order)

Switching from RazorPay to Stripe, or from WhatsApp to email confirmation, is two lines in OrderProcessor. Zero changes to any order class.

# Switch payment and confirmation — zero order class changes
payment_service = StripeService()
confirmation_manager = EmailTicketConfirmation()

OrderCategorySchema depends on PaymentService and TicketConfirmation abstractions — not on RazorPayService or WhatsappTicketConfirmation directly. DIP satisfied.

How the Principles Connect

Each principle solved a problem the previous one left behind:

SRP gave us small, focused classes. When a class does one thing, it becomes naturally easy to extend without modification — which is exactly what OCP requires.

OCP told us to extend via abstractions. But once you have inheritance hierarchies, LSP steps in and says: make sure your subclasses honour the parent's contract.

LSP and ISP surface the same smell — a class implementing something it has no business implementing. LSP says fix your hierarchy. ISP says fix your interface. Two sides of the same coin.

DIP is the glue that ties everything together. SRP, OCP, LSP, and ISP all tell you to create abstractions. DIP says: now depend on those abstractions, not the concretions. This is what makes everything testable, swappable, and decoupled.

SRP creates focused classes → OCP makes them extendable → LSP keeps hierarchies honest → ISP keeps interfaces clean → DIP wires it all together.

The Tradeoffs

SOLID is a compass, not a religion. Over-applying it leads to premature abstraction — which is its own problem.

Principle	Benefit	Cost
SRP	Focused, easy to change in isolation	More classes, more files, more navigation
OCP	Add features without breaking existing code	More abstractions upfront — overkill if variants never appear
LSP	Subclasses are truly interchangeable	Sometimes forces flat hierarchies or abandoning inheritance
ISP	Classes only know what they need	Interface explosion — dozens of tiny interfaces
DIP	Testable, swappable, decoupled	Wiring complexity — need a composition root

CAP, PACELC, and the Tradeoffs Every Distributed System Has to Make

Madhukar Vissapragada — Mon, 13 Jul 2026 05:25:53 +0000

CAP Theorem

Say a research team claims they've built a sorting algorithm that runs in O(log n). Is that possible?

No. To sort anything, you have to at least look at every element once, so time complexity can never be better than O(n) — that's the true lower bound. Comparison-based sorting algorithms (the ones we typically use) can't beat O(n log n). But when the elements are bounded — say, all values between 1 and 10 — non-comparison algorithms like counting sort can hit that O(n) lower bound directly.

The point: it's mathematically proven what is and isn't achievable here. No amount of clever engineering gets you below O(n), just like it can't get comparison-based sorting below O(n log n).

Distributed systems have their own version of this. CAP theorem tells us what is and isn't possible in distributed systems — a lower bound on what a distributed system can guarantee, no matter how well it's engineered. It's built on three properties: Consistency, Availability, and Partition Tolerance.

Consistency

We always talk about consistency in the context of data. When a write happens to the database, consistency asks: are the reads in line with that write?

Reads happen at two places: caches, and replicas.

Consistency is irrelevant to stateless servers, and irrelevant when data is immutable — in both cases there's nothing that can go "stale."

There are three types of consistency:

Eventual Consistency

A system is eventually consistent when reads eventually line up with writes, at some point in time. The system will have stale reads until then.

Example: replicas sync with the write database every 5 minutes. A counter updates every 1 minute. The replicas catch up at t=5, t=10, and so on — eventually consistent.

Immediate Consistency

A system is immediately consistent when reads and writes happen atomically — typically via a two-phase commit. At any point in time, reads are guaranteed to be in line with the write database.

It's always good to have immediate consistency, but it's hard to achieve, and it costs you latency to get it.

No Consistency

A system has no consistency when there's data loss — some writes never make it anywhere durable. This is only acceptable when intermediate values genuinely don't matter and some data loss is fine (e.g. certain analytics pipelines).

Availability

We talk about availability in terms of how a server deals with requests.

If a healthy server denies a healthy request → low / no availability (any 5xx — the server can't reach a critical resource it needs).
If a healthy server satisfies a healthy request → high availability.
If a server crashes mid-request and the client has to retry after a timeout → this is not counted as low availability. The client retries, the load balancer routes elsewhere, and the system moves on.
If a bad request comes in and the server denies it (e.g. an auth error, 4xx) → the system is still considered highly available. The server responded correctly; the client was at fault.

Partition Tolerance

Picture a set of servers connected by cables, all talking to each other. If a network failure isolates some of them, and as a result some services go down — but the system as a whole keeps running — we call the system partition tolerant.

Example: Amazon's payment service goes down due to a network failure, but users can still browse the catalog, wishlist items, add things to their cart.

If a system has to shut down entirely because of a network failure, it is not partition tolerant.

Example: stock exchanges (BSE/NSE/NYSE/SSE) — a partition takes the whole exchange down.

Availability vs Partition Tolerance

Situation: Someone wants to withdraw money from an ATM. The ATM backend checks the account balance, then updates it — both in the primary DB and in the replicas.

Under normal conditions, this just works — the write reaches the DB and the read replica stays in sync.

Now introduce a network partition between the backend DB servers.

Low on consistency, high on availability

The user withdraws money. Because of the partition, the server can't sync up with the replica. A later balance check gets routed to the stale replica and returns the old balance — as if the withdrawal never happened.

Low on availability, high on consistency

Alternatively: the withdrawal request is denied outright, because the backend detects it can't sync with the replica and refuses to risk serving incorrect data.

CAP Theorem: Pick 2

CAP Theorem states that you can only pick 2 out of Consistency (always meaning immediate consistency here), Availability, and Partition Tolerance. With this, we get only 3 possible types of systems:

A+P System

Designed to choose high availability and partition tolerance. These systems have eventual consistency, and yes — they do have stale reads.

Example: social media platforms.

C+P System

Designed to choose high consistency and partition tolerance. These systems have immediate consistency, and no — they do not have stale reads.

A commonly cited example here is ATMs, but as we saw earlier, that is not quite right in practice — most real banking systems are actually AP, favoring uptime and reconciling inconsistencies afterward (that is the whole overdraft-fee mechanism). A more accurate example of a true C+P system would be something like a stock broker placing an order against a live balance check, where the request is flatly denied rather than risking an incorrect trade.

C+A System

Designed to choose high consistency and high availability. These systems are not partition tolerant — if there is any network partition, the entire system goes down. They have immediate consistency, and no stale reads.

Example: stock exchanges. Stock exchange companies cannot afford to be low-available or inconsistent, so to avoid network partition failures in the first place, they do a lot of engineering — their servers are connected by many duplicate fiber optic cables.

Another definition of CAP theorem

At the scale of Google, can a system choose to have network failures bring the entire system down? No. Google has millions of servers, and somewhere, network partitions are happening every single day.

The majority of systems we see are designed to be partition tolerant. They have to choose either availability or consistency. We mostly see AP systems in the real world.

So the definition of CAP theorem becomes:

Partition tolerance is non-negotiable.
We pick either availability or consistency.

PACELC Theorem

PACELC theorem is an extension of CAP theorem.

To understand it, consider two situations:

When there is a network partition → choose Consistency or Availability
When there is no network partition → choose Latency or Consistency

No matter whether there is a partition or not, you only ever have two options to choose between. Even in the best-case scenario — a perfectly healthy network — you still cannot get both low latency and immediate consistency at the same time.

Master Slave Replication

Basic Setup

We'll have one Master. Writes will always go to the master.
We'll have more than one Slave. Reads will always go to the slaves.

Replication Factor (X): number of total copies of the same data.
X = 1 Master + y slaves

If X = 3, then 1 Master + 2 Slaves
If X = 4, then 1 Master + 3 slaves
If X = 5, then 1 Master + 4 slaves

Where do the writes and reads happen?

Writes always happen at the master
Reads always happen at the replicas

What happens if the Master goes down?
Re-election happens, and one of the slaves becomes master.

What if the old master comes back online?
It joins as a slave.

What if a slave goes down?
A new slave is spun up. We should always maintain the replication factor (X).

Why do we need an odd number of servers?
For tie-breaking (quorum).

Master Slave Replication With No Consistency

	Where	Availability	Latency
Reads	At one of the slaves	High	Low
Writes	Only at Master	High	Low

Writes always go to the master. Reads always go to one of the slaves.
We have more than one replica, so read availability is always high.
We write to only one place — even if the master crashes, re-election happens — so write availability is high. And because you're writing to only one place, write latency is low, not high.
Can there be data loss? Yes — if the master's HDD fails before it syncs up, all unsynced data is lost.
Can stale reads happen? Yes — if data is requested before a sync completes.

Master Slave Replication with Eventual Consistency

	Where	Availability	Latency
Reads	At one of the slaves	High	Low
Writes	At 2 places (1 Master + 1 slave)	Decent	Decent

Writes always happen at two places (master and a slave). Reads always go to one of the slaves.
We have more than one replica, so read availability is always high.
Write availability is decent because we're doing atomic writes at 2 places, and we need at least 2 servers online for a successful write.
Can there be data loss? No — we're writing to more than one place.
Can there be stale reads? Yes — possible if we request data before a sync happens.
How do we write to more than one place atomically? We use a two-phase commit for atomic writes, which gradually increases write latency.

Master Slave Replication with Immediate Consistency - Writing everywhere

	Where	Availability	Latency
Reads	One of the Replicas	High	Low
Writes	At every server	Very Low	Very High

Writes happen at every server, and if a write fails at even one server, we roll back at every other server.
Writing to every server will definitely drop the latency, because you're bottlenecked by the slowest server — so write latency is very high, not very low.
Reads have high availability because we have more than one replica.
Reads have low latency because we just have to read from one server.
Can we have stale reads? No — we're writing to all the servers, so every server always has the latest data.
We use a two-phase commit to write to all the servers.

Master Slave Replication with Immediate Consistency - Writing to more than half servers (Quorum)

	Where	Availability	Latency
Reads	More than half of the servers	Decent	Decent
Writes	More than half of the servers	Decent	Decent

We write and read to more than half of the servers.
The availability here is a middle ground — not the "very low" of write-everywhere, but not the "very high" of writing to a single master either — since we now need a majority of servers to be reachable, not all of them.
Latency is also a middle ground, since we're waiting on a majority rather than every single server.
Can we have stale reads? No — because more than half the servers have the latest data.
How do we make sure we're reading the latest data? We add timestamps to each request and store it in the DB. While fetching, we return the value with the latest timestamp across all the reads.
If any server crashes while reading, we'll always have at least one server with the latest data.

Master Slave Replication - Tunable Consistency

We don't need to write or read to more than half of the servers, as long as there's an overlap — that's enough to achieve immediate consistency.

Now we can tune our system:

If your system is read-heavy, choose to write to more servers.
If your system is write-heavy, choose to read from more servers.

Can we have stale data? Depends on how we tune it.

Parameters:

R = Number of reads
W = Number of writes
X = Replication Factor

The rules:

R = 1, W = 1 → No Consistency
R = 1, W > 1 → Eventual Consistency
R + W ≤ X, W > 1 → Eventual Consistency
R + W > X → Immediate Consistency

Wrapping Up

The mental model worth keeping:

Partition tolerance isn't a choice — at any real scale, it's the water you swim in.
So the actual decision is Consistency vs. Availability during a partition, and Latency vs. Consistency the rest of the time.
And master-slave replication, once you add the R/W/X model, isn't stuck at one point on that spectrum — it's a dial you can turn based on whether your system reads more than it writes, or the other way around.

How We Optimized Manuscript Processing at a Scientific Publishing Platform

Madhukar Vissapragada — Sat, 27 Jun 2026 14:14:15 +0000

Section 1: The Domain

We build a product that processes academic manuscripts for scientific publishing companies. Authors submit their manuscripts in the form of DOCX files. Our system converts these DOCX files into XML — the industry standard format used across the entire publishing world.

Every publishing company has their own DTD (Document Type Definition) — a schema that defines the structure of their XML. This means the rules for how a manuscript should be structured, tagged, and formatted are different for every journal and every publisher.

The conversion pipeline

When an author submits a manuscript, here is what happens:

Author submits a DOCX file to our system
The system downloads the journal-specific rules file from S3
The rules file is used to convert the DOCX into a structured XML
During conversion, the system raises annotations and discrepancies — places where the manuscript does not conform to the journal's rules
The XML is then converted into an HTML preview
The author views the HTML on the UI and resolves the annotations and discrepancies raised by the system

The problem

The entire process — from DOCX submission to HTML preview — takes approximately 3 minutes.

The product owner received feedback from authors that 3 minutes is too long. Authors are sitting and waiting, not knowing if their manuscript is being processed correctly. This is a poor experience and directly impacts the author's trust in the platform.

The product owner has asked us to reduce the waiting time.

Section 2: Finding the Bottleneck

As part of improving the system latency we started profiling the pipeline to identify where the 3 minutes were being spent.

We quickly identified that downloading the rules file from S3 on every submission was the biggest contributor to latency.

Why is the download so slow?

The rules files are large — each rules file is close to 1 GB in size. Transferring 1 GB over the network on every single submission adds significant overhead before any actual processing even begins.

Understanding the scale

We receive 3,000 to 5,000 submissions per day
Our system supports 300 different journal types
Based on our metrics, 60 to 70 journals account for 90% of all submissions

This last observation is the key insight. We are downloading 1 GB files from S3 thousands of times a day — but for the same 60 to 70 journals repeatedly. The same rules file is being downloaded over and over again for every submission of the same journal type.

Current architecture

The decision

We decided to break this network latency on every request. Instead of downloading the rules file from S3 on every submission, we would cache the rules files of the top 70 journals locally on the application server.

This would eliminate the redundant S3 downloads for 90% of our submissions and directly reduce the processing time for the majority of authors.

Section 3: Why Local Cache?

Before jumping into the implementation we had to decide what type of cache to use.

Global cache — ruled out

At first glance a global cache seems like a reasonable choice. But when we thought about it carefully we realised it does not solve our problem at all.

With a global cache:

Rules file is downloaded from S3 → stored in global cache server
For every submission, app server downloads the rules file from the global cache server

We have simply moved the bottleneck. We are still transferring 1 GB of data over the network for every request — just from a different source. The latency problem remains unsolved.

Local cache — the right choice

With a local cache, the rules file is stored directly on the application server's HDD. When a submission comes in:

If the rules file is already on the local HDD → use it directly, zero network transfer
If not → download from S3 once, store locally, use it

Every subsequent submission for the same journal type uses the locally cached file with no network overhead at all.

Storage cost

We support 300 journal types but only 60 to 70 journals account for 90% of submissions. If we cache the rules files for these 70 journals:

70 journals × 1 GB per rules file = 70 GB per application server

70 GB on a local HDD is completely acceptable. HDD storage is cheap and this is a one time cost per server.

Local cache is the right fit for our use case.

Section 4: The Consistency Problem

Now that we have decided on local caching, we need to think carefully about cache invalidation. Before choosing an algorithm, we need to understand what kind of consistency our system requires.

Does eventual consistency work here?

Let's think through the scenario.

We cache the rules files locally and start processing manuscripts. Now assume that a domain expert — someone from the manuscript team or a peer reviewer — identifies that one of the journal rules has a bug. A rule has been added incorrectly, changed, or deleted. A separate uploader service fixes the rules file, uploads the new version to S3, and updates the DB.

But here is the problem — our application servers have the old rules file cached locally. Before the cache gets invalidated, our system processes around 100 manuscripts using the wrong rules. The XML is generated, the HTML is rendered, and authors go to the UI and spend time resolving annotations and discrepancies based on incorrect rules.

Later, the quality check team identifies that the XML was generated using outdated rules. Now we have to go back to those authors and tell them their work needs to be redone.

Authors will not accept this. The credibility of the platform is at stake.

Eventual consistency does not fit this use case.

We need immediate consistency

Our system must ensure that the moment a rules file is updated, every subsequent manuscript processed by any application server uses the updated rules. No exceptions.

The natural choice for immediate consistency is Write Through cache — write to both cache and the source of truth atomically. But this is extremely hard to implement in a distributed environment.

With multiple application servers each holding their own local cache, achieving atomic writes across all of them simultaneously is practically impossible. If we use 2 Phase Commit to coordinate these writes, the latency overhead would be so high that it defeats the entire purpose of caching in the first place.

The solution — Write Through with Versioning

We need immediate consistency without the complexity and latency of 2 Phase Commit. The solution is a tweaked approach — write through with versioning.

Before we explain the solution, let us look at how the current code is implemented.

Section 5: The Code

v1 — The naive approach

This is how the system was originally implemented. Every time a manuscript submission comes in, the rules file is hardcoded based on the journal ID.

import os

def handle_request_v1(request):
    author_id = request.author_id
    journal_id = request.journal_id
    manuscript = request.manuscript

    author_info = pgsql.get_author_info(author_id)
    if author_info is None:
        return 404

    journal_info = pgsql.get_journal_info(journal_id)
    if journal_info is None:
        return 404

    rules_file_name = f"{journal_id}_rules.csv"

    if not os.path.exists(rules_file_name):
        download_from_s3([journal_info.rules_file_url])

    convert_to_xml(manuscript, rules_file_name)

The problem with v1:

The rules file name is hardcoded as {journal_id}_rules.csv. If the rules file is updated in S3 and the DB, the file name on disk stays the same. The os.path.exists check returns True — the file exists — but the content is stale. The system silently serves outdated rules with no way of knowing.

This is exactly the eventual consistency problem we described.

v2 — Write Through with Versioning

The key insight is simple — instead of hardcoding the rules file name, we fetch it from the DB on every request. The DB always holds the latest file name. The file name itself acts as the version.

When a domain expert updates the rules file:

The uploader service uploads the new rules file to S3 with a timestamp in the file name — e.g. journal_42_rules_2025-03-16_08:00.csv
On success, the uploader updates the file name in the DB
These two writes do not need to be atomic — if S3 succeeds but DB update fails, the new file is simply not being used yet. It causes no harm.

Now when the next submission comes in:

App server fetches journal_info from DB — gets the new file name
Checks if this file exists on local HDD
It does not — because the old file had a different name
Downloads the new file from S3
Processes the manuscript with the correct updated rules

The old cached file is simply never used again and will eventually be evicted by LRU.

import os

def handle_request_v2(request):
    author_id = request.author_id
    journal_id = request.journal_id
    manuscript = request.manuscript

    author_info = pgsql.get_author_info(author_id)
    if author_info is None:
        return 404

    journal_info = pgsql.get_journal_info(journal_id)
    if journal_info is None:
        return 404

    rules_file_name = journal_info.rules_file_name

    if not os.path.exists(f'/rules_data/{rules_file_name}'):
        download_from_s3([journal_info.rules_file_url])

    convert_to_xml(manuscript, f'/rules_data/{rules_file_name}')

What changed from v1 to v2:

	v1	v2
Rules file name	Hardcoded `{journal_id}_rules.csv`	Fetched from DB `journal_info.rules_file_name`
Versioning	None — stale files served silently	Timestamp in file name acts as version
Consistency	Eventual	Immediate
Cache path	No prefix	`/rules_data/` prefix

The key insight:

We are not caching the file name — the file name is fetched fresh from the DB on every request so it can never be stale. We are only caching the actual rules file content on disk. This gives us immediate consistency without 2 Phase Commit.

Section 6: Eviction, Routing and Tradeoffs

Cache Eviction — LRU

We use LRU (Least Recently Used) eviction. It is the best fit for our use case because every rules file has a timestamp in its name. The operating system automatically maintains read and write timestamps for all files on disk. When the cache storage threshold is reached, we simply evict the file that was least recently accessed to make space for new downloads.

This requires no additional tracking logic — the OS does it for us naturally.

Routing — Round Robin

We use Round Robin for routing requests across application servers.

The reason is that rules files are replicated across all app servers — not sharded. Every app server can serve any journal type.

Why not shard by journal ID? If we route all requests for a specific journal to a specific server, and that journal gets a high volume of submissions, that one server gets bombarded while all others remain idle. This creates an uneven load distribution that defeats the purpose of horizontal scaling.

With Round Robin, any request can go to any server. All servers gradually cache the top 70 journals and serve submissions equally.

The tradeoff — cold start latency

There is one unavoidable tradeoff in this design. The first request for any journal type will always be slow — the rules file has to be downloaded from S3 before processing can begin. Only subsequent requests benefit from the local cache.

This is acceptable in most cases but can be a poor experience if a high volume of submissions is expected for a specific journal — for example, right before a submission deadline.

Overcoming the cold start — warm up strategy

We can proactively eliminate this cold start problem using a cache warm-up background job.

Before a high volume period is expected:

A background job sends dummy small manuscript submissions for the most frequently used journals
The app servers download and cache the rules files
The dummy XML outputs are deleted after caching

When the real high volume of author submissions arrives, the rules files are already cached on all app servers and every submission gets the fast path.

The tradeoff is additional background job infrastructure and a small amount of unnecessary S3 download cost. But the author experience is significantly improved.

Caching — From Fundamentals to Production Systems

Madhukar Vissapragada — Fri, 26 Jun 2026 14:06:02 +0000

Section 1: What is Caching?

Caching is a technique to store a small amount of data for faster retrieval and higher throughput.

Caching is used in two scenarios:

High read frequency — when a particular piece of data is requested a very high number of times
Expensive computation — when fetching data requires complex joins or aggregations — caching the result avoids recomputing it every time

Computer memory hierarchy

To understand why we cache only a small amount of data, we need to look at how computer memory is structured. The higher up in the hierarchy, the faster the read — but the less space available.

Level	Speed	Size
Registers	Ultra fast	Bytes
CPU Cache	Very fast	Kilobytes
RAM	Fast	Gigabytes
Flash / SSD	Slower than RAM	Terabytes
Hard Disk	Slowest	Terabytes

The key insight — the smaller the storage, the faster the retrieval. Caching works by moving frequently accessed data up this hierarchy, closer to the CPU and away from the slow disk.

Section 2: Caching at Various Levels of the Application

Caching does not happen at just one place in a system. It happens at multiple levels — from the browser all the way to the backend database layer.

Frontend caching

As a frontend developer, you can cache data directly in the browser using:

Local Storage — persists even after the browser is closed
Session Storage — cleared when the browser tab is closed
Indexed DB — a full browser-side database for storing large structured data

Third party caching — CDN

Just like DNS is a third party service that resolves domain names, a CDN is a third party service that offers caching as a service.

CDN providers like Akamai, Cloudflare, and AWS Cloudfront have set up edge nodes around the globe. Static content is served directly from these edge nodes — close to the user — instead of travelling all the way to the origin server.

What can be cached in edge nodes? Any static content larger than 10KB — images, videos, code files, web pages, audio files.

CDN providers either own or rent space in data centers around the world to set up these edge nodes. Today, 70% of internet traffic is handled by CDNs — they are the backbone of the modern internet.

Backend caching

On the backend, we have three types of cache:

Local Cache — cache lives inside the application server's memory. Inherently distributed since every app server has its own cache.
Distributed Global Cache — a separate dedicated cache cluster shared by all app servers. Data is either sharded or replicated across cache servers.
Single Global Cache — one dedicated cache server shared by all app servers. No routing algorithm needed.

Section 3: CDN Deep Dive — How Facebook Serves Videos

Let's understand how CDNs work with a real world example.

Upload flow — Madhukar uploads a video

Madhukar sends a video upload request to Facebook's application servers
Facebook's application servers upload the video to a file storage service like S3 and receive back an S3 url
Facebook's application servers send the S3 url to a CDN provider like Akamai to cache the video across their edge nodes
The application server stores all the metadata in the database — video_id, s3_url, cdn_url

View flow — Gopi watches the video
Gopi sends a GET request to Facebook's application servers
Facebook's application servers respond with the CDN url
Gopi's device sends a DNS request to resolve the CDN url to an IP address

How does DNS find the nearest edge node?

Geo DNS
The authoritative DNS servers of the CDN look at the IP address of the user's DNS resolver and return the nearest edge node IP. But there is a problem — if a user changes their DNS server to something like 8.8.8.8, the authoritative server sees Google's IP instead of the user's actual location and may return a far away edge node. This is why Geo DNS is not widely used.

Anycast
All edge nodes share the same IP address. When Gopi's request is sent to that IP, the internet's BGP routers calculate the number of hops required to reach each edge node and automatically route the request to the one with the fewest hops — the nearest edge node. Gopi's DNS settings are completely irrelevant here.

Gopi's request is routed to the nearest edge node via BGP
The video is served from the edge node

Do we cache on the first request?

No. CDNs do not cache on the first or second request. This is called 2 hit caching.

Over time CDN providers observed that many requests are one-hit wonders — a file gets requested once and never again. Caching those wastes precious edge node memory. So CDN providers set a threshold of 2 — only after the third request is the content cached and served from the edge node.

Can the backend server access the CDN?

Technically yes — but CDNs are client facing. They are designed to serve content to end users, not to backend servers.

Section 4: Cache Eviction

Cache memory is limited. When the cache is full and a new record needs to be inserted, the system must remove something to make space. This is called cache eviction.

There are several eviction policies:

LRU — Least Recently Used
Removes the item that has not been accessed for the longest time. The assumption is that if something hasn't been used recently it is unlikely to be used again soon. LRU is the industry standard and is used by the majority of applications.

LFU — Least Frequently Used
Removes the item that has been accessed the fewest number of times overall. Useful when some data is accessed in bursts but overall rarely used.

FIFO — First In First Out
Removes the item that was inserted first regardless of how often it was accessed. Simple but often inefficient — a very popular item that was cached early could get evicted even if it is still heavily used.

Policy	Evicts	Best for
LRU	Least recently accessed	General purpose — industry standard
LFU	Least frequently accessed	Data with stable long term access patterns
FIFO	Oldest inserted item	Simple systems where recency does not matter

Section 5: Cache Invalidation Patterns

Cache invalidation means the data in the cache is no longer valid and needs to be updated or removed. There are four main patterns to handle this.

TTL — Time To Live (Cache Aside)

TTL provides eventual consistency and is ideal for simple DB queries.

Every cached item has an expiry time. After the TTL expires the data is no longer valid.

All write requests go directly to the DB
All read requests go to the cache
- Cache hit → serve from cache
- Cache miss → fetch from DB, asynchronously write to cache The system can serve stale data until the TTL expires. This is acceptable for most use cases where eventual consistency is fine.

Write  →  DB only
Read   →  Cache → hit: serve | miss: fetch from DB → populate cache

Write Around

Write Around is ideal for scenarios where fetching data from the DB is very complex — involving many joins and aggregations.

All write requests go directly to the DB
All read requests go to the cache
A cron job runs periodically, pulls data from the DB and writes it to the cache
Until the cron job runs, the cache will serve stale data
When the first request comes in there is no data in the cache — a 404 is returned to the client

Write  →  DB only
Read   →  Cache → hit: serve | miss: 404
Cron   →  DB → Cache (periodic sync)

Write Through

Write Through provides immediate consistency.

Every write request goes to both the cache and the DB atomically. All read requests go to the cache — which is always fresh.

On a single server — atomic writes are achievable using locks, since both cache and DB share the same memory
On a distributed system — atomic writes require 2 Phase Commit, which increases latency and adds rollback complexity Single server implementation:

# Both writes succeed
lock.acquire()
try:
    write_to_cache(key, value)
    write_to_db(key, value)
finally:
    lock.release()

# Cache write fails
lock.acquire()
try:
    write to cache  ✗  # fails here
    write to DB        # never reached
except CacheError:
    # nothing to rollback
    log("cache write failed")
finally:
    lock.release()

# DB write fails
lock.acquire()
try:
    write to cache  ✓
    write to DB     ✗  # fails here
except DBError:
    rollback cache     # undo cache write
    log("db write failed, cache rolled back")
finally:
    lock.release()

Write  →  Cache + DB atomically
Read   →  Cache always (always fresh)

Write Back

In Write Back all reads and writes go directly to the cache. A background cron job periodically fetches data from the cache and dumps it into the DB.

No data consistency — DB is always behind
No stale reads — since all reads come from cache which has the latest data
Data loss is possible — if the cache crashes before the cron job runs, that window of data is lost
Ideal for use cases where intermediate data points are not critical and some data loss is acceptable

Write  →  Cache only
Read   →  Cache only (always fresh)
Cron   →  Cache → DB (periodic dump)

Conclusion

Caching is not a single technique — it is a layered strategy that operates at every level of a modern application, from the browser to the CDN to the backend database layer.

The choice of cache pattern is always a tradeoff:

If your system can tolerate stale data — TTL or Write Around keeps things simple and scalable
If your system requires immediate consistency — Write Through gives you that guarantee but at the cost of latency and distributed complexity
If your system is write-heavy and can tolerate data loss — Write Back gives you the highest write throughput

The next time your app loads a video in milliseconds, a feed in under a second, or a product page instantly — caching is quietly doing its job at every layer of the stack.

Credits:

This blog is based on the HLD curriculum taught at Scaler Academy by instructor pragy Agarwal.

Consistent Hashing — A System Design Deep Dive

Madhukar Vissapragada — Tue, 16 Jun 2026 16:07:06 +0000

Consistent Hashing — The Algorithm Behind Scalable Systems

Section 1: The Problem

We have customers from Amazon and Flipkart who want to wishlist products from these platforms. Assume that this wishlist feature doesn't exist natively on Amazon or Flipkart. We have built a service where users can save and manage their wishlist from any e-commerce platform — all in one place.

Our service is gaining popularity and experiencing massive scale. To handle this, we first tried vertical scaling — replacing our existing server with a more powerful one. But even that wasn't enough to meet our scale expectations.

So we decided to go with horizontal scaling — adding more servers of the same configuration to share the load.

Vertical scaling — Replacing the existing server with a more powerful server.

Horizontal scaling — Adding more servers of the same existing configuration.

Horizontal scaling solves two problems at once:

Too much traffic — a single server cannot handle all the incoming requests
Too much data — a single server cannot store all the wishlist data

Both of these force us to distribute across multiple servers. But now we have a new problem — we have multiple servers, so which server handles which request? And how do we know which server holds which user's data?

Section 2: What is Sharding?

Before we talk about routing, we need to understand how data is distributed across servers.

If we normalize a table into two separate tables — say users and wishlist — on the same server, we call it normalization.

If we do the same thing but place each table on a different server, we call it separation of concerns or microservices.

If we split the data across multiple tables where the schema remains the same but the data is divided based on a sharding key, and we do this on the same server, we call it horizontal partitioning.

If we do the same thing across different servers, we call it Data Sharding. Data sharding is always done using a sharding key.

Section 3: What makes a good routing algorithm?

Now that we have sharded the data across multiple servers, we need to understand how to route requests correctly.

If user A stores their wishlist data and we route them to Server 5, then the next time user A wants to view their wishlist, we must route that request to Server 5 again — because that is where their data lives. This is the core problem a good routing algorithm must solve.

Before we pick an algorithm, let's define what makes a routing algorithm good:

Fast — computationally efficient to determine which request goes to which server
Equal distribution — load must be distributed equally across all servers
Minimal data movement — when we add or remove servers, the amount of data that needs to move should be minimal
Deterministic — all load balancers must always be in sync without constant communication between them, and requests of the same type must always go to the same server

Section 4: Round Robin

Round Robin sends each request to the next server in sequence using a simple modulo operation.

servers = ["A", "B", "C", "D"]

def handle_request(request):
    key = request.user_id
    total_servers = len(servers)
    server_id = int(key) % total_servers
    server = servers[server_id]
    forward_request(request, server)

Initial distribution with 4 servers:

A → user 0, 4, 8 ...
B → user 1, 5, 9 ...
C → user 2, 6, 10 ...
D → user 3, 7, 11 ...

When server B crashes, N changes from 4 to 3:

A → user 0, 3, 6, 9 ...
C → user 1, 4, 7, 10 ...
D → user 2, 5, 8, 11 ...

Only users 1, 5, 9... should have moved since their server B crashed. But almost every user got remapped to a different server — causing massive unnecessary data movement.

	Round Robin
Fast	✓
Equal distribution	✓
Minimal data movement	✕
Deterministic	✓

Verdict — Round Robin fails on minimal data movement. It works only when the number of servers is fixed and never changes.

Section 5: Bucketing (Range Based)

Bucketing assigns a range of user IDs to each server rather than using modulo.

server_list = ["A", "B", "C", "D"]
total_users = 400

def handle_request(request):
    key = request.user_id
    total_servers = len(server_list)           # 4
    bucket_size = total_users // total_servers  # 400 / 4 = 100
    server_id = math.floor(key / bucket_size)
    server = server_list[server_id]
    forward_request(server, request)

Initial distribution with 4 servers and 400 users:

A → user 0   – 99
B → user 100 – 199
C → user 200 – 299
D → user 300 – 399

When server B crashes, the remaining 3 servers must cover all 400 users:

A → user 0   – 132
C → user 133 – 265
D → user 266 – 399

All buckets change — causing massive unnecessary data movement across every server, not just server B's users.

When new users sign up, we cannot accommodate them on existing servers because the bucket ranges are already decided. It is impossible to add new users without first buying more servers.

	Bucketing
Fast	✓
Equal distribution	✓
Minimal data movement	✕
Deterministic	✓

Verdict — Bucketing is even worse than Round Robin. Not only does it reshuffle all data when a server is added or removed, it cannot even accommodate new users without buying new servers first.

Section 6: Mapping Table

What if instead of a formula-based solution we simply track which user is on which server? The load balancer maintains a hashmap from user_id to server_id.

mapping = {
    "user_A": "server_1",
    "user_B": "server_3",
    "user_C": "server_2",
    ...
}

def handle_request(request):
    server = mapping[request.user_id]
    forward_request(server, request)

When a server crashes, only the users on that server are reassigned to a random available server. No other users are affected.

When a new server is added, we take the total user count, pick a proportional number of random users, and move them to the new server to balance the load.

This gives us minimal data movement — only the affected users move, everyone else stays put.

The fatal flaw — all load balancers must always have the same mapping table. Keeping this table in sync across all load balancers at low latency is practically impossible. The CAP theorem tells us we cannot achieve perfect consistency with low latency at the same time.

	Mapping Table
Fast	✓
Equal distribution	✓
Minimal data movement	✓
Deterministic	✕

Verdict — Mapping Table finally solves minimal data movement but fails on the hardest problem — keeping all load balancers in sync at low latency is impossible.

Section 7: Consistent Hashing

Consistent Hashing is a hash based technique to route requests. It satisfies all four criteria — making it the algorithm of choice for distributed systems.

	Consistent Hashing
Fast	✓
Equal distribution	✓
Minimal data movement	✓
Deterministic	✓

How it works

A hash function is a digest function — it takes anything as input and returns an output within a fixed range. Common hash functions include MD5, SHA256, SHA512, and Murmur3.

In Consistent Hashing, we use a logical hash ring — the output space of the hash function bent into a circle.

We use k hash functions to place each server at k virtual spots on the ring. A good value of k is 32 or 64.
We use 1 hash function to place each user at one spot on the ring.
When a request arrives, we find the first server clockwise from the user's position on the ring using binary search.
That server handles the request and stores the user's data. This means:
All load balancers run the same hash functions and see the same ring — no sync needed
When a server is added or removed, only the users nearest to it on the ring are remapped — minimal data movement
The same user always hashes to the same spot — deterministic ### Implementation

import mmh3
import bisect

def custom_hash(data: str, i: int) -> int:
    # Murmur3 hash with seed i, output range 0..9
    return mmh3.hash(data, seed=i, signed=False) % 10

def build_ring(servers, k):
    ring = []
    for server in servers:
        for index in range(1, k + 1):
            h = custom_hash(str(server), index)
            ring.append((h, server))
    ring = sorted(ring)
    return ring

def route(user):
    user_hash = custom_hash(str(user), 0)
    # Find the first server clockwise using binary search
    index = bisect.bisect_right(ring, (user_hash, user))
    index = index % len(ring)  # wrap around the ring
    server_hash, server = ring[index]
    print(f"{user} hashed to {user_hash} → routed to {server} at position {server_hash}")

servers = ['10.11.1.13', '10.11.2.17', '10.11.13.167', '10.11.12.255', '10.11.1.0']
ring = build_ring(servers, 32)

route('Vishal')
route('Sanjana')

Notice that no matter how many times we call route('Vishal'), he always lands on the same server — that is Consistent Hashing being deterministic.

Adding a new server

When a new server K is added to the ring between user A and server H:

Before: User A → Server H
New server K added between User A and Server H
After:  User A → Server K

User A's existing data moves from Server H → Server K. All other users are completely unaffected. This is minimal data movement — only the users who fall between the new server and its predecessor on the ring are impacted.

When a server crashes

When a server crashes, all the users whose data lived on that server are automatically remapped to the next server clockwise on the ring.

Before: User A → Server H
Server H crashes
After:  User A → Server K  (next server clockwise)

User A's data moves from Server H → Server K
All other users → untouched

In both cases — adding or removing a server — only a small slice of users near that server on the ring are affected. Everyone else continues routing to the same server as before.

This is what makes Consistent Hashing fundamentally better than Round Robin and Bucketing — where any change in the number of servers causes a full reshuffle of almost all users.

Conclusion

Every routing algorithm we evaluated satisfied some criteria but failed on others.

Round Robin uses a simple modulo operation — user_id % N — which means any change in N causes almost all keys to remap to different servers, making it unusable in dynamic environments. Bucketing improves readability but suffers the same remapping problem and additionally cannot accommodate new users without pre-purchasing servers. Mapping Table achieves true minimal data movement but introduces a distributed consistency problem — keeping the hashmap in sync across all load balancers at low latency violates the guarantees of the CAP theorem.

Consistent Hashing resolves all four criteria in a single algorithm. By placing both servers and users on a logical hash ring using k independent hash functions, it guarantees:

O(log Nk) routing time via binary search on a sorted ring
Near-perfect load distribution as k approaches 32 or 64
1/N data movement when a server is added or removed — only the affected segment of the ring remaps
Zero inter-LB communication — since all load balancers share the same hash functions and server list via heartbeat, they independently compute identical routing decisions This is why Consistent Hashing is the foundation of distributed systems at scale — Cassandra, DynamoDB, Redis Cluster, and CDN routing systems like Cloudflare all rely on it.

DEV Community: Madhukar Vissapragada

Simple Factory, Factory Method, Abstract Factory — Which One Do You Need?

The Problem

Step 1: Simple Factory

Step 2: Factory Method

Step 3: Abstract Factory

Adding a New Database Family

The Progression — Why Each Pattern Exists

When to Use Each

The Tradeoffs

Simple Factory

Factory Method

Abstract Factory

The SOLID Connection

Never Create an Invalid Object Again — The Builder Pattern

Fix 1: Named Parameters

Fix 2: Validation Inside the Constructor

Fix 3: Setters

Three Approaches. Three Failures.

What Is the Builder Pattern?

Building It Step by Step

Step 1: Separate the Classes

Step 2: The Builder with Method Chaining

Step 3: build() — Validate First, Create Second

Step 4: Block Direct Instantiation

The Complete Implementation

Usage — Plain English at the Call Site

The Director — Presets for Known Configurations

The Tradeoffs

What Builder Gives You

What Builder Costs You

SOLID Design Principles: Stop Writing Code That Breaks When You Touch It

What is SOLID?

The Example

The Naive Version

S — Single Responsibility Principle

O — Open/Closed Principle

L — Liskov Substitution Principle

I — Interface Segregation Principle

D — Dependency Inversion Principle

How the Principles Connect

The Tradeoffs

CAP, PACELC, and the Tradeoffs Every Distributed System Has to Make

CAP Theorem

Consistency

Eventual Consistency

Immediate Consistency

No Consistency

Availability

Partition Tolerance

Availability vs Partition Tolerance

Low on consistency, high on availability

Low on availability, high on consistency

CAP Theorem: Pick 2

A+P System

C+P System

C+A System

Another definition of CAP theorem

PACELC Theorem

Master Slave Replication

Master Slave Replication With No Consistency

Master Slave Replication with Eventual Consistency

Master Slave Replication with Immediate Consistency - Writing everywhere

Master Slave Replication with Immediate Consistency - Writing to more than half servers (Quorum)

Master Slave Replication - Tunable Consistency

Wrapping Up

How We Optimized Manuscript Processing at a Scientific Publishing Platform

Section 1: The Domain

The conversion pipeline

The problem

Section 2: Finding the Bottleneck

Why is the download so slow?

Understanding the scale

Current architecture

The decision

Section 3: Why Local Cache?

Global cache — ruled out

Local cache — the right choice

Storage cost

Section 4: The Consistency Problem

Step 3: `build()` — Validate First, Create Second