Python Architectural Refactoring: Moving from Primitive Dictionaries to Protocols and Immutable Dataclasses

Python Clean Code Architecture

In modern backend engineering, Python often suffers from a silent, chronic architectural disease known as **Primitive Obsession**—specifically, what experienced teams call *Dictionary-Driven Development*. Because Python dictionaries are extraordinarily ergonomic and trivially serialized to JSON, engineering teams frequently pass untyped `dict` payloads across dozens of function calls, service boundaries, and asynchronous queues.

What begins as rapid prototyping quickly degrades into an unmaintainable production liability. A simple typo in a key string—such as accessing `order["usr_id"]` instead of `order["user_id"]`—passes static linters undetected, only to detonate in production as a `KeyError` during peak traffic. Furthermore, functions that accept mutable dictionaries frequently mutate them in-place, introducing subtle, non-deterministic bugs that defy debugging across concurrent async loops.

To build robust, maintainable Python backends capable of scaling with large engineering teams, software architects must elevate their domain modeling beyond primitive dictionaries. By combining **structural subtyping via `typing.Protocol`**, **immutable state via `@dataclass(frozen=True, slots=True)`**, and strict static type analysis, teams can achieve the agility of dynamic scripting paired with the compile-time guarantees of statically-typed systems.

The Anti-Pattern: Dictionary-Driven Development and Silent Runtime Failures

Consider a standard e-commerce fulfillment function written with primitive dictionaries:

```python
# ANTI-PATTERN: Fragile, untyped dictionary manipulation
def process_order(order_payload: dict) -> dict:
# Invisible dependency on exact string keys
user_id = order_payload.get("user_id")
items = order_payload.get("items", [])

# In-place mutation breaks idempotency and purity
total_cents = 0
for item in items:
total_cents += item["price_cents"] * item.get("qty", 1)
item["processed"] = True # Side effect on input dictionary!

order_payload["total_cents"] = total_cents
order_payload["status"] = "PROCESSED"
return order_payload
```

While concise, this pattern introduces severe architectural liabilities:
1. **Zero Static Safety**: Modern type checkers (`mypy`, `pyright`) see `dict` and cannot verify whether `"price_cents"` actually exists, whether `"qty"` is guaranteed to be an integer, or whether keys are spelled correctly.
2. **Hidden In-Place Mutation**: Modifying `item["processed"] = True` mutates the caller's memory. If downstream code or retry loops reuse the input dictionary, unexpected side effects cascade across the application.
3. **No Centralized Validation**: There is no enforcement that `total_cents` cannot be negative, or that `items` contains at least one product. Validation logic gets scattered across ad-hoc `if` checks in every handler.
4. **Poor IDE Discoverability**: Autocomplete provides zero assistance. A developer working with `order_payload` must hunt through documentation or database schemas to discover valid property names.

Structural Subtyping: Why typing.Protocol Beats Abstract Base Classes (ABCs)

For decades, object-oriented design in languages like Java or classic Python relied on **Nominal Typing** via Abstract Base Classes (`abc.ABC`). In nominal typing, a class must explicitly inherit from a base interface to satisfy a type contract:

```python
from abc import ABC, abstractmethod

class PaymentGateway(ABC):
@abstractmethod
def charge(self, amount_cents: int, token: str) -> bool:
pass

class StripeGateway(PaymentGateway): # Explicit inheritance coupling
def charge(self, amount_cents: int, token: str) -> bool:
...
```

While ABCs work, they introduce tight coupling. Third-party libraries, legacy classes, or lightweight test mocks that implement the exact same `.charge()` method cannot be used interchangeably unless they explicitly inherit from `PaymentGateway`.

Python 3.8 solved this elegantly with **PEP 544: Structural Subtyping (Protocols)**. `typing.Protocol` implements static duck typing: *if it walks like a duck and quacks like a duck, static type checkers treat it as a duck, with zero inheritance required*.

```python
from typing import Protocol, runtime_checkable

@runtime_checkable
class PaymentGateway(Protocol):
"""Structural interface contract for any billing provider."""
def charge(self, amount_cents: int, token: str) -> bool:
...
```

With `Protocol`, any class that defines a conforming `charge` method automatically satisfies `PaymentGateway` without inheriting from it. This provides significant advantages:
- **Decoupled Architecture**: Domain interfaces remain pure and belong to the consumer, adhering strictly to the Dependency Inversion Principle.
- **Trivial Mocking**: In unit tests, you can construct a clean mock class without dragging in heavyweight base class dependencies or metaclass mechanics.
- **Third-Party Compatibility**: You can define protocols that match classes from third-party vendor SDKs without wrapping them in complex inheritance hierarchies.

Watch: ArjanCodes on Protocols vs ABCs in Python

Enforcing Domain Invariants with Frozen Dataclasses and Slots

When modeling domain entities, value objects, and configuration payloads, the standard `@dataclass` decorator provides automatic generation of `__init__`, `__repr__`, and `__eq__`. However, standard dataclasses are **mutable by default**, leaving them vulnerable to accidental state alteration.

By configuring `@dataclass(frozen=True, slots=True)`, you achieve two critical architectural milestones:

### 1. Strict Immutability and Thread Safety
When `frozen=True` is enabled, any attempt to reassign attributes after instantiation raises a `FrozenInstanceError`:

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class Money:
amount_cents: int
currency: str = "USD"

def __post_init__(self) -> None:
if self.amount_cents < 0:
raise ValueError(f"Amount cannot be negative: {self.amount_cents}")
if len(self.currency) != 3:
raise ValueError(f"Invalid ISO currency code: {self.currency}")

# Demonstrating immutability
price = Money(amount_cents=2500)
# price.amount_cents = 3000 # RAISES: FrozenInstanceError at runtime!
```

Because frozen dataclasses cannot be mutated, Python automatically provides a deterministic `__hash__` method. This allows value objects to be used safely as keys in dictionaries and elements in sets—a capability vital for memoization and caching.

### 2. Radical Memory Efficiency with `slots=True`
In standard Python classes, every instance allocates an internal dictionary (`__dict__`) to store its dynamic attributes. For microservices instantiating hundreds of thousands of domain objects per second, this dictionary overhead accounts for up to 40% of total heap memory.

Setting `slots=True` (introduced natively in Python 3.10) instructs the CPython interpreter to allocate a compact, fixed-size array of references instead of a dictionary:

```python
@dataclass(frozen=True, slots=True)
class TelemetryEvent:
event_name: str
timestamp_ns: int
user_id: int
payload_hash: str
```

In micro-benchmarks measuring 1,000,000 instances, `slots=True` delivers:
- **~35% to 42% reduction in memory footprint** compared to standard dataclasses.
- **~15% faster attribute access speeds**, as property lookups bypass dictionary hashing.

Architectural Comparison: Dicts vs Pydantic vs Frozen Dataclasses vs Protocols

Choosing the right data modeling abstraction is a core software design decision. Here is a definitive breakdown of when each construct should be utilized in production:

Real-World Refactoring: An Order Processing Pipeline

Let us refactor our initial fragile dictionary-driven order processor into a production-grade, type-safe architecture using Protocols and Frozen Dataclasses.

Step 1: Define Immutable Domain Entities and Value Objects

```python
from dataclasses import dataclass, replace
from typing import Tuple

@dataclass(frozen=True, slots=True)
class OrderItem:
sku: str
price_cents: int
quantity: int = 1

def __post_init__(self) -> None:
if self.price_cents <= 0:
raise ValueError(f"Price must be positive, got {self.price_cents}")
if self.quantity <= 0:
raise ValueError(f"Quantity must be positive, got {self.quantity}")

@property
def subtotal_cents(self) -> int:
return self.price_cents * self.quantity

@dataclass(frozen=True, slots=True)
class Order:
order_id: str
user_id: int
items: Tuple[OrderItem, ...]
status: str = "PENDING"

@property
def total_cents(self) -> int:
return sum(item.subtotal_cents for item in self.items)

def mark_processed(self) -> "Order":
"""Return a fresh copy with updated status (Pure Immutability)."""
return replace(self, status="PROCESSED")
```

Step 2: Define Structural Protocols for External Dependencies

Instead of depending on concrete database connections or third-party email SDKs, define consumer-driven Protocols:

```python
from typing import Protocol

class OrderRepository(Protocol):
"""Structural storage contract."""
def save(self, order: Order) -> None:
...

class NotificationService(Protocol):
"""Structural messaging contract."""
def send_confirmation(self, user_id: int, order_id: str, amount_cents: int) -> bool:
...
```

Step 3: Implement Pure Service Logic with Dependency Injection

```python
class OrderFulfillmentService:
def __init__(
self,
repository: OrderRepository,
notifier: NotificationService,
) -> None:
self._repository = repository
self._notifier = notifier

def fulfill_order(self, order: Order) -> Order:
if not order.items:
raise ValueError("Cannot fulfill empty order.")

# Execute business logic immutably
processed_order = order.mark_processed()

# Persist and notify
self._repository.save(processed_order)
self._notifier.send_confirmation(
user_id=processed_order.user_id,
order_id=processed_order.order_id,
amount_cents=processed_order.total_cents,
)

return processed_order
```

### The Architectural Payoff
Notice what we achieved:
- **Zero In-Place Side Effects**: The original `order` object remains unaltered. `order.mark_processed()` returns a new instance via `dataclasses.replace()`.
- **Absolute Type Safety**: Passing an invalid property name or incorrect type triggers immediate errors during static analysis (`mypy`).
- **Complete Testability**: In unit tests, writing a mock repository requires zero patching or inheritance:

```python
# Trivial test mock satisfying OrderRepository structural protocol
class InMemoryOrderRepo:
def __init__(self) -> None:
self.saved_orders = []

def save(self, order: Order) -> None:
self.saved_orders.append(order)
```

Implementation Blueprint: How to Migrate Legacy Codebases Incrementally

Migrating an enterprise Python codebase away from dictionary obsession does not require a risky rewrite. Use this phased migration playbook:

By adopting structural protocols and immutable dataclasses, Python engineering teams eliminate an entire class of runtime bugs while preserving the expressive velocity that makes Python a world-class backend language.