Advanced Data Structures & Algorithms

Java Backend Modernization

Beginner's Guide to Data Structures

Agentic AI Systems

Data Engineering & Spark Mastery

Low-Level Design Interview Prep

Microservices Interview Roadmap

Design Patterns Interview Roadmap

Distributed Systems Interview Roadmap

Mastering Python Development

System Design Interview Prep

Distributed Systems Refresher

AI Engineering Launchpad

Architecture Patterns for Scalable Systems

RAG & Vector Search Mastery

Production DevOps & Reliability

Enterprise Patterns Playbook

Master Coding Interviews

Coding Techniques Interview Roadmap

Data Structures Interview Roadmap

Architecture Patterns Interview Roadmap

software-engineering-principles

Migrate your Spring Boot services from thread-pool exhaustion to JDK 21 virtual threads — the practical Spring developer guide

Adapting to Virtual Threads for Spring Developers

how-it-works-internals-explained

From WAL and MVCC to fsync and isolation levels — the internals behind every ACID guarantee in PostgreSQL, MySQL, Oracle, and SQL Server.

ACID Properties Explained: How SQL Databases Guarantee Atomicity, Consistency, Isolation, and Durability

How modern NoSQL databases achieve atomicity and isolation without a single machine

ACID Transactions in Distributed Databases: DynamoDB, Cosmos DB, and Spanner Compared

llm-engineering

Is an LLM a brain in a jar? To make it truly useful, we need to give it access to the world. This guide explains RAG and Agents.

Advanced AI: Agents, RAG, and the Future of Intelligence

Production AI needs explicit routing, memory, execution, and evaluation layers rather than one loop.

AI Architecture Patterns: Routers, Planner-Worker Loops, Memory Layers, and Evaluation Guardrails

datastructures-and-algorithms

Master shortest paths, dependency resolution, and cycle detection with robust Java solutions.

Advanced Graph Algorithms: Dijkstra, Topological Sort, and Disjoint Set Union (DSU)

An LLM can talk, but an AI Agent can *act*. We explain how Agents use the ReAct framework to brow...

AI Agents Explained: When LLMs Start Using Tools

A production-first guide to picking the right vector index for recall, latency, memory, and update patterns.

ANN Index Types Explained: When to Choose Flat, HNSW, IVF, or IVF-PQ

apache-spark-engineering

Process petabytes with Python: understand Spark's execution model, DataFrame transformations, partitioning strategy, and real-time streaming.

Apache Spark for Data Engineers: RDDs, DataFrames, and Structured Streaming

ACID guarantees consistency. BASE guarantees availability. We explain the trade-offs between SQL...

BASE Theorem Explained: How it Stands Against ACID

machine-learning-fundamentals

From the query-key-value formulation to multi-head attention — the mechanism that made transformers dominate AI

Attention Mechanism Explained: How Transformers Learn to Focus

system-design-interview-prep

They all sit in front of your servers. But do you need Nginx, HAProxy, or Kong? We clarify the roles of each component.

API Gateway vs. Load Balancer vs. Reverse Proxy: What's the Difference?

architecture-patterns-for-production-systems

Mobile apps need less data than Desktop dashboards. Why serve them the same JSON? The Backend for Frontend (BFF) pattern solves this.

Backend for Frontend (BFF): Tailoring APIs for UI

BFS explores graphs level by level using a queue — the key to shortest paths and level-order problems.

BFS — Breadth-First Search: Level-by-Level Graph Exploration

Backtracking is a brute-force algorithmic technique that solves problems by trying to build a sol...

Exploring Backtracking Techniques in Data Structures

big-data-engineering

Choose ingestion, serving, and ownership patterns deliberately when data platforms start to scale.

Big Data Architecture Patterns: Lambda, Kappa, CDC, Medallion, and Data Mesh

Why traditional databases fail at scale, what the 5 Vs really mean, and a practical map of the big data ecosystem from ingestion to insights.

Big Data 101: The 5 Vs, Ecosystem, and Why Scale Breaks Everything

Not all Binary Trees are created equal. We explain Full, Complete, Perfect, and Balanced Binary T...

Exploring Different Types of Binary Trees

Master Big O notation: measure algorithm efficiency from O(1) to O(n²) with growth diagrams, worked examples, and the interview mental model.

Big O Notation Explained: Time Complexity, Space Complexity, and Why They Matter in Interviews

Binary search has five distinct patterns — classic, leftmost, rightmost, rotated arrays, and 2D matrices.

Binary Search Patterns: Five Variants Every Senior Engineer Knows

A class should have one, and only one, reason to change. We explain the 'S' in SOLID with a simpl...

Simplifying Code with the Single Responsibility Principle

Software entities should be open for extension, but closed for modification. We explain the 'O' i...

How the Open/Closed Principle Enhances Software Development

Understand how behavioral subtyping preserves correctness in Java application architectures.

Liskov Substitution Principle Demystified: The Heart of Polymorphism

Clients shouldn't be forced to depend on methods they don't use. We explain the 'I' in SOLID with...

Interface Segregation Principle: No Fat Interfaces

High-level modules shouldn't depend on low-level modules. Both should depend on abstractions. We explain DIP with a simple Java example.

Dependency Inversion Principle: Decoupling Your Code

Stop writing massive if-else statements. The Strategy Pattern allows you to swap algorithms at runtime. We explain it with a Payment Processing exampl

Strategy Design Pattern: Simplifying Software Design

low-level-design-guide

Build a robust, state-driven vending machine system in Java Boot with clean OOP design.

Low-Level Design: Designing a Vending Machine using the State Pattern

Master Domain-Driven Design (DDD) by learning how to enforce domain invariants using Aggregates and Value Objects in Java.

Domain-Driven Design (DDD): Designing Aggregates, Value Objects, and Context Boundaries

A classic interview problem. We design an extensible Tic-Tac-Toe game that supports N*N grids, multiple players, and different winning strategies.

LLD for Tic-Tac-Toe: Designing an Extensible OOP Game

Designing a parking lot is the 'Hello World' of OOP Design. Break down LLD using OOP pillars, SOLID, and classic design patterns.

LLD for Parking Lot System: Designing a Smart Garage

Theory is good, code is better. We implement the Parking Lot system in Java, focusing on the Singleton, Factory, and Strategy patterns.

Implement LLD for Parking Lot: Code Walkthrough

OOP design breakdown: Cache<K,V> interface, SOLID principles, and the HashMap + DoublyLinkedList pattern that powers LRU eviction in Java.

LLD for LRU Cache: Designing a High-Performance Cache

OOP design of an elevator system: Encapsulation, Abstraction, Polymorphism, SOLID principles, and two design patterns — all in one domain model.

LLD for Elevator System: Designing a Smart Lift

Designing a movie booking system involves handling concurrency (no double bookings!), managing complex hierarchies, and ensuring a smooth user experie

LLD for Movie Booking System: Designing BookMyShow

How do you match a rider with a driver in real-time? We break down the Low-Level Design of a ride-sharing app using the Observer and Strategy patterns

LLD for Ride Booking App: Designing Uber/Lyft

Design a high-throughput, concurrent pub-sub queue in Java using locks and thread pools.

Low-Level Design: Building a Thread-Safe In-Memory Pub-Sub Queue

How do you turn a long URL into a 7-character string? We explore Base62 encoding, Hash collisions, and database choices.

LLD for URL Shortener: Designing TinyURL

## Scenario context

Imagine a filing clerk whose job is:
1. **Store documents** (filing cabinet logic).
2. **Send notification emails** whenever a document is filed.
3. **Log activity** to an audit trail.

One person doing three jobs — fine until they're on vacation and you only need the email changed. You have to find and understand the whole multi-responsibility class just to change one notification template.

**SRP** says: each clas…

This walkthrough focuses on **The Filing Cabinet That Also Sends Emails**.

Before making a design choice, clarify:

- Imagine a filing clerk whose job is: 1.
- Store documents (filing cabinet logic).
- Send notification emails whenever a document is filed.

**Concepts in play:** design-principles-solid, event-driven-architecture, jvm-internals-and-garbage-collection, low-level-design-systems

## Stage 1 — The Classic Violation: User Manager Who Does Everything

- Reasons this class must change: - The database schema changes → modify DB logic.
- - The welcome email template changes → modify email logic.
- - The audit log format changes → modify logging logic.
- Three reasons to change = three responsibilities.

*Applies **design-principles-solid** to the decision above.*

```java
// ❌ SRP violation — two very different reasons to change this class
class UserManager {
    public void saveUser(User user) {
        // 1. save to DB
        db.execute("INSERT INTO users VALUES (?)", user.data());
        // 2. send a welcome email
        emailService.send(user.email, "Welcome to our platform!", WELCOME_TEMPLATE);
        // 3. write audit log
        logger.info("User created: " + user.getId());
    }
}
```

```mermaid
classDiagram
    class UserManager {
        +saveUser()
        +sendWelcomeEmail()
        +logAuditTrail()
    }
    note for UserManager "Violates SRP: DB, email, and logging in one class"
```

**Observable outcome:** Three reasons to change = three responsibilities.

## Stage 2 — The SRP Fix: One Class, One Job

- Now each class has exactly one reason to change.
- UserRegistrationService orchestrates the flow but owns none of the individual mechanics.
- Notice the key benefit beyond cleanliness: independent deployability of understanding .
- A new developer joining the team can read WelcomeEmailService in thirty seconds and fully understand what it does and what could cause it to change.

*Applies **event-driven-architecture** to the decision above.*

```java
// ✅ Split into single-responsibility classes
class UserRepository {
    public void save(User user) {
        db.execute("INSERT INTO users VALUES (?)", user.data());
    }
}

class WelcomeEmailService {
    public void sendWelcome(User user) {
        emailService.send(user.email, "Welcome!", WELCOME_TEMPLATE);
    }
}

class UserAuditLogger {
    public void logCreated(User user) {
        logger.info("User created: " + user.getId());
    }
}

// Orchestrator — knows when to call each, but not how they work
class UserRegistrationService {
    private final UserRepository repo;
    private final WelcomeEmailService emailSvc;
    private final UserAuditLogger audit;

    public void register(User user) {
        repo.save(user);
        emailSvc.sendWelcome(user);
        audit.logCreated(user);
    }
}
```

```mermaid
classDiagram
    class UserRegistrationService {
        +register()
    }
    class UserRepository {
        +save()
    }
    class WelcomeEmailService {
        +sendWelcome()
    }
    class UserAuditLogger {
        +logCreated()
    }
    UserRegistrationService --> UserRepository
    UserRegistrationService --> WelcomeEmailService
    UserRegistrationService --> UserAuditLogger
```

**Observable outcome:** A new developer joining the team can read WelcomeEmailService in thirty seconds and fully understand what it does and what could cause it to change.

## Stage 3 — Deep Dive: Detecting SRP Violations

- 

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

**Observable outcome:** You can explain how “Deep Dive: Detecting SRP Violations” changes the architecture or implementation path.

## Stage 4 — SRP Responsibility Flow

- When a request hits UserRegistrationService.register() , responsibility flows cleanly to dedicated single-purpose classes — each is an isolated change axis.
- If the database schema changes, only UserRepository is modified.
- If the email template changes, only WelcomeEmailService is touched.
- The orchestrator UserRegistrationService never changes for infrastructure reasons — only if the registration workflow itself changes.

*Applies **low-level-design-systems** to the decision above.*

```mermaid
flowchart LR
    A["register(user)"] --> B[UserRepository.save]
    A --> C[WelcomeEmailService.sendWelcome]
    A --> D[UserAuditLogger.logCreated]
    B --> E[(Database)]
    C --> F[Email Provider]
    D --> G[Audit Log]
```

**Observable outcome:** The orchestrator UserRegistrationService never changes for infrastructure reasons — only if the registration workflow itself changes.

## Stage 5 — Real-World Application: SRP at Scale

- SRP applies at every scale — class, service, and infrastructure.
- Where to apply SRP first: Start at the class level.
- Pain signals: unit tests with 5+ mocks in setUp, class names with "And" or "Manager", files frequently edited by two different teams for unrelated features.
- At the microservice level, SRP manifests as bounded contexts — each service owns one business capability.

*Applies **design-principles-solid** to the decision above.*

**Observable outcome:** At the microservice level, SRP manifests as bounded contexts — each service owns one business capability.

## Stage 6 — Hands-On: Identify and Refactor SRP Violations

- Here is a class that violates SRP.
- Identify the responsibilities, then split them.
- Five responsibilities → five focused classes: Orchestrator: OrderProcessingService has one responsibility: orchestrating the order workflow.
- Each collaborator has one responsibility: doing its specific job.

*Applies **event-driven-architecture** to the decision above.*

```java
// 🛑 How many responsibilities does this class have?
class OrderProcessor {
    public void processOrder(Order order) {
        // Responsibility 1: Validate
        if (order.getItems().isEmpty()) {
            throw new IllegalArgumentException("Order has no items");
        }
        // Responsibility 2: Charge
        stripeClient.charge(order.getCustomerId(), order.getTotal());
        // Responsibility 3: Update inventory
        for (Item item : order.getItems()) {
            inventoryDb.decrementStock(item.getSku(), item.getQuantity());
        }
        // Responsibility 4: Notify
        emailService.send(order.getEmail(), "Order confirmed", buildBody(order));
        // Responsibility 5: Audit
        logger.info("Order processed: " + order.getId());
    }
}
```

```java
class OrderProcessingService {
    public void processOrder(Order order) {
        validator.validate(order);
        paymentService.charge(order);
        inventoryService.decrementStock(order);
        notificationService.sendConfirmation(order);
        auditLogger.logProcessed(order);
    }
}
```

**Observable outcome:** Each collaborator has one responsibility: doing its specific job.

## End-to-end outcome

After working through the stages, you should be able to explain:

- - The "And" test always works.
- If you cannot name a class without "And" or "Manager", it has multiple responsibilities.

## Alternatives considered

### Decision Guide

Decision Guide


## Failure and degraded modes

### Trade-offs & Failure Modes: SRP vs. Cohesion

- **Detection:** SRP is sometimes misunderstood as "one method per class." That's wrong.
- **User or operator impact:** SRP is sometimes misunderstood as "one method per class." That's wrong.



## Scenario context

Here's a payment processor that violates OCP:

```python
class PaymentProcessor:
    def process(self, payment_type, amount):
        if payment_type == "credit_card":
            print(f"Processing credit card: ${amount}")
        elif payment_type == "paypal":
            print(f"Processing PayPal: ${amount}")
        # Every new payment method = edit THIS file
```

Each time you add a new payment method (Apple Pa…

This walkthrough focuses on **The Fragile Base Class Problem**.

Before making a design choice, clarify:

- Here's a payment processor that violates OCP: Each time you add a new payment method (Apple Pay, Crypto), you edit PaymentProcessor.process() .
- You risk: - Breaking credit card handling.
- - Merging conflicts from other teams editing the same file.

**Concepts in play:** design-principles-solid, jvm-internals-and-garbage-collection, low-level-design-systems, python-concurrency-nogil

## Stage 1 — Open for Extension, Closed for Modification" — What That Actually Means

- Every time you open a file to add a new feature, you risk breaking something that already works.
- OCP says: instead of modifying existing code, design it so you can add new behavior by adding new code — not changing old code.
- The classic metaphor: a plugin system .
- You don't modify Firefox to add an ad-blocker.

*Applies **design-principles-solid** to the decision above.*

**Observable outcome:** You don't modify Firefox to add an ad-blocker.

## Stage 2 — OCP via Polymorphism: Extending Without Modifying

- The fix: define a common abstraction and extend it.
- PaymentProcessor is now closed for modification.
- You can add 50 new payment methods and never touch it.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```python
from abc import ABC, abstractmethod

class PaymentMethod(ABC):
    @abstractmethod
    def process(self, amount: float) -> None:
        ...

class CreditCard(PaymentMethod):
    def process(self, amount):
        print(f"Processing credit card: ${amount}")

class PayPal(PaymentMethod):
    def process(self, amount):
        print(f"Processing PayPal: ${amount}")

class CryptoWallet(PaymentMethod):           # NEW — no existing file touched
    def process(self, amount):
        print(f"Processing crypto: ${amount}")

class PaymentProcessor:
    def process(self, method: PaymentMethod, amount: float):
        method.process(amount)               # Never changes
```

```mermaid
classDiagram
    class PaymentMethod {
        <<abstract>>
        +process(amount)
    }
    PaymentMethod <|-- CreditCard
    PaymentMethod <|-- PayPal
    PaymentMethod <|-- CryptoWallet
    PaymentProcessor --> PaymentMethod
```

**Observable outcome:** You can add 50 new payment methods and never touch it.

## Stage 3 — Deep Dive: Java Interface Implementation

- In Java, the same pattern uses interfaces: Testing benefit: You can write a FakePayment implementing PaymentMethod for unit tests without any production code changes.
- The Java version also demonstrates an important architectural boundary: the PaymentProcessor class lives in a separate module and has zero compile-time dependency on CreditCard , CryptoWallet , or any concrete payment t…
- Those classes are loaded at runtime, which means you can add, remove, or swap payment providers via dependency injection without recompiling PaymentProcessor .
- This is OCP operating at the module boundary level — a pattern you'll find in every major Java framework from Spring to Jakarta EE.

*Applies **low-level-design-systems** to the decision above.*

```java
public interface PaymentMethod {
    void process(double amount);
}

public class CreditCard implements PaymentMethod {
    public void process(double amount) {
        System.out.printf("Credit card: $%.2f%n", amount);
    }
}

public class CryptoWallet implements PaymentMethod {   // New — zero changes to CreditCard
    public void process(double amount) {
        System.out.printf("Crypto: $%.2f%n", amount);
    }
}

public class PaymentProcessor {
    public void charge(PaymentMethod method, double amount) {
        method.process(amount);   // Closed — never modified
    }
}
```

```mermaid
classDiagram
    class Shape {
        <<interface>>
        +area() double
        +perimeter() double
    }
    class Circle {
        -double radius
        +area() double
        +perimeter() double
    }
    class Rectangle {
        -double width
        -double height
        +area() double
        +perimeter() double
    }
    class Triangle {
        -double base
        -double height
        +area() double
        +perimeter() double
    }
    class AreaCalculator {
        +totalArea(shapes) double
    }
    Shape <|.. Circle
    Shape <|.. Rectangle
    Shape <|.. Triangle
    AreaCalculator ..> Shape
```

**Observable outcome:** This is OCP operating at the module boundary level — a pattern you'll find in every major Java framework from Spring to Jakarta EE.

## Stage 4 — OCP Extension Flow

- The key insight of OCP is that adding new behavior never requires touching PaymentProcessor .
- New payment types are added by creating new classes that plug into the existing abstraction.
- When Apple Pay is needed, a developer creates ApplePayMethod implements PaymentMethod and passes it to PaymentProcessor .
- Zero lines of PaymentProcessor or any existing payment class are changed — that is OCP in action.

*Applies **python-concurrency-nogil** to the decision above.*

```mermaid
flowchart LR
    A[PaymentProcessor.process] --> B[PaymentMethod interface]
    B --> C[CreditCard]
    B --> D[PayPal]
    B --> E[CryptoWallet]
    E --> F[NEW: no existing code modified]
    G[Add Apple Pay] --> H[Create new class]
    H --> B
```

**Observable outcome:** Zero lines of PaymentProcessor or any existing payment class are changed — that is OCP in action.

## Stage 5 — Real-World Application: OCP in Production Systems

- OCP is not just a class design pattern — it appears throughout distributed systems and product architecture.
- Real-world example — VS Code extensions: VS Code defines extension APIs (the abstraction).
- Extension authors add new functionality (language support, themes, debuggers) by implementing those APIs.
- The VS Code core is never modified to support new extensions.

*Applies **design-principles-solid** to the decision above.*

**Observable outcome:** The VS Code core is never modified to support new extensions.

## Stage 6 — Hands-On: Apply OCP to a Report Generator

- This exercise demonstrates the most common OCP violation pattern: a class that grows a new elif branch for every new output format, using ReportGenerator as the example because report formats are a natural extension poi…
- This particular violation was chosen because it mirrors real-world code you will find in ETL pipelines, data export tools, and document services.
- As you read through the violation code, focus on the line you would have to change to add Excel support — that modification point is the exact boundary OCP asks you to protect.
- OCP-compliant refactor: Before vs After: 📊 Strategy Pattern: OCP Applied to Sorting Algorithms This class diagram shows the Strategy pattern applied to sorting: Sorter holds a reference to the SortStrategy interface an…

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```python
# 🛑 OCP violation — every new format requires modifying this class
class ReportGenerator:
    def generate(self, data, format_type: str):
        if format_type == "pdf":
            return self._render_pdf(data)
        elif format_type == "csv":
            return self._render_csv(data)
        elif format_type == "html":
            return self._render_html(data)
        # Adding Excel requires modifying this class

    def _render_pdf(self, data): ...
    def _render_csv(self, data): ...
    def _render_html(self, data): ...
```

```python
from abc import ABC, abstractmethod

class ReportFormatter(ABC):
    @abstractmethod
    def format(self, data) -> str: ...

class PDFFormatter(ReportFormatter):
    def format(self, data) -> str:
        return f"[PDF] {data}"

class CSVFormatter(ReportFormatter):
    def format(self, data) -> str:
        return ",".join(str(v) for v in data)

class ExcelFormatter(ReportFormatter):   # NEW — zero existing code changed
    def format(self, data) -> str:
        return f"[Excel] {data}"

class ReportGenerator:
    def generate(self, data, formatter: ReportFormatter) -> str:
        return formatter.format(data)   # Never changes
```

**Observable outcome:** OCP-compliant refactor: Before vs After: 📊 Strategy Pattern: OCP Applied to Sorting Algorithms This class diagram shows the Strategy pattern applied to sorting: Sorter holds a reference to the SortStrategy interface an…

## End-to-end outcome

After working through the stages, you should be able to explain:

- - Apply OCP reactively, not preemptively.
- The first time you write payment processing, write CreditCard directly.

## Alternatives considered

### Decision Guide

Decision Guide


## Failure and degraded modes

### Trade-offs & Failure Modes: When OCP Is Over-Engineering

- **Detection:** That's only worth the cost when variation is genuinely expected.
- **User or operator impact:** That's only worth the cost when variation is genuinely expected.



## Scenario context

The Liskov Substitution Principle (LSP) mandates that subclasses must be substitutable for their superclasses without changing the correctness of the program. It shifts our understanding of inheritance from syntax (IS-A) to behavior (behaves-like).

---

Imagine you are maintaining a payment processing backend for an e-commerce platform. The system defines a base payment processor class to handle transaction process…

This walkthrough focuses on **The Fragile Base Class: A Common Inheritance Nightmare**.

Before making a design choice, clarify:

- Imagine you are maintaining a payment processing backend for an e-commerce platform.
- The system defines a base payment processor class to handle transaction processing, refunds, and fraud checks.
- For months, everything runs smoothly.

**Concepts in play:** jvm-internals-and-garbage-collection, design-patterns-gof, design-principles-solid, database-indexing

## Stage 1 — Defining the Contract: Behavioral Subtyping

- The Liskov Substitution Principle (LSP) was formulated by Barbara Liskov in a 1987 conference keynote and later formalized in a 1994 paper with Jeannette Wing.
- The formal definition states: If for each object $o 1$ of type $S$ there is an object $o 2$ of type $T$ such that for all programs $P$ defined in terms of $T$, the behavior of $P$ is unchanged when $o 1$ is substituted…
- In simpler terms, a subclass should extend the parent's behavior, not change or restrict it.
- If a client class expects an object of type Parent , it should be able to receive an object of type Child and continue operating correctly without needing to inspect the concrete type using instanceof or catching unexpe…

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

**Observable outcome:** If a client class expects an object of type Parent , it should be able to receive an object of type Child and continue operating correctly without needing to inspect the concrete type using instanceof or catching unexpe…

## Stage 2 — Preconditions, Postconditions, and Invariants

- To execute LSP successfully, you must master the rules governing preconditions, postconditions, and invariants.
- Let's look at a concrete toy dataset representing validation constraints to see how modifying these constraints breaks or preserves the contract.
- 📊 Toy Dataset: Validation Constraint Matrix Consider a base processor that validates customer age inputs.
- The base class accepts ages between 18 and 100.

*Applies **design-patterns-gof** to the decision above.*

**Observable outcome:** The base class accepts ages between 18 and 100.

## Stage 3 — Deep Dive: Covariance, Contravariance, and the History Constraint

- To fully grasp the mechanics of substitution, we must analyze the type-system level behaviors that occur during dynamic dispatch and inheritance.
- The Internals of Type Substitution LSP relies on covariant and contravariant types.
- Covariance allows a method to return a more specific (narrower) type than defined in the superclass.
- Contravariance allows a method to accept a more general (broader) argument type than defined in the superclass.

*Applies **design-principles-solid** to the decision above.*

**Observable outcome:** Contravariance allows a method to accept a more general (broader) argument type than defined in the superclass.

## Stage 4 — Visualizing the Substitutability Flow

- Understanding how contracts map between the client, base type, and subclasses is easiest when viewed as a flow.
- 📊 Client-Subtype Compatibility Workflow This diagram maps how a client system's input is handled by two different subclass implementations.
- Subclass A weakens the input preconditions (accepts ages 0-120) and safely processes the call.
- Subclass B strengthens the preconditions (only accepts ages 21-80), resulting in a runtime exception when passed an age of 19, which violates the parent interface contract and crashes the client system.

*Applies **database-indexing** to the decision above.*

```mermaid
flowchart TD
    Client[Client System] -->|Invokes method| Base[Base Type Interface]
    Base -->|Preconditions: Age 18-100| Sub1[Subclass A: Age 0-120]
    Base -->|Preconditions: Age 18-100| Sub2[Subclass B: Age 21-80]
    Sub1 -->|Returns ValidationResult| Client
    Sub2 -->|Throws IllegalArgumentException for Age 19| Client
    style Sub1 fill:#d4edda,stroke:#28a745
    style Sub2 fill:#f8d7da,stroke:#dc3545
```

**Observable outcome:** Subclass B strengthens the preconditions (only accepts ages 21-80), resulting in a runtime exception when passed an age of 19, which violates the parent interface contract and crashes the client system.

## Stage 5 — Real-World Systems: How Frameworks Enforce LSP

- In enterprise frameworks like Spring and Hibernate, LSP is a foundational assumption.
- For example, Spring's Dependency Injection container resolves beans by their interface type.
- If a developer registers a custom implementation of a MailSender interface that throws an exception during startup or fails to resolve template properties, the application context fails to load.
- Similarly, in Hibernate, lazy-loading proxies subclass your entity classes at runtime to intercept getter calls.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

**Observable outcome:** Similarly, in Hibernate, lazy-loading proxies subclass your entity classes at runtime to intercept getter calls.

## Stage 6 — Refactoring an LSP Violation: Java Code Contrast

- Let us contrast a database repository implementation that violates LSP with its refactored, safe version.
- The Violation: Throwing Exceptions in Overrides In this database processing example, we have a base CrudRepository class that supports reads, writes, and deletes.
- We extend it to create a ReadOnlyRepository .
- Since write and delete actions are not allowed, we throw exceptions.

*Applies **design-patterns-gof** to the decision above.*

```java
// VIOLATION: Subclass throws UnsupportedOperationException, breaking parent contract
public class CrudRepository {
    public String findById(String id) {
        return "EntityData";
    }

    public void save(String data) {
        System.out.println("Data saved to database");
    }

    public void delete(String id) {
        System.out.println("Data deleted from database");
    }
}

// Subclass that violates the base CrudRepository contract
public class ReadOnlyRepository extends CrudRepository {
    @Override
    public void save(String data) {
        // Violates LSP: Client expects writes to succeed
        throw new UnsupportedOperationException("Write operations are disabled on read-only databases");
    }

    @Override
    public void delete(String id) {
        // Violates LSP: Client expects deletes to succeed
        throw new UnsupportedOperationException("Delete operations are disabled on read-only databases");
    }
}

// Client application class executing data cleanups
public class DataCleanupService {
    public void purgeRecord(CrudRepository repo, String id) {
        // Safe compiler call, but crashes at runtime if passed ReadOnlyRepository!
        repo.delete(id);
    }
}
```

```java
// RESOLUTION: Segregate interfaces to ensure safe substitution
public interface ReadRepository {
    String findById(String id);
}

public interface WriteRepository {
    void save(String data);
    void delete(String id);
}

// Implements read capabilities safely
public class DatabaseReader implements ReadRepository {
    @Override
    public String findById(String id) {
        return "EntityData from Reader";
    }
}

// Implements read/write capabilities safely
public class DatabaseWriter implements ReadRepository, WriteRepository {
    @Override
    public String findById(String id) {
        return "EntityData from Writer";
    }

    @Override
    public void save(String data) {
        System.out.println("Data written safely");
    }

    @Override
    public void delete(String id) {
        System.out.println("Data deleted safely");
    }
}

// Client service accepts exactly what it requires
public class SafeDataCleanupService {
    private final WriteRepository writeRepo;

    public SafeDataCleanupService(WriteRepository writeRepo) {
        this.writeRepo = writeRepo;
    }

    public void purgeRecord(String id) {
        // Guaranteed to succeed without runtime contract failures
        writeRepo.delete(id);
    }
}
```

**Observable outcome:** Since write and delete actions are not allowed, we throw exceptions.

## End-to-end outcome

After working through the stages, you should be able to explain:

- When writing polymorphically dispatched code, follow these best practices to maintain substitutability: 1.
- Avoid Exceptions in Overrides: If you find yourself writing throw new UnsupportedOperationException() in a subclass, refactor your interface hierarchy.
- Behavior Over Syntax: Inheritance is a behavioral contract ("behaves-like"), not just a compiler mapping.
- Contract Rules: Subclasses can weaken preconditions or strengthen postconditions, but never the reverse.

## Alternatives considered

### API Decision Guide: Inheritance vs. Composition

When designing APIs, use this decision guide to choose between extending a class or composing it.


## Failure and degraded modes

### The Cost of Clean Inheritance: Design Trade-offs

- **Detection:** Strictly adhering to LSP is not free.
- **User or operator impact:** Strictly adhering to LSP is not free.



## Scenario context

Imagine a TV remote with 50 buttons. You only ever use 5: power, volume, channel up/down, and input select. ISP says: **don't give every device the full remote**. Give each device the buttons it actually needs.

In software, a **fat interface** forces every implementing class to provide methods it doesn't need, creating:
- Stub implementations that throw `UnsupportedOperationException`.
- Tight coupling — changes to…

This walkthrough focuses on **The Fat Remote Control Problem**.

Before making a design choice, clarify:

- Imagine a TV remote with 50 buttons.
- You only ever use 5: power, volume, channel up/down, and input select.
- ISP says: don't give every device the full remote .

**Concepts in play:** design-principles-solid, jvm-internals-and-garbage-collection

## Stage 1 — The Classic Violation: The Printer Interface

- SimplePrinter can only print — but the Machine interface forces it to "implement" 4 other operations it can't do.
- Any code that calls simplePrinter.fax() fails at runtime rather than at compile time.
- 📊 Fat Interface Violation: SimplePrinter Forced to Stub Four Methods Both SimplePrinter and OfficePrinter implement the fat Machine interface, but the similarity ends there.
- OfficePrinter can legitimately fulfil all five methods, while SimplePrinter is forced to throw UnsupportedOperationException in scan() , fax() , copy() , and staple() — four methods it cannot meaningfully support.

*Applies **design-principles-solid** to the decision above.*

```java
public interface Machine {
    void print(Document d);
    void scan(Document d);
    void fax(Document d);
    void copy(Document d);
    void staple(Document d);
}

public class SimplePrinter implements Machine {
    public void print(Document d) { /* works */ }
    public void scan(Document d)  { throw new UnsupportedOperationException(); }
    public void fax(Document d)   { throw new UnsupportedOperationException(); }
    public void copy(Document d)  { throw new UnsupportedOperationException(); }
    public void staple(Document d){ throw new UnsupportedOperationException(); }
}
```

```mermaid
classDiagram
    class Machine {
        <<interface>>
        +print(d)
        +scan(d)
        +fax(d)
        +copy(d)
        +staple(d)
    }
    class SimplePrinter {
        +print(d)
        +scan(d) throws
        +fax(d) throws
        +copy(d) throws
        +staple(d) throws
    }
    class OfficePrinter {
        +print(d)
        +scan(d)
        +fax(d)
        +copy(d)
        +staple(d)
    }
    Machine <|.. SimplePrinter
    Machine <|.. OfficePrinter
```

**Observable outcome:** OfficePrinter can legitimately fulfil all five methods, while SimplePrinter is forced to throw UnsupportedOperationException in scan() , fax() , copy() , and staple() — four methods it cannot meaningfully support.

## Stage 2 — Applying ISP: Split by Role

- After the split, SimplePrinter implements only Printable — the single capability it genuinely supports — while OfficePrinter implements Printable , Scannable , and Faxable to reflect its real hardware capabilities.
- Any code holding a Printable reference can safely accept either class, and no class is ever forced to provide a method it cannot meaningfully execute.
- Now: - SimplePrinter compiles and works with zero stubs.
- - OfficePrinter implements everything it genuinely supports.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```java
// Segregated interfaces — each is a single capability
public interface Printable  { void print(Document d); }
public interface Scannable  { void scan(Document d); }
public interface Faxable    { void fax(Document d); }
public interface Copyable   { void copy(Document d); }
public interface Stapleable { void staple(Document d); }

// Simple printer: only what it can do
public class SimplePrinter implements Printable {
    public void print(Document d) { /* full implementation */ }
}

// All-in-one office printer: combines all
public class OfficePrinter implements Printable, Scannable, Faxable, Copyable, Stapleable {
    public void print(Document d)  { /* ... */ }
    public void scan(Document d)   { /* ... */ }
    public void fax(Document d)    { /* ... */ }
    public void copy(Document d)   { /* ... */ }
    public void staple(Document d) { /* ... */ }
}
```

```mermaid
classDiagram
    class Printable {+print(d)}
    class Scannable {+scan(d)}
    class Faxable   {+fax(d)}

    SimplePrinter ..|> Printable
    OfficePrinter ..|> Printable
    OfficePrinter ..|> Scannable
    OfficePrinter ..|> Faxable
```

**Observable outcome:** - OfficePrinter implements everything it genuinely supports.

## Stage 3 — Deep Dive: Python Protocol-Based ISP

- Python uses structural subtyping via Protocol (PEP 544) — no explicit implements required: SimplePrinter never declared it implements Printable .
- The type checker confirms structural compatibility at analysis time without runtime overhead.
- Notice that OfficePrinter satisfies both Printable and Scannable — Python's Protocol lets you express the same ISP split as Java's explicit interfaces, but with zero inheritance boilerplate.

*Applies **design-principles-solid** to the decision above.*

```python
from typing import Protocol

class Printable(Protocol):
    def print(self, doc: str) -> None: ...

class Scannable(Protocol):
    def scan(self) -> str: ...

class SimplePrinter:
    def print(self, doc: str) -> None:
        print(f"Printing: {doc}")

class OfficePrinter:
    def print(self, doc: str) -> None:
        print(f"Printing: {doc}")
    def scan(self) -> str:
        return "scanned content"

def send_to_printer(device: Printable, doc: str) -> None:
    device.print(doc)

def run_scanner(device: Scannable) -> str:
    return device.scan()

send_to_printer(SimplePrinter(), "Invoice.pdf")   # OK — only print needed
send_to_printer(OfficePrinter(), "Report.pdf")    # OK — also satisfies Printable
run_scanner(OfficePrinter())                      # OK — satisfies Scannable
# run_scanner(SimplePrinter())                   # Type error — SimplePrinter has no scan()
```

**Observable outcome:** Notice that OfficePrinter satisfies both Printable and Scannable — Python's Protocol lets you express the same ISP split as Java's explicit interfaces, but with zero inheritance boilerplate.

## Stage 4 — ISP Interface Segregation Flow

- The transformation from a fat interface to segregated role-based interfaces — and how implementations choose only what they need.
- The left-to-right flow traces the refactoring decision for the Machine interface.
- OfficePrinter answers "YES" to supporting all capabilities and takes the direct path — it implements Printable , Scannable , and Faxable because it genuinely provides all three.
- SimplePrinter answers "NO" and routes through the split, arriving at Printable alone, with no stubs and no forced coupling to operations its hardware cannot perform.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
flowchart LR
    A[Machine fat interface] --> B{Does class support all?}
    B -- YES --> C[OfficePrinter implements all 5]
    B -- NO --> D[Split into role interfaces]
    D --> E[Printable]
    D --> F[Scannable]
    D --> G[Faxable]
    E --> H[SimplePrinter implements Printable only]
    C --> E
    C --> F
    C --> G
```

**Observable outcome:** SimplePrinter answers "NO" and routes through the split, arriving at Printable alone, with no stubs and no forced coupling to operations its hardware cannot perform.

## Stage 5 — Real-World Application: ISP in Production Systems

- ISP applies everywhere interfaces define contracts between components.
- Kubernetes analogy: A Pod spec in Kubernetes follows ISP — you only declare the capabilities you need (volumes, network policies, security contexts).
- Each concern is a separate, composable specification.
- You don't get a monolithic "configure everything" spec that forces you to set all 200 fields.

*Applies **design-principles-solid** to the decision above.*

**Observable outcome:** You don't get a monolithic "configure everything" spec that forces you to set all 200 fields.

## Stage 6 — Hands-On: Segregate a Fat Interface

- Here is a fat IUserService interface.
- Problem: A read-only admin dashboard must implement createUser , deleteUser , sendWelcomeEmail .
- A background job that only resets passwords must implement findById , listAll , sendWelcomeEmail , and getAuditLog .
- ISP-compliant split: Key benefit: AdminDashboardService cannot accidentally call deleteUser — the interface doesn't include it.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```java
// 🛑 Fat interface — forces all implementers to support everything
public interface IUserService {
    User findById(String id);
    List<User> searchByName(String name);
    List<User> listAll();
    void createUser(User user);
    void updateUser(User user);
    void deleteUser(String id);
    void resetPassword(String userId, String newPassword);
    void sendWelcomeEmail(String userId);
    List<String> getAuditLog(String userId);
}
```

```java
public interface IUserReader {
    User findById(String id);
    List<User> searchByName(String name);
    List<User> listAll();
}

public interface IUserWriter {
    void createUser(User user);
    void updateUser(User user);
    void deleteUser(String id);
}

public interface IUserPasswordManager {
    void resetPassword(String userId, String newPassword);
}

public interface IUserNotifier {
    void sendWelcomeEmail(String userId);
}

public interface IUserAuditor {
    List<String> getAuditLog(String userId);
}

// Admin dashboard only needs reads
public class AdminDashboardService implements IUserReader { ... }

// Full user management service implements all
public class UserManagementService implements IUserReader, IUserWriter,
    IUserPasswordManager, IUserNotifier, IUserAuditor { ... }
```

**Observable outcome:** ISP-compliant split: Key benefit: AdminDashboardService cannot accidentally call deleteUser — the interface doesn't include it.

## End-to-end outcome

After working through the stages, you should be able to explain:

- - UnsupportedOperationException is the ISP alarm.
- Any time you write throw new UnsupportedOperationException() in an interface implementation, that method doesn't belong in that interface.

## Alternatives considered

### Decision Guide

Decision Guide


## Failure and degraded modes

### ISP is closely related to:

- **Detection:** Rule of thumb: If you ask "when would a class mock or stub this method just to satisfy the interface?", that method doesn't belong in that interface.
- **User or operator impact:** Rule of thumb: If you ask "when would a class mock or stub this method just to satisfy the interface?", that method doesn't belong in that interface.

### When Fat Interfaces Are Acceptable

- **Detection:** 📊 ISP Decision Flow: When to Split an Interface The flowchart captures the single question that drives every ISP refactoring decision: do all clients use all the methods?
- **User or operator impact:** 📊 ISP Decision Flow: When to Split an Interface The flowchart captures the single question that drives every ISP refactoring decision: do all clients use all the methods?



## Scenario context

You're building an order service. The first version looks like this:

```architecture
{
  "version": 1,
  "title": "The Tightly Coupled Trap: When Changing a Database Breaks Business Logic - Storage Topology",
  "description": "Multi-tier caching and replicated storage pipeline ensuring fast reads and transactional consistency.",
  "view": "data-flow",
  "pattern": "cache-aside",
  "direction": "LR",
  "groups": […

Before making a design choice, clarify:

- You're building an order service.
- The first version looks like this: Six months later, you migrate to PostgreSQL.
- You search for every place MySQLDatabase() is used — it's woven through your order logic, your billing logic, your reporting.

**Concepts in play:** design-principles-solid, caching, jvm-internals-and-garbage-collection, consistency-replication

## Stage 1 — The Two Rules of Dependency Inversion

- The Dependency Inversion Principle has exactly two rules: 1.
- High-level modules should not depend on low-level modules.
- Both should depend on abstractions.
- Abstractions should not depend on details.

*Applies **design-principles-solid** to the decision above.*

**Observable outcome:** Abstractions should not depend on details.

## Stage 2 — The Principle: Abstractions Own the Contract

- The Dependency Inversion Principle has two parts: 1.
- High-level modules should not depend on low-level modules.
- Both should depend on abstractions.
- Abstractions should not depend on details.

*Applies **caching** to the decision above.*

```mermaid
graph LR
    subgraph Before DIP
        Biz1[OrderService] --> MySQL[MySQLDatabase]
        Biz1 --> Email1[SendGridClient]
    end
    subgraph After DIP
        Biz2[OrderService] --> IRepo[IOrderRepository abstraction]
        Biz2 --> IEmail[IEmailService abstraction]
        IRepo --> MySQL2[MySQLRepository]
        IRepo --> PG[PostgresRepository]
        IEmail --> Email2[SendGridEmailService]
        IEmail --> Mock[MockEmailService]
    end
```

**Observable outcome:** Abstractions should not depend on details.

## Stage 3 — DIP Dependency Direction

- Without DIP, high-level modules point arrows at low-level modules.
- With DIP, both point at abstractions in the middle — the direction of dependency is inverted.
- Reading the diagram: In the "With DIP" half, every arrow points AT the interface (the abstraction), never away from it.
- OrderService knows nothing about MySQL or SendGrid — only about the interface contracts.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
flowchart LR
    subgraph Without_DIP[Without DIP]
        A[OrderService] --> B[MySQLDatabase]
        A --> C[SendGridClient]
    end
    subgraph With_DIP[With DIP]
        D[OrderService] --> E[IOrderRepository]
        D --> F[IEmailService]
        G[MySQLRepository] --> E
        H[PostgresRepository] --> E
        I[SendGridEmailService] --> F
        J[MockEmailService] --> F
    end
```

**Observable outcome:** OrderService knows nothing about MySQL or SendGrid — only about the interface contracts.

## Stage 4 — The Interface as the Contract: Python and Java Examples

- Python (using ABC): Switch to Postgres: OrderService(PostgresOrderRepository()) .
- Java (using interface): 📊 DIP Correct Pattern: Both Layers Depend on the Abstraction This diagram shows the corrected DIP pattern: OrderService now points to the abstractions IOrderRepository and IEmailService rather t…
- Both MySQLOrderRepository and PostgresOrderRepository implement IOrderRepository from below, so swapping database engines requires zero changes to OrderService .
- MockEmailService implementing IEmailService is precisely what enables unit testing — tests inject the mock and verify behavior without sending real emails or touching a real database.

*Applies **consistency-replication** to the decision above.*

```python
from abc import ABC, abstractmethod

class IOrderRepository(ABC):
    @abstractmethod
    def save(self, order) -> None: ...

    @abstractmethod
    def find_by_id(self, order_id: str): ...

class MySQLOrderRepository(IOrderRepository):
    def save(self, order):
        # MySQL-specific implementation
        ...

class PostgresOrderRepository(IOrderRepository):
    def save(self, order):
        # Postgres-specific implementation
        ...

class OrderService:
    def __init__(self, repo: IOrderRepository):   # depends on interface
        self.repo = repo

    def place_order(self, order):
        self.repo.save(order)
```

```java
public interface IOrderRepository {
    void save(Order order);
    Order findById(String id);
}

public class OrderService {
    private final IOrderRepository repo;          // depends on interface

    public OrderService(IOrderRepository repo) {
        this.repo = repo;
    }

    public void placeOrder(Order order) {
        repo.save(order);
    }
}
```

**Observable outcome:** MockEmailService implementing IEmailService is precisely what enables unit testing — tests inject the mock and verify behavior without sending real emails or touching a real database.

## Stage 5 — Deep Dive: Dependency Injection at Runtime

- DIP says what to depend on (abstractions).
- Dependency Injection (DI) says how to supply the concrete implementation at runtime.
- Constructor injection is the simplest and most testable option for most cases.
- Testing benefit: With DIP, unit tests can inject a mock: No database needed to test business logic.

*Applies **design-principles-solid** to the decision above.*

```python
class FakeOrderRepository(IOrderRepository):
    def __init__(self):
        self.saved = []
    def save(self, order):
        self.saved.append(order)

def test_place_order():
    repo = FakeOrderRepository()
    svc = OrderService(repo)
    svc.place_order(Order(id="1"))
    assert len(repo.saved) == 1
```

**Observable outcome:** Testing benefit: With DIP, unit tests can inject a mock: No database needed to test business logic.

## Stage 6 — Real-World Application: DIP Across Systems

- Spring Boot example: Spring's @Autowired and @Repository / @Service annotations are DIP at the framework level.
- You declare @Autowired IUserRepository repo in a service, and Spring injects the appropriate implementation.
- Business logic never instantiates infrastructure classes directly.
- Hexagonal architecture (Ports and Adapters): This architecture pattern IS DIP at the system design level.

*Applies **caching** to the decision above.*

**Observable outcome:** Hexagonal architecture (Ports and Adapters): This architecture pattern IS DIP at the system design level.

## End-to-end outcome

After working through the stages, you should be able to explain:

- - DIP makes testing a first-class concern.
- When business logic depends on interfaces, every external dependency (DB, email, HTTP) can be swapped for a fake in tests.

## Alternatives considered

### Decision Guide

Decision Guide


## Failure and degraded modes

### Trade-offs & Failure Modes: When DIP Adds Complexity

- **Detection:** DIP is not always the right answer: A sign that DIP is applied incorrectly: your project has 40 interfaces, all of which have exactly one implementation.
- **User or operator impact:** DIP is not always the right answer: A sign that DIP is applied incorrectly: your project has 40 interfaces, all of which have exactly one implementation.



Build clean object boundaries and dependency direction.

SOLID Principles

## Scenario context

The Strategy Pattern replaces giant `if-else` or `switch` blocks with a family of interchangeable algorithm classes. Each strategy is a self-contained unit that can be swapped at runtime without touching the client code. The result: Open/Closed Principle compliance and dramatically easier testing.

---

Imagine a `PaymentProcessor` that handles Stripe, PayPal, Apple Pay, and crypto:

```java
void pay(String type, in…

This walkthrough focuses on **Stop Writing If-Else Hell: The Case for Strategy**.

Before making a design choice, clarify:

- Imagine a PaymentProcessor that handles Stripe, PayPal, Apple Pay, and crypto: The problem: every new payment method forces you to modify the core class, violating the Open/Closed Principle ( open for extension, closed…
- Tests become fragile and the class grows without bound.
- The Strategy Pattern fixes this by extracting each algorithm into its own class.

**Concepts in play:** design-patterns-gof, jvm-internals-and-garbage-collection, graph-traversal-algorithms, api-security-oauth2

## Stage 1 — The Three Components of the Strategy Pattern

- 📊 Class Hierarchy: Strategy Pattern

*Applies **design-patterns-gof** to the decision above.*

```mermaid
graph TD
    A[Client: PaymentCheckout] --> B[Context: PaymentProcessor]
    B --> C{Strategy interface: PaymentStrategy}
    C --> D[StripeStrategy]
    C --> E[PayPalStrategy]
    C --> F[ApplePayStrategy]
```

```mermaid
classDiagram
  class Context {
    -strategy: PaymentStrategy
    +setStrategy(s: PaymentStrategy)
    +checkout(amount: int)
  }
  class PaymentStrategy {
    <<interface>>
    +pay(amount: int)
  }
  class StripeStrategy {
    -apiKey: String
    +pay(amount: int)
  }
  class PayPalStrategy {
    -email: String
    +pay(amount: int)
  }
  class CryptoStrategy {
    -walletAddress: String
    +pay(amount: int)
  }
  Context --> PaymentStrategy
  PaymentStrategy <|.. StripeStrategy
  PaymentStrategy <|.. PayPalStrategy
  PaymentStrategy <|.. CryptoStrategy
```

**Observable outcome:** 📊 Class Hierarchy: Strategy Pattern

## Stage 2 — Full Implementation: Payment Processing Example

- Adding a new payment method (e.g., ApplePayStrategy ) requires zero changes to PaymentProcessor or any other existing class.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```java
// 1. Strategy interface
interface PaymentStrategy {
    void pay(int amount);
}

// 2. Concrete strategies
class StripeStrategy implements PaymentStrategy {
    private String apiKey;
    public StripeStrategy(String apiKey) { this.apiKey = apiKey; }

    @Override
    public void pay(int amount) {
        System.out.printf("Charging $%d via Stripe (key: %s)%n", amount, apiKey);
        // real Stripe API call here
    }
}

class PayPalStrategy implements PaymentStrategy {
    private String email;
    public PayPalStrategy(String email) { this.email = email; }

    @Override
    public void pay(int amount) {
        System.out.printf("Sending $%d to %s via PayPal%n", amount, email);
    }
}

// 3. Context
class PaymentProcessor {
    private PaymentStrategy strategy;

    public PaymentProcessor(PaymentStrategy strategy) {
        this.strategy = strategy;
    }

    // Swap strategy at runtime
    public void setStrategy(PaymentStrategy strategy) {
        this.strategy = strategy;
    }

    public void checkout(int amount) {
        strategy.pay(amount);   // delegate entirely to the strategy
    }
}

// 4. Client usage
public class Main {
    public static void main(String[] args) {
        PaymentProcessor processor = new PaymentProcessor(new StripeStrategy("sk_test_123"));
        processor.checkout(99);     // → Charging $99 via Stripe

        // Runtime swap: user switches to PayPal
        processor.setStrategy(new PayPalStrategy("user@example.com"));
        processor.checkout(49);     // → Sending $49 to user@example.com via PayPal
    }
}
```

**Observable outcome:** Adding a new payment method (e.g., ApplePayStrategy ) requires zero changes to PaymentProcessor or any other existing class.

## Stage 3 — Deep Dive: How Strategy Enables Open/Closed Design

- The Strategy Pattern achieves Open/Closed compliance through composition over inheritance .
- The Context holds an interface reference — not a concrete type — so any conforming object can be injected at runtime.
- This is a direct application of dependency inversion : high-level modules (Context) depend on abstractions (Strategy interface), not on low-level implementations.
- At runtime, the JVM dispatches pay() through a virtual method table — the same call site, different behavior, zero branching logic in the caller.

*Applies **graph-traversal-algorithms** to the decision above.*

**Observable outcome:** At runtime, the JVM dispatches pay() through a virtual method table — the same call site, different behavior, zero branching logic in the caller.

## Stage 4 — Runtime Strategy Switching Flow

- The real power of the Strategy Pattern is runtime flexibility — the ability to swap the algorithm in the middle of execution without restarting the application or recompiling a single line of existing code.
- Notice that the PaymentProcessor context class appears exactly once in this diagram and never changes shape.
- All variation lives in the leaf nodes — the concrete strategy objects.
- Adding CryptoStrategy is a new leaf, not a change to the graph.

*Applies **api-security-oauth2** to the decision above.*

```mermaid
graph TD
    A[Client Code] --> B[Context: PaymentProcessor created with StripeStrategy]
    B --> C{User changes payment method?}
    C -->|No| D[context.checkout called  delegates to StripeStrategy.pay]
    C -->|Yes| E[context.setStrategy called with new PayPalStrategy]
    E --> F[context.checkout called  delegates to PayPalStrategy.pay]
    D --> G[Payment result returned]
    F --> G
```

**Observable outcome:** Adding CryptoStrategy is a new leaf, not a change to the graph.

## Stage 5 — Real-World Applications: Where the Strategy Pattern Appears in Real Systems

- 

*Applies **design-patterns-gof** to the decision above.*

**Observable outcome:** You can explain how “Real-World Applications: Where the Strategy Pattern Appears in Real Systems” changes the architecture or implementation path.

## Stage 6 — What to Learn Next

- - Low-Level Design (LLD) for Tic-Tac-Toe - Low-Level Design Guide for Ride Booking - The Ultimate Data Structures Cheat Sheet

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

**Observable outcome:** - Low-Level Design (LLD) for Tic-Tac-Toe - Low-Level Design Guide for Ride Booking - The Ultimate Data Structures Cheat Sheet

## End-to-end outcome

Imagine a PaymentProcessor that handles Stripe, PayPal, Apple Pay, and crypto: The problem: every new payment method forces you to modify the core class, violating the Open/Closed Principle ( open for extension, closed for modification ).

## Alternatives considered

### Decision Guide: Strategy vs. Similar Patterns

Decision Guide: Strategy vs. Similar Patterns


## Failure and degraded modes

### Trade-offs & Failure Modes: When to Use Strategy (and When Not To)

- **Detection:** Use Strategy when: - You have multiple algorithms for the same task that differ only in behavior.
- **User or operator impact:** Use Strategy when: - You have multiple algorithms for the same task that differ only in behavior.



## Scenario context

Designing a Vending Machine is a classic low-level design interview problem that tests state-driven logic. By using the GoF State Pattern, we avoid nested conditional blocks and build a modular, thread-safe system in Java Spring Boot.

---

Imagine you are tasked with developing the control software for a next-generation office vending machine. The machine must accept coins of different denominations, track a dynami…

This walkthrough focuses on **Design Challenge: The Fragile Vending Machine**.

Before making a design choice, clarify:

- Imagine you are tasked with developing the control software for a next-generation office vending machine.
- The machine must accept coins of different denominations, track a dynamic inventory of snacks, validate user selections, dispense products, and return change.
- A naive approach might rely on nested conditional checks to manage the machine's state: This code is fragile.

**Concepts in play:** low-level-design-systems, design-principles-solid, jvm-internals-and-garbage-collection, api-gateway

## Stage 1 — Scope: Use Cases and System Actors

- Before drawing class structures, we must establish the system boundary and identify the core functional requirements.
- Customer: The primary user who inserts money, selects products, requests refunds, and collects snacks and change.
- Maintenance Technician: An administrative user who refills inventory, collects accumulated cash, and audits machine health.
- Core Functional Requirements (Use Cases) Insert Money: The Customer inserts coins of recognized denominations (Nickel, Dime, Quarter, Dollar).

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** Core Functional Requirements (Use Cases) Insert Money: The Customer inserts coins of recognized denominations (Nickel, Dime, Quarter, Dollar).

## Stage 2 — Architectural Blueprint: Class Diagram

- The class diagram below maps the relationships between the main components of our vending machine design, detailing variables, methods, and interface dependencies.
- This class diagram illustrates the implementation of the State Pattern.
- The VendingMachine maintains a reference to a VendingState interface and delegates all actions to it.
- The four concrete state implementations— IdleState , HasMoneyState , DispensingState , and OutOfStockState —override these actions to execute state-specific logic and trigger transitions by calling VendingMachine.setCur…

*Applies **design-principles-solid** to the decision above.*

```mermaid
classDiagram
    VendingMachine "1" *-- "1" VendingState : delegates to
    VendingMachine "1" *-- "1" Inventory : manages
    VendingState <|.. IdleState : implements
    VendingState <|.. HasMoneyState : implements
    VendingState <|.. DispensingState : implements
    VendingState <|.. OutOfStockState : implements
    class VendingState {
        <<interface>>
        +insertCoin(VendingMachine machine, Coin coin) void
        +selectProduct(VendingMachine machine, String slotId) void
        +dispense(VendingMachine machine) void
        +refund(VendingMachine machine) void
    }
    class VendingMachine {
        -VendingState currentState
        -Inventory inventory
        -int balance
        +setCurrentState(VendingState state) void
        +insertCoin(Coin coin) void
        +selectProduct(String slotId) void
        +dispense() void
        +refund() void
    }
```

**Observable outcome:** The four concrete state implementations— IdleState , HasMoneyState , DispensingState , and OutOfStockState —override these actions to execute state-specific logic and trigger transitions by calling VendingMachine.setCur…

## Stage 3 — Core Mechanics: Mapping the OOP Pillars

- Our design leverages the four core pillars of Object-Oriented Programming to ensure structural integrity: Abstraction: The VendingState interface defines a boundary.
- It hides state-specific transition rules from the VendingMachine and the client.
- The client calls generic methods like insertCoin without knowing how the machine transitions internally.
- Encapsulation: The VendingMachine encapsulates its internal variables—such as balance , selectedSlot , and inventory —restricting direct manipulation.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

**Observable outcome:** Encapsulation: The VendingMachine encapsulates its internal variables—such as balance , selectedSlot , and inventory —restricting direct manipulation.

## Stage 4 — Deep Dive: SOLID Walkthrough and Concurrency

- Let us walk through how our architecture implements SOLID design principles and handles concurrency in production.
- The Internals of State-Driven Execution Our vending machine design enforces multiple SOLID principles to maintain high codebase maintainability: Single Responsibility Principle (SRP): Each concrete state class has a sin…
- For example, IdleState only handles the initial coin insertion, delegating product selection warnings back to the client.
- Open-Closed Principle (OCP): Introducing a new state (e.g., MaintenanceState or CardAuthorizationState ) only requires writing a new class that implements VendingState and updating the transitions.

*Applies **api-gateway** to the decision above.*

**Observable outcome:** Open-Closed Principle (OCP): Introducing a new state (e.g., MaintenanceState or CardAuthorizationState ) only requires writing a new class that implements VendingState and updating the transitions.

## Stage 5 — Visualizing State Transitions: The Vending Flow

- To understand how the machine behaves as the user interacts with it, we map the lifecycle of a transaction.
- The diagram below shows the paths between states based on trigger actions.
- This state transition flowchart maps the operational phases of the vending machine.
- The system begins in the Idle state.

*Applies **low-level-design-systems** to the decision above.*

```mermaid
flowchart TD
    Idle([Idle State]) -->|insertCoin| HasMoney([Has Money State])
    HasMoney -->|insertCoin| HasMoney
    HasMoney -->|selectProduct - balance ok| Dispensing([Dispensing State])
    HasMoney -->|refund / cancel| Idle
    Dispensing -->|dispense completed| Idle
    Dispensing -->|dispense - empty| OutOfStock([Out of Stock State])
    OutOfStock -->|refund| Idle
```

**Observable outcome:** The system begins in the Idle state.

## Stage 6 — Real-World Endpoint: Spring REST API

- To expose our LLD simulation to the client, we implement a Spring Boot @RestController mapping endpoints to the VendingMachine singleton.
- This controller handles coin insertions, product selections, and cancel requests, executing state transitions concurrently inside Spring container threads.

*Applies **design-principles-solid** to the decision above.*

```java
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/vending")
public class VendingMachineController {

    private final VendingMachine machine = new VendingMachine();

    @GetMapping("/status")
    public VendingStatus getStatus() {
        return new VendingStatus(machine.getBalance(), machine.getSelectedSlot());
    }

    @PostMapping("/insert")
    public String insertCoin(@RequestParam Coin coin) {
        machine.insertCoin(coin);
        return "Balance updated: " + machine.getBalance();
    }

    @PostMapping("/select")
    public String selectProduct(@RequestParam String slotId) {
        machine.selectProduct(slotId);
        return "Selection processed.";
    }

    @PostMapping("/refund")
    public String refund() {
        machine.refund();
        return "Refund complete.";
    }
}

class VendingStatus {
    private final int balance;
    private final String selectedSlot;

    public VendingStatus(int balance, String selectedSlot) {
        this.balance = balance;
        this.selectedSlot = selectedSlot;
    }
    public int getBalance() { return balance; }
    public String getSelectedSlot() { return selectedSlot; }
}
```

**Observable outcome:** This controller handles coin insertions, product selections, and cancel requests, executing state transitions concurrently inside Spring container threads.

## End-to-end outcome

After working through the stages, you should be able to explain:

- When designing state-driven LLD systems: 1.
- Keep Context Synchronized: Always declare context methods that alter mutable variables (like insertCoin , selectProduct ) as synchronized to ensure thread-safety in multi-threaded container environments.
- State Pattern: Encapsulates state-specific logic in dedicated classes, avoiding nested if-else structures.
- OOP Abstraction: Hides transition details completely behind interface contracts.

## Alternatives considered

The source focuses on one primary design. A second architecture is not compared, so no alternative is invented here.

## Failure and degraded modes

### Trade-offs and Failure Modes: State Pattern Overhead

- **Detection:** Every architectural choice has trade-offs: Class Proliferation: The State Pattern requires creating a new class for every single state.
- **User or operator impact:** Every architectural choice has trade-offs: Class Proliferation: The State Pattern requires creating a new class for every single state.



## Scenario context

Domain-Driven Design (DDD) shifts the focus of software development from database schemas to core business logic. By implementing a rich domain model using Entities, Value Objects, and Aggregate Roots, we protect business invariants directly inside our code. This guide contrasts anemic domain models with rich DDD patterns in Java.

* * *



```architecture
{
  "version": 1,
  "title": "TLDR:** Domain-Driven Design (…

This walkthrough focuses on **Concept: Transitioning to Domain-Driven Design**.

Before making a design choice, clarify:

- In many enterprise software applications, developers fall into the trap of designing systems database-first.
- They create database tables, map them directly to Java classes using ORM frameworks (like Hibernate/JPA), generate standard getters and setters for every field, and write all business logic in procedural service classes.
- This anti-pattern is known as the Anemic Domain Model .

**Concepts in play:** design-patterns-gof, jvm-internals-and-garbage-collection, caching, consistency-replication

## Stage 1 — Mechanics: Entities, Value Objects, and Aggregates

- To build a rich domain model, DDD divides domain concepts into three primary building blocks: 1\.
- Entities An Entity has a thread of continuity and a unique identity that remains constant throughout its lifecycle, even if its properties change.
- For example, an Order is an entity because it is identified by a unique ID, even if items are added or the shipping status changes.
- Value Objects A Value Object represents a descriptive aspect of the domain and has no unique identity.

*Applies **design-patterns-gof** to the decision above.*

**Observable outcome:** Value Objects A Value Object represents a descriptive aspect of the domain and has no unique identity.

## Stage 2 — Flow: Domain Event Lifecycle Sequence

- The flowchart below visualizes how an Aggregate Root processes a command, validates invariants, mutates state, registers a domain event, and transactionally commits changes: The table below contrasts the behavioral diff…

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
flowchart TD
    Cmd[Client Command: e.g. AddItemToOrder] -->|Invoke Method| AR[Aggregate Root: Order]
    AR -->|1. Validate Business Invariants| InvCheck{IsValid?}
    InvCheck -->|No| Err[Throw DomainException]
    InvCheck -->|Yes| Mutate[2. Mutate Internal State]
    Mutate -->|3. Register Domain Event| Event[OrderLineAddedEvent]
    Event -->|4. Save Root to Repository| Save[Database Transaction Commit]
    Save -->|5. Publish Event to Broker| EventBus[Outbox / Event Broker]
```

**Observable outcome:** The flowchart below visualizes how an Aggregate Root processes a command, validates invariants, mutates state, registers a domain event, and transactionally commits changes: The table below contrasts the behavioral diff…

## Stage 3 — Deep Dive: Object Encapsulation & Thread Consistency

- Designing domain boundaries requires a clear understanding of transactional boundaries, consistency models, and performance overheads.
- Aggregate Root Consistency Internals The Aggregate Root guarantees that all rules within the aggregate are satisfied during any operation.
- Because external objects cannot modify internal entities directly, the root controls all state transitions.
- For example, if a Customer aggregate has a list of Address objects, changes to the primary address must go through Customer.changeAddress() , allowing the customer root to verify that the customer account is active befo…

*Applies **caching** to the decision above.*

**Observable outcome:** For example, if a Customer aggregate has a list of Address objects, changes to the primary address must go through Customer.changeAddress() , allowing the customer root to verify that the customer account is active befo…

## Stage 4 — Advanced Concepts: Bounded Context Integration and Domain Events

- In large-scale systems, different departments use the same term to describe different concepts.
- For example, to Sales, a Product represents a price and description.
- To Shipping, a Product represents weight and dimensions.
- Instead of building a single, bloated product model, DDD divides the system into Bounded Contexts (e.g.

*Applies **consistency-replication** to the decision above.*

**Observable outcome:** Instead of building a single, bloated product model, DDD divides the system into Bounded Contexts (e.g.

## Stage 5 — Applications: Real-World Enterprise Architectures

- E-Commerce Checkouts: Managing inventories and applying discount rules within an Order aggregate before committing payment.
- Banking Ledger Systems: Ensuring that transfer amounts match available balances across account roots while preventing concurrent double-spending.
- SaaS Multi-Tenant Roles: Managing permissions and user groups within tenant boundaries using Bounded Context mappings.

*Applies **design-patterns-gof** to the decision above.*

```architecture
{
  "version": 1,
  "title": "Applications: Real-World Enterprise Architectures - Subsystem Overview",
  "description": "Decoupled system architecture isolating ingress, stateless logic, and persistent datastores.",
  "view": "high-level",
  "pattern": "microservices",
  "direction": "LR",
  "groups": [
    { "id": "edge", "label": "Edge Traffic Ingress", "tone": "slate" },
    { "id": "services", "label": "Stateless Microservices", "tone": "blue" },
    { "id": "data", "label": "Datastore Infrastructure", "tone": "green" }
  ],
  "nodes": [
    { "id": "gw", "component": "api-gateway", "label": "API Gateway", "group": "edge", "badge": "TLS & Auth" },
    { "id": "app", "component": "workflow-service", "label": "Domain Service", "group": "services", "badge": "Stateless" },
    { "id": "cache", "component": "redis", "label": "Redis Cache", "group": "data", "badge": "Sub-ms Reads" },
    { "id": "db", "component": "postgres", "label": "Transactional DB", "group": "data", "badge": "ACID Log" }
  ],
  "edges": [
    { "from": "gw", "to": "app", "kind": "request", "label": "gRPC Request" },
    { "from": "app", "to": "cache", "kind": "read", "label": "Cache Lookups" },
    { "from": "app", "to": "db", "kind": "write", "label": "Durable Write" }
  ],
  "takeaway": {
    "title": "Architecture Boundary Invariant",
    "body": "Stateless compute nodes scale horizontally while shielding underlying database clusters behind fast cache layers."
  }
}
```

**Observable outcome:** SaaS Multi-Tenant Roles: Managing permissions and user groups within tenant boundaries using Bounded Context mappings.

## Stage 6 — Practical Implementation: Java Before/After Case Study

- Let us compare an anemic implementation with a rich DDD domain model implementation of an Order aggregate in Java.
- Before: The Anemic Domain Model (Anti-Pattern) Here, the entity is a passive data holder, and the validation logic is externalized in a service, allowing any class to bypass rules by calling setters directly.
- After: The Rich DDD Domain Model (Recommended Pattern) In this implementation, the Order aggregate root enforces invariants within its boundary.
- Internal data structures are encapsulated (returned as unmodifiable lists), and fields can only be modified through explicit domain methods.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```java
// Anemic Entity
import java.util.List;

public class AnemicOrder {
    private Long id;
    private String status;
    private double totalAmount;
    private List<AnemicOrderLine> lines;

    // Standard getters/setters exposing internals
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
    public double getTotalAmount() { return totalAmount; }
    public void setTotalAmount(double totalAmount) { this.totalAmount = totalAmount; }
    public List<AnemicOrderLine> getLines() { return lines; }
    public void setLines(List<AnemicOrderLine> lines) { this.lines = lines; }
}

// Procedural Service executing business rules
class AnemicOrderService {
    public void addOrderLine(AnemicOrder order, AnemicOrderLine line) {
        // Validation logic is written outside the entity
        if ("SHIPPED".equals(order.getStatus())) {
            throw new IllegalStateException("Cannot add items to a shipped order");
        }
        order.getLines().add(line);
        order.setTotalAmount(order.getTotalAmount() + (line.getPrice() * line.getQuantity()));
    }
}
```

```java
// Immutable Value Object representing Money
import java.math.BigDecimal;
import java.util.Objects;

final class Money {
    private final BigDecimal amount;
    private final String currency;

    public Money(BigDecimal amount, String currency) {
        if (amount == null || currency == null) {
            throw new IllegalArgumentException("Amount and currency cannot be null");
        }
        this.amount = amount;
        this.currency = currency;
    }

    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("Currency mismatch");
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }

    public BigDecimal getAmount() { return amount; }
    public String getCurrency() { return currency; }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Money)) return false;
        Money money = (Money) o;
        return amount.compareTo(money.amount) == 0 && currency.equals(money.currency);
    }

    @Override
    public int hashCode() {
        return Objects.hash(amount, currency);
    }
}

// Child Entity inside the Aggregate Boundary
class OrderLine {
    private final String productId;
    private final Money price;
    private final int quantity;

    public OrderLine(String productId, Money price, int quantity) {
        if (productId == null || price == null || quantity <= 0) {
            throw new IllegalArgumentException("Invalid order line values");
        }
        this.productId = productId;
        this.price = price;
        this.quantity = quantity;
    }

    public Money calculateSubtotal() {
        return new Money(price.getAmount().multiply(BigDecimal.valueOf(quantity)), price.getCurrency());
    }
}

// Aggregate Root
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

public class Order {
    private final Long id;
    private OrderStatus status;
    private Money totalAmount;
    private final List<OrderLine> lines;

    public enum OrderStatus { DRAFT, CONFIRMED, SHIPPED }

    public Order(Long id, String currency) {
        this.id = id;
        this.status = OrderStatus.DRAFT;
        this.totalAmount = new Money(BigDecimal.ZERO, currency);
        this.lines = new ArrayList<>();
    }

    // Method encapsulates state mutation and checks business rules
    public void addProduct(String productId, Money price, int quantity) {
        // Enforce business invariant
        if (this.status == OrderStatus.SHIPPED) {
            throw new IllegalStateException("Cannot modify an order that has already been shipped.");
        }
        
        OrderLine line = new OrderLine(productId, price, quantity);
        this.lines.add(line);
        
        // Update total using value object addition
        this.totalAmount = this.totalAmount.add(line.calculateSubtotal());
    }

    public void ship() {
        if (this.lines.isEmpty()) {
            throw new IllegalStateException("Cannot ship an empty order.");
        }
        this.status = OrderStatus.SHIPPED;
    }

    // Expose read-only view of child collection to preserve encapsulation
    public List<OrderLine> getLines() {
        return Collections.unmodifiableList(this.lines);
    }

    public Long getId() { return id; }
    public OrderStatus getStatus() { return status; }
    public Money getTotalAmount() { return totalAmount; }
}
```

**Observable outcome:** Internal data structures are encapsulated (returned as unmodifiable lists), and fields can only be modified through explicit domain methods.

## End-to-end outcome

After working through the stages, you should be able to explain:

- Rich Domain Model: Combines data and behavior inside entities, enforcing invariants directly in the domain layer.
- Value Objects: Immutable objects with no identity.

## Alternatives considered

### Decision Guide: Anemic vs. Rich Domain Models

Use this guide to choose the right model for your application:


## Failure and degraded modes

### Trade-offs and Failure Modes

- **Detection:** Complexity Overhead: Splitting code into clean domain layers, applications layers, and infrastructure mapping repositories requires more classes and boilerplate converters.
- **User or operator impact:** Complexity Overhead: Splitting code into clean domain layers, applications layers, and infrastructure mapping repositories requires more classes and boilerplate converters.

### Lessons Learned: Common DDD Pitfalls

- **Detection:** Design Large Aggregates: Keeping large collections inside an aggregate makes the aggregate slow to load and save, and causes database locking issues.
- **User or operator impact:** Design Large Aggregates: Keeping large collections inside an aggregate makes the aggregate slow to load and save, and causes database locking issues.



Learn state, strategy, and aggregate boundaries for realistic object models.

Behavioral and Domain Patterns

## Scenario context

Tic-Tac-Toe looks trivial — until the interviewer says "make it N×N with P players and pluggable winning rules." The key design decisions: a Board abstracted from piece identity, a Strategy Pattern for win conditions, and a Factory for player creation. Getting these right is the interview objective.

---

A fixed two-player array breaks the moment a third player is added. A `Deque<Player>` implements round-robin rot…

This walkthrough focuses on **Deep Dive: Why the Deque Is the Right Structure for Turn Management**.

Before making a design choice, clarify:

- A fixed two-player array breaks the moment a third player is added.
- A Deque<Player implements round-robin rotation with two operations: pollFirst() takes the current player and offerLast() returns them after their turn.
- This scales to N players without index arithmetic.

**Concepts in play:** low-level-design-systems, design-principles-solid, stack-and-queue-data-structures, jvm-internals-and-garbage-collection

## Stage 1 — The Basics: Object-Oriented Design for Games

- A common interview mistake is designing Tic-Tac-Toe as a 3×3 hardcoded grid.
- The interviewer immediately asks: "What if I want a 10×10 board?
- Or 4-in-a-row instead of 3?" The design that handles this is what we're building.
- Low-level design interviews test whether you can decompose a system into clean, extensible objects.

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** Low-level design interviews test whether you can decompose a system into clean, extensible objects.

## Stage 2 — From 3×3 Toy to OOP Interview Test

- Every LLD interview question hides the same trap: the naive solution is obvious, so the interviewer immediately extends it.
- Naive version: a fixed 3×3 grid, two hardcoded players, if-else win check.
- Extended version: N×N board, P players with distinct symbols, swappable winning strategies (row, column, diagonal, custom), and clean state transitions.
- This post builds the extensible version step by step.

*Applies **design-principles-solid** to the decision above.*

**Observable outcome:** This post builds the extensible version step by step.

## Stage 3 — Core Entities — Board, Piece, Player, Game

- A clean OOP model needs exactly four entities: Enums and value objects first:

*Applies **stack-and-queue-data-structures** to the decision above.*

```mermaid
classDiagram
    class PlayingPiece {
        +PieceType type
    }
    class Player {
        +String name
        +PlayingPiece piece
    }
    class Board {
        +int size
        +PlayingPiece[][] grid
        +placePiece(row, col, piece)
        +isFull()
    }
    class Game {
        +Board board
        +Deque players
        +WinningStrategy strategy
        +startGame()
        +checkWinner(row, col, piece)
    }
    Player --> PlayingPiece
    Game --> Board
    Game --> Player
    Game --> WinningStrategy
```

```java
enum PieceType { X, O, STAR, HASH }  // extensible — add symbols without changing Board

class PlayingPiece {
    final PieceType type;
    PlayingPiece(PieceType t) { this.type = t; }
}

class Player {
    final String name;
    final PlayingPiece piece;
    Player(String name, PlayingPiece piece) {
        this.name  = name;
        this.piece = piece;
    }
}
```

**Observable outcome:** A clean OOP model needs exactly four entities: Enums and value objects first:

## Stage 4 — Extending to N×N: Board with Variable Size

- The Board must not hardcode 3.
- Size is a constructor parameter; the grid is a 2D array of nullable PlayingPiece .
- Multiple player support — use a Deque for round-robin turns, regardless of player count: Each turn: poll() from front, play, then offerLast() to back.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```java
class Board {
    final int size;
    private final PlayingPiece[][] grid;

    Board(int size) {
        this.size = size;
        this.grid = new PlayingPiece[size][size];
    }

    public boolean placePiece(int row, int col, PlayingPiece piece) {
        if (row < 0 || row >= size || col < 0 || col >= size) return false;
        if (grid[row][col] != null) return false;   // cell occupied
        grid[row][col] = piece;
        return true;
    }

    public PlayingPiece getPiece(int row, int col) { return grid[row][col]; }

    public boolean isFull() {
        for (PlayingPiece[] row : grid)
            for (PlayingPiece p : row)
                if (p == null) return false;
        return true;
    }
}
```

```java
Deque<Player> players = new LinkedList<>();
players.add(new Player("Alice", new PlayingPiece(PieceType.X)));
players.add(new Player("Bob",   new PlayingPiece(PieceType.O)));
players.add(new Player("Carol", new PlayingPiece(PieceType.STAR)));
```

**Observable outcome:** Multiple player support — use a Deque for round-robin turns, regardless of player count: Each turn: poll() from front, play, then offerLast() to back.

## Stage 5 — OOP Pillars Applied in the Game Design

- Each of the four OOP pillars maps directly onto a specific class or interface in this design — not as a textbook exercise, but as a concrete decision that makes the code extensible.
- Encapsulation in practice: Board 's constructor allocates grid as a private field.
- The only public surface is placePiece(row, col, piece) , getPiece(row, col) , and isFull() .
- If the internal representation changes from a 2D array to a Map<Position, Piece , no external class breaks — callers never touch grid[row][col] directly.

*Applies **low-level-design-systems** to the decision above.*

```mermaid
classDiagram
    direction LR
    class Player {
        <<abstract>>
        +Piece piece
        +makeMove(Board) Move*
    }
    class HumanPlayer {
        +makeMove(Board) Move
    }
    class AiPlayer {
        +makeMove(Board) Move
    }
    class WinStrategy {
        <<interface>>
        +checkWin(Board, Piece) bool
    }
    class RowColWinStrategy
    class DiagonalWinStrategy
    HumanPlayer --|> Player : extends
    AiPlayer --|> Player : extends
    RowColWinStrategy ..|> WinStrategy : implements
    DiagonalWinStrategy ..|> WinStrategy : implements
    Game --> Player : uses
    Game --> WinStrategy : depends on
```

**Observable outcome:** If the internal representation changes from a 2D array to a Map<Position, Piece , no external class breaks — callers never touch grid[row][col] directly.

## Stage 6 — SOLID Principles in the Tic-Tac-Toe Design

- Every SOLID principle surfaces in a specific, traceable design decision here — not as abstract advice: OCP in practice: the product team wants a "diagonal-only" win rule for a new game variant.
- You write DiagonalOnlyWinStrategy implements WinStrategy .
- Existing Game , Board , and RowColWinStrategy are untouched.
- The open/closed boundary is the WinStrategy interface.

*Applies **design-principles-solid** to the decision above.*

```java
// Game depends on the abstraction — never on a concrete class
class Game {
    private final WinStrategy strategy;

    Game(Board board, List<Player> players, WinStrategy strategy) {
        this.strategy = strategy;   // injected — any WinStrategy works here
    }
}

// The call site decides which concrete strategy is used — Game never knows
Game standard = new Game(board, players, new RowColWinStrategy());
Game variant  = new Game(board, players, new DiagonalOnlyWinStrategy());
```

**Observable outcome:** The open/closed boundary is the WinStrategy interface.

## End-to-end outcome

A fixed two-player array breaks the moment a third player is added.

## Alternatives considered

### Decision Guide: When to Apply This OOP Pattern

Decision Guide: When to Apply This OOP Pattern


## Failure and degraded modes

### Trade-offs & Failure Modes: Trade-offs and Design Decisions

- **Detection:** Strategy Pattern for win conditions: Passing WinningStrategy into Game via constructor injection means adding a new win rule is a new class — zero changes to Game .
- **User or operator impact:** Strategy Pattern for win conditions: Passing WinningStrategy into Game via constructor injection means adding a new win rule is a new class — zero changes to Game .



## Scenario context

You pull up to a mall garage. Three things happen:
1. **Entry gate:** You press a button → get a ticket → gate opens.
2. **Parking:** Find a spot (the system might display "Floor 2, Spot 14").
3. **Exit:** Scan your ticket → system calculates fee based on time parked → gate opens.

The software behind this manages hundreds of concurrent vehicles across multiple floors, spot types, and pricing tiers.

---

This walkthrough focuses on **The Mall Garage Problem**.

Before making a design choice, clarify:

- Entry gate: You press a button → get a ticket → gate opens.
- Parking: Find a spot (the system might display "Floor 2, Spot 14").
- Exit: Scan your ticket → system calculates fee based on time parked → gate opens.

**Concepts in play:** tree-data-structures, low-level-design-systems, vector-databases-rag, design-patterns-gof

## Stage 1 — Parking Lot Design Basics

- Before writing any code, it helps to map out the real-world entities the system must represent.
- Spot Types — Not every bay fits every vehicle.
- A typical garage divides its spaces into three tiers: Vehicle Types — Each vehicle carries a licensePlate and a VehicleType enum ( BIKE , CAR , TRUCK ).
- The type determines which spot tier it can occupy — a TRUCK cannot squeeze into a CompactSpot .

*Applies **tree-data-structures** to the decision above.*

**Observable outcome:** The type determines which spot tier it can occupy — a TRUCK cannot squeeze into a CompactSpot .

## Stage 2 — The Domain Model

- Hierarchy: - ParkingSpot → subclasses: BikeSpot , CompactSpot , LargeSpot - Vehicle → subclasses: Bike , Car , Truck - ParkingLot → Singleton (one physical lot, one controller)

*Applies **low-level-design-systems** to the decision above.*

```mermaid
classDiagram
    class ParkingLot {
        -static ParkingLot instance
        +List~ParkingFloor~ floors
        -PricingStrategy pricingStrategy
        +Ticket park(Vehicle v)
        +double exit(Ticket t)
    }
    class ParkingFloor {
        +int floorNumber
        -Map~VehicleType,PriorityQueue~ heaps
        +ParkingSpot findNearest(VehicleType t)
        +void releaseSpot(ParkingSpot s)
    }
    class ParkingSpot {
        <<abstract>>
        +int id
        +boolean isFree
        +VehicleType type
        +void assign(Vehicle v)
        +void free()
    }
    class BikeSpot {
        +VehicleType type = BIKE
    }
    class CompactSpot {
        +VehicleType type = CAR
    }
    class LargeSpot {
        +VehicleType type = TRUCK
    }
    class Vehicle {
        <<abstract>>
        +String licensePlate
        +VehicleType type
    }
    class Bike
    class Car
    class Truck
    class Ticket {
        +Vehicle vehicle
        +ParkingSpot spot
        +Instant entryTime
    }
    class PricingStrategy {
        <<interface>>
        +calculateFee(VehicleType type, long minutes) double
    }
    class HourlyPricing {
        +calculateFee(VehicleType type, long minutes) double
    }

    ParkingLot "1" *-- "many" ParkingFloor : owns
    ParkingFloor "1" *-- "many" ParkingSpot : contains
    BikeSpot --|> ParkingSpot : extends
    CompactSpot --|> ParkingSpot : extends
    LargeSpot --|> ParkingSpot : extends
    Bike --|> Vehicle : extends
    Car --|> Vehicle : extends
    Truck --|> Vehicle : extends
    Ticket --> Vehicle : records
    Ticket --> ParkingSpot : records
    ParkingLot o-- PricingStrategy : uses
    HourlyPricing ..|> PricingStrategy : implements
```

**Observable outcome:** Hierarchy: - ParkingSpot → subclasses: BikeSpot , CompactSpot , LargeSpot - Vehicle → subclasses: Bike , Car , Truck - ParkingLot → Singleton (one physical lot, one controller)

## Stage 3 — OOP Pillars in the Parking Lot Domain

- The four OOP pillars are not abstract ideals here — each one maps to a concrete class or interface in this design.
- Encapsulation — ParkingFloor hides its Min-Heap ParkingFloor owns a Map<VehicleType, PriorityQueue<ParkingSpot internally.
- No external class ever touches that map directly.
- The public surface is exactly two methods: findNearest(VehicleType) (wraps poll() ) and releaseSpot(ParkingSpot) (wraps offer() ).

*Applies **vector-databases-rag** to the decision above.*

```mermaid
stateDiagram-v2
    [*] --> AVAILABLE : spot added to Min-Heap
    AVAILABLE --> OCCUPIED : findNearest()  assign(vehicle)
    OCCUPIED --> AVAILABLE : releaseSpot()  re-insert into heap
    AVAILABLE --> [*] : floor decommissioned
```

**Observable outcome:** The public surface is exactly two methods: findNearest(VehicleType) (wraps poll() ) and releaseSpot(ParkingSpot) (wraps offer() ).

## Stage 4 — Finding the Nearest Spot: Min-Heap

- A naive O(N) linear scan through all spots is too slow for a large garage.
- Optimized: Use a Min-Heap (priority queue ordered by spot ID, lowest = nearest entrance) per vehicle type per floor.
- Operations: - findNearest(CAR) → heaps.get(CAR).poll() → O(log N) - releaseSpot(spot) → heaps.get(spot.type).offer(spot) → O(log N) For N = 1000 spots per floor: log₂(1000) ≈ 10 operations vs.

*Applies **design-patterns-gof** to the decision above.*

```
Floor 1 Compact Heap: [101, 103, 107, ...]   ← pop 101 in O(log N)
Floor 1 Large Heap:   [150, 155, ...]
```

**Observable outcome:** Operations: - findNearest(CAR) → heaps.get(CAR).poll() → O(log N) - releaseSpot(spot) → heaps.get(spot.type).offer(spot) → O(log N) For N = 1000 spots per floor: log₂(1000) ≈ 10 operations vs.

## Stage 5 — Deep Dive: Factory and Strategy Patterns

- Callers use VehicleFactory.create(VehicleType.CAR, "ABC-123") — never new Car(...) directly.
- This decouples object creation from business logic and makes it easy to add ElectricVehicle later.

*Applies **tree-data-structures** to the decision above.*

```java
public class VehicleFactory {
    public static Vehicle create(VehicleType type, String plate) {
        return switch (type) {
            case BIKE   -> new Bike(plate);
            case CAR    -> new Car(plate);
            case TRUCK  -> new Truck(plate);
        };
    }
}
```

**Observable outcome:** This decouples object creation from business logic and makes it easy to add ElectricVehicle later.

## Stage 6 — Strategy Pattern for Pricing

- Pricing rules vary (hourly, daily, weekend, EV charging surcharge): The ParkingLot holds a reference to any PricingStrategy .
- Swapping from HourlyPricing to DynamicPricing requires zero changes to the rest of the code.
- 📊 Factory and Strategy: Class Diagram This class diagram extends the core domain model to show the full Factory and Strategy pattern integration, including the VehicleFactory creation point, the pluggable PricingStrate…
- The key relationship is that ParkingLot depends on interfaces ( PricingStrategy , SpotAllocator ) rather than concrete classes, which is what allows EVSpot and ChargingPricing to be added without modifying any existing…

*Applies **low-level-design-systems** to the decision above.*

```java
public interface PricingStrategy {
    double calculateFee(VehicleType type, long parkingMinutes);
}

public class HourlyPricing implements PricingStrategy {
    public double calculateFee(VehicleType type, long minutes) {
        double ratePerHour = type == VehicleType.TRUCK ? 3.50 :
                             type == VehicleType.CAR   ? 2.00 : 1.00;
        return ratePerHour * Math.ceil(minutes / 60.0);
    }
}
```

```mermaid
classDiagram
    class VehicleFactory {
        +create(VehicleType, String) Vehicle
    }
    class PricingStrategy {
        <<interface>>
        +calculateFee(VehicleType, long) double
    }
    class HourlyPricing {
        +calculateFee(VehicleType, long) double
    }
    class ChargingPricing {
        +calculateFee(VehicleType, long) double
    }
    class SpotAllocator {
        <<interface>>
        +findNearest(VehicleType, List~ParkingFloor~) Optional~ParkingSpot~
        +release(ParkingSpot, List~ParkingFloor~) void
    }
    class NearestFirstAllocator {
        +findNearest(VehicleType, List~ParkingFloor~) Optional~ParkingSpot~
        +release(ParkingSpot, List~ParkingFloor~) void
    }
    class EVSpot {
        +chargerType String
        +canFit(VehicleType) boolean
    }
    class ParkingLot {
        -PricingStrategy pricingStrategy
        -SpotAllocator allocator
        +park(Vehicle) Ticket
        +exit(Ticket) double
    }
    HourlyPricing ..|> PricingStrategy : implements
    ChargingPricing ..|> PricingStrategy : implements
    NearestFirstAllocator ..|> SpotAllocator : implements
    ParkingLot o-- PricingStrategy : uses (injected)
    ParkingLot o-- SpotAllocator : uses (injected)
    VehicleFactory --> Vehicle : creates
    EVSpot --|> ParkingSpot : extends
```

**Observable outcome:** The key relationship is that ParkingLot depends on interfaces ( PricingStrategy , SpotAllocator ) rather than concrete classes, which is what allows EVSpot and ChargingPricing to be added without modifying any existing…

## End-to-end outcome

Entry gate: You press a button → get a ticket → gate opens.

## Alternatives considered

### Decision Guide: When to Apply These Parking Lot Patterns

Start simple: a flat HashMap<SpotId, Spot works for a garage under 50 spots.


## Failure and degraded modes

### Trade-offs & Failure Modes in Parking Lot Design

- **Detection:** Trade-offs & Failure Modes in Parking Lot Design
- **User or operator impact:** Trade-offs & Failure Modes in Parking Lot Design



## Scenario context

This is the code companion to the [Parking Lot System Design](./lld-parking-lot-system) post. We implement the core classes (`ParkingLot`, `ParkingSpot`, `Ticket`) in Java, apply the **Singleton**, **Factory**, and **Strategy** patterns, and use a Min-Heap to find the nearest available spot in O(log n).

---

### Vehicle Hierarchy

```java
public enum VehicleType { BIKE, CAR, TRUCK }

public abstract class Vehicle {…

This walkthrough focuses on **The Domain Model: Vehicles, Spots, and Tickets**.

Before making a design choice, clarify:

- Vehicle Hierarchy Parking Spot Hierarchy 📊 ParkingSpot Lifecycle States The state diagram shows the complete two-state lifecycle every ParkingSpot instance goes through: it enters FREE when addSpot() places it into the…
- The synchronized keyword on both assign() and free() is what makes this state machine thread-safe: two threads competing to take the same free spot will serialize at the monitor, so only one will see isFree == true and…
- The FREE → [ ] edge represents lot decommissioning — a rare but necessary transition that prevents the heap from holding references to removed spots.

**Concepts in play:** tree-data-structures, low-level-design-systems, jvm-internals-and-garbage-collection, design-patterns-gof

## Stage 1 — ParkingFloor: Managing Spots via a Min-Heap

- Each floor maintains a Min-Heap per vehicle type.
- The heap is ordered by spot ID — the smallest ID = nearest to the entrance.
- - findNearest() → O(1) peek, O(log n) remove.
- - freeSpot() → O(log n) re-insert.

*Applies **tree-data-structures** to the decision above.*

```java
import java.util.PriorityQueue;
import java.util.Map;
import java.util.HashMap;

public class ParkingFloor {
    private final int floorNumber;
    private final Map<VehicleType, PriorityQueue<ParkingSpot>> availableSpots;

    public ParkingFloor(int floorNumber) {
        this.floorNumber = floorNumber;
        availableSpots = new HashMap<>();
        for (VehicleType type : VehicleType.values()) {
            availableSpots.put(type,
                new PriorityQueue<>((a, b) -> a.getId() - b.getId()));
        }
    }

    public synchronized ParkingSpot findAndAssign(Vehicle v) {
        PriorityQueue<ParkingSpot> heap = availableSpots.get(v.getType());
        if (heap.isEmpty()) return null;
        ParkingSpot spot = heap.poll();   // O(log n)
        spot.assign(v);
        return spot;
    }

    public synchronized void releaseSpot(ParkingSpot spot) {
        spot.free();
        availableSpots.get(spot.getType()).offer(spot);   // O(log n)
    }

    public void addSpot(ParkingSpot spot) {
        availableSpots.get(spot.getType()).offer(spot);
    }
}
```

```mermaid
flowchart TD
    Vehicle["Vehicle.getType() = CAR"] --> Floor["ParkingFloor.findAndAssign()"]
    Floor --> Heap[MinHeap[CompactSpot] peek  Spot #3]
    Heap -->|poll O(log n)| Spot["Spot #3: assign(vehicle)"]
    Spot --> Ticket["Issue Ticket(spotId=3, entryTime=now)"]
```

**Observable outcome:** - freeSpot() → O(log n) re-insert.

## Stage 2 — System Flow: Vehicle Entry to Exit

- When a vehicle arrives at the gate, the request flows through three layers before a spot is assigned and a ticket issued.
- Understanding this top-down call chain makes it clear why synchronization lives at the floor level rather than the lot level.
- This end-to-end flowchart exposes two structural decisions that are easy to miss when reading the code alone.
- First, the D → C back-edge represents the floor iteration loop in ParkingLot.park() : the lot scans floors in order and retries until it finds one with capacity, which means floor ordering matters — a low-numbered floor…

*Applies **low-level-design-systems** to the decision above.*

```mermaid
flowchart TD
    A[Vehicle arrives at gate] --> B["Gate calls ParkingLot.park(vehicle)"]
    B --> C[Iterate ParkingFloor list]
    C --> D{Floor has available spot for vehicle type?}
    D -->|No| C
    D -->|Yes| E["floor.findAndAssign(vehicle) Min-Heap poll O log n"]
    E --> F["spot.assign(vehicle) synchronized"]
    F --> G[Issue Ticket vehicle + spot + floor + entryTime]
    G --> H[Vehicle parks]
    H --> I["Vehicle exits:  lot.exit(ticket)"]
    I --> J["floor.releaseSpot(spot) Min-Heap re-insert"]
    J --> K[FeeCalculator.calculate type + duration]
    K --> L[Return fee, spot freed]
```

```mermaid
sequenceDiagram
    participant Gate as Entry Gate
    participant PL as ParkingLot
    participant PF as ParkingFloor
    participant PS as ParkingSpot
    participant T as Ticket
    Gate->>PL: park(vehicle)
    loop each floor
        PL->>PF: findAndAssign(vehicle)
        PF->>PF: heap.poll()  O(log n)
        PF->>PS: assign(vehicle) synchronized
        PS-->>PF: true (spot assigned)
        PF-->>PL: ParkingSpot reference
    end
    PL->>T: new Ticket(vehicle, spot, floor, now)
    T-->>Gate: Ticket issued
```

**Observable outcome:** First, the D → C back-edge represents the floor iteration loop in ParkingLot.park() : the lot scans floors in order and retries until it finds one with capacity, which means floor ordering matters — a low-numbered floor…

## Stage 3 — Deep Dive: ParkingLot — Singleton + Multi-Floor Search

- Double-checked locking: The volatile keyword on instance prevents instruction reordering.
- Both null checks prevent creating two instances under race conditions at startup.
- Internals: Thread Safety in ParkingLot The park() method itself is not synchronized at the ParkingLot level — synchronization happens at ParkingFloor.findAndAssign() .
- This is intentional: locking the entire lot for every park operation would serialize all gates.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```java
import java.time.Instant;
import java.util.List;
import java.util.ArrayList;

public class ParkingLot {
    private static volatile ParkingLot instance;
    private final List<ParkingFloor> floors = new ArrayList<>();
    private final FeeStrategy feeStrategy;

    private ParkingLot(FeeStrategy feeStrategy) {
        this.feeStrategy = feeStrategy;
    }

    public static ParkingLot getInstance(FeeStrategy feeStrategy) {
        if (instance == null) {
            synchronized (ParkingLot.class) {
                if (instance == null) {           // double-checked locking
                    instance = new ParkingLot(feeStrategy);
                }
            }
        }
        return instance;
    }

    public void addFloor(ParkingFloor floor) {
        floors.add(floor);
    }

    public Ticket park(Vehicle v) {
        for (ParkingFloor floor : floors) {
            ParkingSpot spot = floor.findAndAssign(v);
            if (spot != null) {
                return new Ticket(v, spot, floor, Instant.now());
            }
        }
        throw new RuntimeException("Parking lot full for type: " + v.getType());
    }

    public double exit(Ticket ticket) {
        ticket.getFloor().releaseSpot(ticket.getSpot());
        return feeStrategy.calculate(ticket);   // ← delegates to injected strategy
    }
}
```

```
T1 checks: instance == null → true → enters synchronized block
T1 checks: instance == null → true → creates instance → exits synchronized block
T2 checks: instance == null → false → returns existing instance (guaranteed by volatile)
```

**Observable outcome:** This is intentional: locking the entire lot for every park operation would serialize all gates.

## Stage 4 — Ticket and Fee Strategy Pattern

- Using a Strategy pattern here (even as simple as a rate map) makes it easy to swap pricing logic (dynamic pricing, peak hours) without touching ParkingLot or Ticket .

*Applies **design-patterns-gof** to the decision above.*

```java
public class Ticket {
    private final Vehicle vehicle;
    private final ParkingSpot spot;
    private final ParkingFloor floor;
    private final Instant entryTime;

    public Ticket(Vehicle vehicle, ParkingSpot spot, ParkingFloor floor, Instant entryTime) {
        this.vehicle = vehicle;
        this.spot = spot;
        this.floor = floor;
        this.entryTime = entryTime;
    }

    // Getters...
}
```

```java
public class FeeCalculator {
    private static final Map<VehicleType, Double> RATE_PER_HOUR = Map.of(
        VehicleType.BIKE,  1.0,
        VehicleType.CAR,   2.0,
        VehicleType.TRUCK, 3.5
    );

    public static double calculate(VehicleType type, long minutes) {
        double hours = Math.ceil(minutes / 60.0);   // round up to next hour
        return RATE_PER_HOUR.getOrDefault(type, 2.0) * hours;
    }
}
```

**Observable outcome:** Using a Strategy pattern here (even as simple as a rate map) makes it easy to swap pricing logic (dynamic pricing, peak hours) without touching ParkingLot or Ticket .

## Stage 5 — OOP Pillars in the Implementation

- Every OOP pillar is load-bearing here — not decorative.
- The table below maps each pillar to the exact class or interface where it does work, followed by the code rationale.
- Encapsulation: ParkingFloor Owns Its Heap The Map<VehicleType, PriorityQueue<ParkingSpot inside ParkingFloor is private.
- External callers cannot poll the heap, reorder it, or add a spot to the wrong vehicle-type bucket.

*Applies **tree-data-structures** to the decision above.*

```java
floor.findAndAssign(vehicle);   // caller never touches the heap directly
floor.releaseSpot(spot);        // re-insertion is the floor's responsibility
```

```java
// Hourly pricing — injected at startup
FeeStrategy hourly = ticket -> {
    long hours = Math.max(1,
        Duration.between(ticket.getEntryTime(), Instant.now()).toHours());
    return hours * BASE_RATES.get(ticket.getVehicle().getType());
};

ParkingLot lot = ParkingLot.getInstance(hourly);
```

**Observable outcome:** External callers cannot poll the heap, reorder it, or add a spot to the wrong vehicle-type bucket.

## Stage 6 — SOLID Principles Applied in Code

- SRP — The floor knows spots; the lot knows fees.
- If ParkingFloor.findAndAssign() also invoked feeStrategy.calculate() , then changing pricing rules would require opening ParkingFloor .
- Two reasons to change = SRP violation.
- The floor's single responsibility: maintain an ordered set of available spots per vehicle type.

*Applies **low-level-design-systems** to the decision above.*

```java
public class EvSpot extends ParkingSpot {
    private final boolean hasCharger;

    public EvSpot(int id, boolean hasCharger) {
        super(id, VehicleType.CAR);           // reuses a CAR-type heap slot
        this.hasCharger = hasCharger;
    }

    @Override
    public boolean canFit(VehicleType type) { return type == VehicleType.CAR; }
    public boolean hasCharger() { return hasCharger; }
}
```

```java
@FunctionalInterface
public interface FeeStrategy {
    double calculate(Ticket ticket);   // one method, no baggage
}
```

**Observable outcome:** The floor's single responsibility: maintain an ordered set of available spots per vehicle type.

## End-to-end outcome

Vehicle Hierarchy Parking Spot Hierarchy 📊 ParkingSpot Lifecycle States The state diagram shows the complete two-state lifecycle every ParkingSpot instance goes through: it enters FREE when addSpot() places it into the floor's Min-Heap, transitions to OCCUPIED when assign(vehicle) succeeds inside a synchronized block, and returns to FREE when free() is called on exit — at which point the spot is immediately re-inserted into the heap for the next arrival.

## Alternatives considered

### Decision Guide: When to Use Which Pattern

Not every problem needs every pattern.


## Failure and degraded modes

### Trade-offs & Failure Modes: Design Patterns Applied

- **Detection:** Trade-offs & Failure Modes: Design Patterns Applied
- **User or operator impact:** Trade-offs & Failure Modes: Design Patterns Applied



## Scenario context

A **cache** is a small, fast store that holds a hot subset of a larger, slower dataset. When your application repeatedly reads the same data from a database, remote API, or disk, caching the results in memory slashes latency from milliseconds to microseconds.

Because caches have limited capacity, they need an **eviction policy** — a rule for deciding which item to drop when the cache is full and a new item arrives.…

This walkthrough focuses on **Eviction Policies: Why LRU Makes Sense**.

Before making a design choice, clarify:

- A cache is a small, fast store that holds a hot subset of a larger, slower dataset.
- When your application repeatedly reads the same data from a database, remote API, or disk, caching the results in memory slashes latency from milliseconds to microseconds.
- Because caches have limited capacity, they need an eviction policy — a rule for deciding which item to drop when the cache is full and a new item arrives.

**Concepts in play:** caching, low-level-design-systems, hash-tables-and-bloom-filters, database-indexing

## Stage 1 — The Browser History Analogy

- Your browser "Back" button stores the pages you visited most recently.
- If you visit 100 pages and your browser only keeps 10 in memory, it drops the oldest one.
- LRU says: the item you haven't needed in the longest time is the least valuable — evict it first.
- The classic challenge is implementing this in O(1) for both get and put .

*Applies **caching** to the decision above.*

**Observable outcome:** The classic challenge is implementing this in O(1) for both get and put .

## Stage 2 — The HashMap + Doubly Linked List Architecture

- architecture { "version": 1, "title": "The HashMap + Doubly Linked List Architecture - Subsystem Overview", "description": "Decoupled system architecture isolating ingress, stateless logic, and persistent datastores.",…
- Together, both get() and put() complete in O(1) — something neither data structure can achieve alone.
- The arrow represents the dependency: every cache operation starts at the HashMap to retrieve the node reference, then hands off to the DLL for order-preserving position updates.
- - HashMap: Maps each key to its Node in the list— O(1) access.

*Applies **low-level-design-systems** to the decision above.*

```mermaid

```

```

flowchart LR
    HashMap["HashMap (key  node pointer)"] --> DLL["Doubly Linked List Head (MRU)  ...  Tail (LRU)"]
```

**Observable outcome:** - HashMap: Maps each key to its Node in the list— O(1) access.

## Stage 3 — Step-by-Step Trace: Capacity = 3

- Key: get(1) bumped 1 to head, so 3 became the new tail.
- When 4 arrives, 2 gets evicted — not 3.
- 📊 Cache Entry Lifecycle States The state machine captures the complete lifecycle of a single cache entry from insertion to eviction.
- A node enters as HOT (placed at the head/MRU position) and returns to HOT whenever get() is called on it, resetting its eviction clock with each access.

*Applies **hash-tables-and-bloom-filters** to the decision above.*

```mermaid
stateDiagram-v2
    [*] --> HOT : put(key, val)  inserted at head (MRU)
    HOT --> HOT : get(key)  moved back to head
    HOT --> COLD : newer entries push it toward tail
    COLD --> HOT : get(key)  moved back to head (MRU)
    COLD --> EVICTED : cache full  tail node removed on next put()
    EVICTED --> [*]
```

**Observable outcome:** A node enters as HOT (placed at the head/MRU position) and returns to HOT whenever get() is called on it, resetting its eviction clock with each access.

## Stage 4 — LRU Cache Operation Flow

- Every get and put follows a deterministic decision path.
- Tracking which branch executes is the key to understanding unexpected evictions.
- This decision tree captures every execution path through get() and put() in a single view.
- The left branch ( get ) is two steps: a HashMap lookup, then either a miss (return -1) or a move-to-head followed by returning the value.

*Applies **database-indexing** to the decision above.*

```mermaid
flowchart TD
    A[Request arrives] --> B{get or put?}
    B -->|"get(key)"| C{Key in HashMap?}
    C -->|No| D["Return -1 (cache miss)"]
    C -->|Yes| E["Move node to head (mark as MRU)"]
    E --> F["Return value (cache hit)"]
    B -->|"put(key, val)"| G{Key exists?}
    G -->|Yes| H[Update value Move node to head]
    G -->|No| I[Create new node Insert at head]
    I --> J{Size > capacity?}
    J -->|Yes| K[Remove tail node Delete from HashMap]
    J -->|No| L[Done ]
    K --> L
```

**Observable outcome:** The left branch ( get ) is two steps: a HashMap lookup, then either a miss (return -1) or a move-to-head followed by returning the value.

## Stage 5 — How the Four OOP Pillars Shape the LRU Cache Design

- Object-oriented design is not just syntax — it is a discipline for assigning clear, bounded responsibilities to each class.
- The LRU cache is a compact example of all four OOP pillars working together in a single design.
- Encapsulation: The Node<K,V inner class — with its prev and next pointers — is declared private static .
- A dedicated DoublyLinkedList helper manages all pointer manipulation.

*Applies **caching** to the decision above.*

```mermaid
classDiagram
    direction LR
    class Cache~K,V~ {
        <<interface>>
        +get(key K) Optional~V~
        +put(key K, value V) void
        +size() int
        +capacity() int
    }
    class LruCache~K,V~ {
        -capacity int
        -map HashMap
        -head Node
        -tail Node
        +get(key K) Optional~V~
        +put(key K, value V) void
    }
    class LfuCache~K,V~ {
        -capacity int
        -freqMap HashMap
        +get(key K) Optional~V~
        +put(key K, value V) void
    }
    class Node~K,V~ {
        -key K
        -value V
        -prev Node
        -next Node
    }
    Cache <|.. LruCache : implements
    Cache <|.. LfuCache : implements
    LruCache *-- Node : has-a (private)
```

**Observable outcome:** A dedicated DoublyLinkedList helper manages all pointer manipulation.

## Stage 6 — SOLID Principles in the LRU Cache Design

- Getting the algorithm right is only half the job in LLD.
- The other half is designing classes that are easy to extend, test, and replace independently.
- Every SOLID principle has a concrete mapping in the LRU cache design.
- SRP in practice: When a pointer-corruption bug surfaces, you look inside DoublyLinkedList .

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** SRP in practice: When a pointer-corruption bug surfaces, you look inside DoublyLinkedList .

## End-to-end outcome

A cache is a small, fast store that holds a hot subset of a larger, slower dataset.

## Alternatives considered

### Decision Guide: Choosing the Right Cache Implementation

Start with synchronized methods for correctness.


## Failure and degraded modes

### Trade-offs & Failure Modes: Thread Safety and Cache Invalidation

- **Detection:** The basic implementation above is not thread-safe.
- **User or operator impact:** The basic implementation above is not thread-safe.



Practice compact, extensible systems that fit a coding interview.

Machine Coding Classics

## Scenario context

A hotel has 10 floors and 3 elevators. At any moment:
- External requests come in: "Someone on Floor 5 pressed UP."
- Internal requests come in: "Someone inside Lift 1 pressed Floor 10."
- The system must decide which car to dispatch, and which order to serve floors.

This is a classic **State Machine + Scheduling** design. The key insight is that a lift behaves differently based on its current state — and we should…

This walkthrough focuses on **The Hotel Lift Problem: What We Are Designing**.

Before making a design choice, clarify:

- A hotel has 10 floors and 3 elevators.
- At any moment: - External requests come in: "Someone on Floor 5 pressed UP." - Internal requests come in: "Someone inside Lift 1 pressed Floor 10." - The system must decide which car to dispatch, and which order to serv…
- This is a classic State Machine + Scheduling design.

**Concepts in play:** low-level-design-systems, jvm-internals-and-garbage-collection, design-patterns-gof, design-principles-solid

## Stage 1 — Elevator System Basics: Entities, States, and Button Types

- Before writing a single line of code it helps to name every moving part in plain English.
- Core entities: States an ElevatorCar can be in: - IDLE — the car is stopped and has no pending stops.
- - MOVING UP — the car is travelling upward and serving stops along the way.
- - MOVING DOWN — the car is travelling downward and serving stops along the way.

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** - MOVING DOWN — the car is travelling downward and serving stops along the way.

## Stage 2 — Domain Model: The Core Entities

- - ElevatorCar: Holds a sorted set of destination floors.
- Has a state (IDLE, MOVING UP, MOVING DOWN).
- Assigns incoming Request to the best car.
- - Request: Either ExternalRequest (floor + direction pressed outside) or InternalRequest (destination floor pressed inside the car).

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
classDiagram
    class Building {
        +List~Floor~ floors
        +List~ElevatorCar~ cars
        +Dispatcher dispatcher
        +handleExternalRequest(Request r)
    }
    class ElevatorCar {
        +int id
        +int currentFloor
        +Direction direction
        +ElevatorState state
        -TreeSet~Integer~ stops
        +addStop(int floor)
        +move()
        +getCurrentFloor() int
    }
    class Dispatcher {
        -DispatchStrategy strategy
        +assign(Request r) ElevatorCar
    }
    class Request {
        +int sourceFloor
        +Direction direction
    }
    class ElevatorState {
        <<interface>>
        +handleExternalRequest(ElevatorCar car, Request r)
        +handleInternalRequest(ElevatorCar car, int floor)
        +isIdle() bool
    }
    class DispatchStrategy {
        <<interface>>
        +assign(Request request, List~ElevatorCar~ available) ElevatorCar
    }
    class IdleState {
        +handleExternalRequest(ElevatorCar, Request)
        +handleInternalRequest(ElevatorCar, int)
        +isIdle() bool
    }
    class MovingUpState {
        +handleExternalRequest(ElevatorCar, Request)
        +handleInternalRequest(ElevatorCar, int)
        +isIdle() bool
    }
    class MovingDownState {
        +handleExternalRequest(ElevatorCar, Request)
        +handleInternalRequest(ElevatorCar, int)
        +isIdle() bool
    }
    class NearestCarStrategy {
        +assign(Request, List~ElevatorCar~) ElevatorCar
    }

    Building "1" *-- "many" ElevatorCar : contains
    Building --> Dispatcher : uses
    Dispatcher o-- DispatchStrategy : uses (injected)
    ElevatorCar o-- ElevatorState : state (State Pattern)
    ElevatorState <|.. IdleState : implements
    ElevatorState <|.. MovingUpState : implements
    ElevatorState <|.. MovingDownState : implements
    DispatchStrategy <|.. NearestCarStrategy : implements
    Dispatcher --> ElevatorCar : assigns
```

**Observable outcome:** - Request: Either ExternalRequest (floor + direction pressed outside) or InternalRequest (destination floor pressed inside the car).

## Stage 3 — Deep Dive: State Pattern for Elevator Movement

- An elevator's behavior depends on its current state.
- We make this explicit with the State pattern: The state transitions:

*Applies **design-patterns-gof** to the decision above.*

```java
public interface ElevatorState {
    void handleRequest(ElevatorCar car, int targetFloor);
    String name();
}

public class IdleState implements ElevatorState {
    public void handleRequest(ElevatorCar car, int targetFloor) {
        car.addStop(targetFloor);
        if (targetFloor > car.getCurrentFloor()) {
            car.setState(new MovingUpState());
        } else if (targetFloor < car.getCurrentFloor()) {
            car.setState(new MovingDownState());
        }
    }
    public String name() { return "IDLE"; }
}

public class MovingUpState implements ElevatorState {
    public void handleRequest(ElevatorCar car, int targetFloor) {
        // SCAN: only add if it's above current floor
        if (targetFloor >= car.getCurrentFloor()) {
            car.addStop(targetFloor);   // serve on the way
        } else {
            car.deferRequest(targetFloor);  // serve on the next sweep
        }
    }
    public String name() { return "MOVING_UP"; }
}
```

```mermaid
stateDiagram-v2
    [*] --> IDLE
    IDLE --> MOVING_UP : request above current floor
    IDLE --> MOVING_DOWN : request below current floor
    MOVING_UP --> IDLE : no more up requests
    MOVING_UP --> MOVING_DOWN : switch at top
    MOVING_DOWN --> IDLE : no more down requests
    MOVING_DOWN --> MOVING_UP : switch at bottom
```

**Observable outcome:** We make this explicit with the State pattern: The state transitions:

## Stage 4 — Dispatcher: Strategy Pattern for Assignment Policy

- The Dispatcher uses the Strategy pattern so we can swap assignment algorithms: canService() checks the car's state: - IDLE → always serviceable.
- - MOVING UP → serviceable if request is above current floor and direction matches.
- - MOVING DOWN → serviceable if request is below current floor and direction matches.

*Applies **design-principles-solid** to the decision above.*

```java
public interface DispatchStrategy {
    ElevatorCar select(List<ElevatorCar> cars, Request request);
}

// Nearest-Car strategy: pick the car that will reach the requester soonest
public class NearestCarStrategy implements DispatchStrategy {
    public ElevatorCar select(List<ElevatorCar> cars, Request request) {
        return cars.stream()
            .filter(c -> c.canService(request))
            .min(Comparator.comparingInt(c ->
                Math.abs(c.getCurrentFloor() - request.getSourceFloor())))
            .orElse(null);
    }
}
```

**Observable outcome:** - MOVING DOWN → serviceable if request is below current floor and direction matches.

## Stage 5 — Interface Contracts: DispatchStrategy and ElevatorState

- Two interfaces form the entire behavioral backbone of this design.
- Every concrete class — state implementations, dispatch algorithms, the Dispatcher itself — is wired together through these two contracts.
- Why separate handleExternalRequest from handleInternalRequest ?
- External requests originate from a floor panel and route through the Dispatcher — the strategy can load-balance across cars.

*Applies **low-level-design-systems** to the decision above.*

```java
// Who implements: NearestCarStrategy, ZoneStrategy, LookStrategy
// Who consumes:   Dispatcher
interface DispatchStrategy {
    ElevatorCar assign(Request request, List<ElevatorCar> available);
}

// Who implements: IdleState, MovingUpState, MovingDownState
// Who consumes:   ElevatorCar.handleExternalRequest(), ElevatorCar.handleInternalRequest()
interface ElevatorState {
    void handleExternalRequest(ElevatorCar car, Request request);
    void handleInternalRequest(ElevatorCar car, int targetFloor);
    boolean isIdle();
}
```

```mermaid
sequenceDiagram
    participant U as User (Floor 3)
    participant D as Dispatcher
    participant S as DispatchStrategy
    participant C as ElevatorCar
    participant ST as ElevatorState
    U->>D: handleExternalRequest(floor=3, UP)
    D->>S: assign(request, availableCars)
    S->>S: score each car by distance
    S-->>D: bestCar (Car #2)
    D->>C: handleExternalRequest(car, request)
    C->>ST: delegate to current state
    ST->>C: addStop(floor=3)
    ST->>C: setState(MovingUpState)
    C-->>D: stop added
    Note over C: Car moves toward Floor 3 via SCAN
```

**Observable outcome:** External requests originate from a floor panel and route through the Dispatcher — the strategy can load-balance across cars.

## Stage 6 — OOP Pillars in the Elevator Design

- Each of the four OOP pillars maps cleanly to a specific boundary in this design.
- The table below names the pillar, the class or interface that embodies it, and the concrete mechanism.
- Encapsulation deep-dive: The TreeSet<Integer inside ElevatorCar is the most critical encapsulation boundary in the design.
- If external code could add floors to the set arbitrarily, it could insert a below-current-floor stop while the car is sweeping up — silently breaking the SCAN invariant.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
classDiagram
    class Building {
        +List~Floor~ floors
        +List~ElevatorCar~ cars
        +Dispatcher dispatcher
        +handleExternalRequest(Request) void
    }
    class ElevatorCar {
        +int id
        +int currentFloor
        -ElevatorState state
        -TreeSet~Integer~ stopQueue
        +addStop(int) void
        +deferRequest(int) void
        +move() void
        +setState(ElevatorState) void
        +getCurrentFloor() int
    }
    class Dispatcher {
        -DispatchStrategy strategy
        +assign(Request, List~ElevatorCar~) ElevatorCar
    }
    class ElevatorState {
        <<interface>>
        +handleExternalRequest(ElevatorCar, Request) void
        +handleInternalRequest(ElevatorCar, int) void
        +isIdle() boolean
    }
    class DispatchStrategy {
        <<interface>>
        +assign(Request, List~ElevatorCar~) ElevatorCar
    }
    class IdleState {
        +handleExternalRequest(ElevatorCar, Request) void
        +handleInternalRequest(ElevatorCar, int) void
        +isIdle() boolean
    }
    class MovingUpState {
        +handleExternalRequest(ElevatorCar, Request) void
        +handleInternalRequest(ElevatorCar, int) void
        +isIdle() boolean
    }
    class MovingDownState {
        +handleExternalRequest(ElevatorCar, Request) void
        +handleInternalRequest(ElevatorCar, int) void
        +isIdle() boolean
    }
    class NearestCarStrategy {
        +assign(Request, List~ElevatorCar~) ElevatorCar
    }
    class DestinationDispatchStrategy {
        +assign(Request, List~ElevatorCar~) ElevatorCar
    }
    class Request {
        +int sourceFloor
        +Direction direction
    }
    class Direction {
        <<enumeration>>
        UP
        DOWN
    }
    Building "1" *-- "many" ElevatorCar : contains
    Building --> Dispatcher : uses
    Dispatcher o-- DispatchStrategy : uses (injected)
    ElevatorCar o-- ElevatorState : current state
    ElevatorState <|.. IdleState : implements
    ElevatorState <|.. MovingUpState : implements
    ElevatorState <|.. MovingDownState : implements
    DispatchStrategy <|.. NearestCarStrategy : implements
    DispatchStrategy <|.. DestinationDispatchStrategy : implements
    Dispatcher --> ElevatorCar : assigns
    Request --> Direction : uses
```

**Observable outcome:** If external code could add floors to the set arbitrarily, it could insert a below-current-floor stop while the car is sweeping up — silently breaking the SCAN invariant.

## End-to-end outcome

A hotel has 10 floors and 3 elevators.

## Alternatives considered

### Decision Guide: Choosing the Right Elevator Scheduling Strategy

Start with the SCAN algorithm and Nearest-Car dispatch.


## Failure and degraded modes

### Trade-offs & Failure Modes in Elevator Design

- **Detection:** Trade-offs & Failure Modes in Elevator Design
- **User or operator impact:** Trade-offs & Failure Modes in Elevator Design



## Scenario context

You run a cinema. A Friday night show has 200 seats. Two scenarios break a naive implementation:

1. **Double-booking:** User A and User B click "Book Seat A1" at the same millisecond. Only one should succeed.
2. **Abandoned locks:** User A locks Seat A1 but never completes payment. The seat should become available again after 10 minutes.

This needs a **3-state model + distributed lock** strategy.

---

This walkthrough focuses on **The Cinema Inventory Problem: What Makes It Hard**.

Before making a design choice, clarify:

- A Friday night show has 200 seats.
- Two scenarios break a naive implementation: 1.
- Double-booking: User A and User B click "Book Seat A1" at the same millisecond.

**Concepts in play:** low-level-design-systems, caching, api-gateway, distributed-locking

## Stage 1 — Key Entities in a Movie Booking System

- Before writing a single line of concurrency code, you need a clear domain model.
- A movie booking platform has six core entities: SeatType classifies seats by price tier: - PLATINUM — premium recliner seats (front/center) - GOLD — standard premium tier - SILVER — economy tier SeatStatus is the concur…
- Every Booking references a Show, not the Movie directly — this is why "the 7 PM showing of a film" is completely separate inventory from "the 9 PM showing" of the same film.
- This hierarchy shapes every query, index, and cache partition in the real system.

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** This hierarchy shapes every query, index, and cache partition in the real system.

## Stage 2 — The Domain Hierarchy: City → Cinema → Screen → Show → Seat

- The composition arrows ( -- ) running down the left spine — City → Cinema → Screen → Seat — model physical containment: a Screen cannot exist without its owning Cinema , and Seat instances are part of the Screen .
- Show sits at the centre as the critical join entity, linking a Movie and a Screen at a specific startTime ; every Booking references a Show , not a Movie directly, which is why two screenings of the same film are comple…
- The aggregation arrows ( o-- ) from BookingService to PricingStrategy and PaymentGateway express collaboration, not ownership — both dependencies are injected interfaces, making the service fully decoupled from any conc…
- - SeatType: GOLD , SILVER , PLATINUM — affects pricing.

*Applies **caching** to the decision above.*

```mermaid
classDiagram
    class City {+String name; +List~Cinema~ cinemas}
    class Cinema {+String name; +List~Screen~ screens}
    class Screen {+int id; +List~Seat~ seats}
    class Movie {+String title; +int durationMinutes}
    class Show {
        +Movie movie
        +Screen screen
        +LocalDateTime startTime
        +synchronized boolean bookSeats(List seats)
    }
    class Seat {
        -SeatStatus status
        +String row
        +int col
        +SeatType type
        +reserve(bookingId)
        +release()
        +confirm()
    }
    class PremiumSeat {
        +boolean hasRecline
        +boolean hasFootrest
    }
    class GroupSeat {
        +String groupReservationId
    }
    class Booking {
        +int id
        +Show show
        +List~Seat~ seats
        +PaymentStatus payment
    }
    class BookingService {
        +reserveSeats(User, Show, List~Seat~)
        +confirmBooking(Booking)
    }
    class PricingStrategy {
        <<interface>>
        +calculatePrice(Seat, Show, Customer) Money
    }
    class PaymentGateway {
        <<interface>>
        +charge(Customer, Money, String) PaymentResult
    }

    City *-- Cinema
    Cinema *-- Screen
    Screen *-- Seat
    Show "1" *-- "many" Seat : contains
    Show --> Screen
    Booking --> Show
    Booking --> Seat
    PremiumSeat --|> Seat : extends
    GroupSeat --|> Seat : extends
    BookingService o-- PricingStrategy : uses (injected)
    BookingService o-- PaymentGateway : uses (injected)
```

**Observable outcome:** - SeatType: GOLD , SILVER , PLATINUM — affects pricing.

## Stage 3 — The 3-State Seat Model: Preventing Double Booking

- The key insight: don't go directly from AVAILABLE to BOOKED.
- Insert a temporary LOCKED state.
- State machine: The booking flow: User B gets a graceful "This seat is currently being held by another user" message — not a race condition with undefined behavior.

*Applies **api-gateway** to the decision above.*

```mermaid
stateDiagram-v2
    [*] --> AVAILABLE
    AVAILABLE --> LOCKED : User selects seat (10 min TTL)
    LOCKED --> BOOKED : Payment success
    LOCKED --> AVAILABLE : Payment timeout / failure
    BOOKED --> [*] : Show complete
```

**Observable outcome:** State machine: The booking flow: User B gets a graceful "This seat is currently being held by another user" message — not a race condition with undefined behavior.

## Stage 4 — Booking Flow: From Seat Selection to Confirmation

- Here is how a booking request moves through the system end-to-end — including both failure paths that keep inventory clean: The flowchart maps the complete booking transaction as a directed decision graph with two disti…
- The first diamond — "All seats AVAILABLE?" — is the cheap early-exit: if any seat is already LOCKED or BOOKED by a concurrent user, the request is rejected before a lock is ever acquired on the current user's behalf, re…
- Only after seats are successfully locked does control reach the payment gateway, whose failure branch explicitly releases the hold and returns inventory to AVAILABLE — this explicit release is what separates a well-desi…
- Two distinct failure paths keep inventory accurate: 1.

*Applies **distributed-locking** to the decision above.*

```mermaid
flowchart TD
    A([User Selects Seats]) --> B{All seats AVAILABLE?}
    B -- No --> C([Error: Seat Already Held by Another User])
    B -- Yes --> D[Lock Seats  10 min TTL applied]
    D --> E([User Redirected to Payment Page])
    E --> F{Payment Successful?}
    F -- Timeout or Failure --> G[Release Lock  Seats set back to AVAILABLE]
    F -- Yes --> H[Set Seats to BOOKED]
    H --> I([Confirmation Email Sent to User])
    G --> J([Error: Payment Failed  Seats Released])
```

**Observable outcome:** Two distinct failure paths keep inventory accurate: 1.

## Stage 5 — Deep Dive: Synchronized Booking Implementation

- synchronized on the Show method ensures that the check-and-lock is atomic — no two threads can interleave between the check ( AVAILABLE ) and the lock ( LOCKED ).
- 📊 Reserve Seats: Booking Sequence The sequence diagram traces the critical path for seat reservation — from the initial lock request (preventing other threads from booking the same seat) through payment confirmation to…
- The synchronized annotation on the BS- SH call marks the boundary of the atomic monitor: every arrow that follows — the status check ( SH- S: status == AVAILABLE?
- ) and the lock ( SH- S: reserve(bookingId) ) — executes inside a single thread-held critical section, making interleaving between the check and the commit impossible.

*Applies **low-level-design-systems** to the decision above.*

```java
public class Show {
    private final int id;
    private final List<Seat> seats;

    public synchronized BookingResult reserveSeats(User user, List<Integer> seatIds) {
        // Phase 1: Check all requested seats are available
        List<Seat> selected = new ArrayList<>();
        for (int id : seatIds) {
            Seat s = findSeat(id);
            if (s.getStatus() != SeatStatus.AVAILABLE) {
                return BookingResult.failure("Seat " + id + " is not available");
            }
            selected.add(s);
        }
        // Phase 2: Lock all seats together (atomic within synchronized block)
        Instant lockExpiry = Instant.now().plusSeconds(600);
        for (Seat s : selected) {
            s.setStatus(SeatStatus.LOCKED);
            s.setLockExpiry(lockExpiry);
        }
        return BookingResult.success(new Booking(user, this, selected));
    }
}
```

```mermaid
sequenceDiagram
    participant U as User
    participant BS as BookingService
    participant SH as Show
    participant S as Seat
    participant PG as PaymentGateway
    U->>BS: reserveSeats(user, show, seatIds)
    BS->>SH: reserveSeats(user, seatIds) synchronized
    SH->>S: status == AVAILABLE?
    S-->>SH: true
    SH->>S: reserve(bookingId)  LOCKED
    SH-->>BS: BookingResult.success(booking)
    BS->>PG: charge(user, amount, bookingId)
    PG-->>BS: PaymentResult.success
    BS->>S: confirm()  BOOKED
    BS-->>U: Booking{id, seats, CONFIRMED}
```

**Observable outcome:** ) and the lock ( SH- S: reserve(bookingId) ) — executes inside a single thread-held critical section, making interleaving between the check and the commit impossible.

## Stage 6 — Pricing Strategy Pattern

- Different shows and seat types need different prices: 📊 Enhanced Booking Domain Class Diagram This enhanced diagram isolates the Seat subsystem with its full type hierarchy and wires in the three Strategy/Gateway inter…
- The enumeration classes SeatType and SeatStatus appear as owned associations of Seat (solid arrows from Seat ), making explicit that price tier and booking state are intrinsic to the seat itself — not to the Booking or…
- The dashed implementation arrows ( ..
- ) from HourlyPricing and DynamicPricing to PricingStrategy are the Strategy pattern in UML form: both are interchangeable at the BookingService injection site, so the active pricing rule switches at Spring configuration…

*Applies **caching** to the decision above.*

```java
public interface PricingStrategy {
    Money calculatePrice(Seat seat, Show show, Customer customer);
}

public class HourlyPricing implements PricingStrategy {
    public Money calculatePrice(Seat seat, Show show, Customer customer) {
        double base = seat.getType() == SeatType.GOLD ? 15.0 : 10.0;
        double multiplier = show.isWeekend() ? 1.2 : 1.0;  // weekend surcharge
        return Money.of(base * multiplier);
    }
}

public class DynamicPricing implements PricingStrategy {
    public Money calculatePrice(Seat seat, Show show, Customer customer) {
        double occupancy = show.getBookedPercent();
        return Money.of(BASE_PRICE * (1 + occupancy));  // price rises with demand
    }
}
```

```mermaid
classDiagram
    class Seat {
        -SeatStatus status
        +String row
        +int col
        +SeatType type
        +reserve(String bookingId) void
        +release() void
        +confirm() void
    }
    class PremiumSeat {
        +boolean hasRecline
        +boolean hasFootrest
    }
    class GroupSeat {
        +String groupReservationId
    }
    class SeatType {
        <<enumeration>>
        PLATINUM
        GOLD
        SILVER
    }
    class SeatStatus {
        <<enumeration>>
        AVAILABLE
        LOCKED
        BOOKED
    }
    class PricingStrategy {
        <<interface>>
        +calculatePrice(Seat, Show, Customer) Money
    }
    class HourlyPricing {
        +calculatePrice(Seat, Show, Customer) Money
    }
    class DynamicPricing {
        +calculatePrice(Seat, Show, Customer) Money
    }
    class SeatSelector {
        <<interface>>
        +findAvailable(Show, SeatType, int) List~Seat~
    }
    class PaymentGateway {
        <<interface>>
        +charge(Customer, Money, String) PaymentResult
    }
    class BookingService {
        -PricingStrategy pricer
        -SeatSelector selector
        -PaymentGateway gateway
        +reserveSeats(User, Show, List~Seat~) Booking
        +confirmBooking(Booking) void
    }
    PremiumSeat --|> Seat : extends
    GroupSeat --|> Seat : extends
    Seat --> SeatStatus : state
    Seat --> SeatType : type
    HourlyPricing ..|> PricingStrategy : implements
    DynamicPricing ..|> PricingStrategy : implements
    BookingService o-- PricingStrategy : uses (injected)
    BookingService o-- SeatSelector : uses (injected)
    BookingService o-- PaymentGateway : uses (injected)
```

**Observable outcome:** ) from HourlyPricing and DynamicPricing to PricingStrategy are the Strategy pattern in UML form: both are interchangeable at the BookingService injection site, so the active pricing rule switches at Spring configuration…

## End-to-end outcome

A Friday night show has 200 seats.

## Alternatives considered

### OOP Decision Guide: Patterns and Extension Points

Start with synchronized on Seat methods and constructor-injected strategies.


## Failure and degraded modes

### OOP Design Trade-offs and Failure Modes in the Booking System

- **Detection:** Failure mode — skipping the LOCKED state: If code transitions directly from AVAILABLE to BOOKED in a single step, any failure mid-payment (timeout, gateway error, network drop) leaves the seat perman…
- **User or operator impact:** Failure mode — skipping the LOCKED state: If code transitions directly from AVAILABLE to BOOKED in a single step, any failure mid-payment (timeout, gateway error, network drop) leaves the seat perman…



## Scenario context

A ride-booking system (Uber/Lyft-style) needs three interleaved sub-systems: real-time driver location tracking (Observer Pattern), nearest-driver matching (geospatial query), and dynamic pricing (Strategy Pattern). Getting state transitions right — Requested → Accepted → InProgress → Completed — is the core LLD challenge.


```architecture
{
  "version": 1,
  "title": "Ride Sharing Platform - Spatial Indexing & Geo…

This walkthrough focuses on **The Matchmaking Problem Behind Every Ride Request**.

Before making a design choice, clarify:

- When a rider taps "Book Ride," a deceptively complex chain of decisions fires within seconds: 1.
- Which drivers are available near the pickup point?
- How does the trip state transition as the ride progresses?

**Concepts in play:** design-patterns-gof, low-level-design-systems, caching, jvm-internals-and-garbage-collection

## Stage 1 — Core Entities and Their Relationships

- Rider → requests a trip, has a current location.
- Driver → has availability status, current location, vehicle info.
- Trip → ties a rider to a driver, from pickup to drop-off.
- TripStatus enum: DriverStatus enum: 📊 Driver Availability State Machine

*Applies **design-patterns-gof** to the decision above.*

```mermaid
classDiagram
    class Rider {
        +String id
        +String name
        +Location location
        +requestRide(Location destination)
    }
    class Driver {
        +String id
        +String name
        +DriverStatus status
        +Location location
        +updateLocation(Location loc)
    }
    class Trip {
        +String tripId
        +Rider rider
        +Driver driver
        +TripStatus status
        +Location pickup
        +Location destination
        +transition(TripEvent event)
    }
    Rider --> Trip : initiates
    Driver --> Trip : fulfills
```

```java
enum TripStatus {
    REQUESTED, ACCEPTED, IN_PROGRESS, COMPLETED, CANCELLED
}
```

**Observable outcome:** TripStatus enum: DriverStatus enum: 📊 Driver Availability State Machine

## Stage 2 — State Transitions: The Trip Lifecycle

- Every transition is triggered by an explicit event.
- Wrong transitions must be rejected.

*Applies **low-level-design-systems** to the decision above.*

```mermaid
stateDiagram-v2
    [*] --> REQUESTED : rider taps Book
    REQUESTED --> ACCEPTED : driver accepts
    REQUESTED --> CANCELLED : no driver found / rider cancels
    ACCEPTED --> IN_PROGRESS : driver arrives at pickup
    IN_PROGRESS --> COMPLETED : destination reached
    IN_PROGRESS --> CANCELLED : rider or driver cancels mid-trip
    COMPLETED --> [*]
    CANCELLED --> [*]
```

```java
// Transition enforcement
public void transition(TripStatus newStatus) {
    if (!isValidTransition(this.status, newStatus)) {
        throw new IllegalStateException(
            "Cannot transition from " + this.status + " to " + newStatus);
    }
    this.status = newStatus;
}

private boolean isValidTransition(TripStatus from, TripStatus to) {
    return switch (from) {
        case REQUESTED   -> to == ACCEPTED   || to == CANCELLED;
        case ACCEPTED    -> to == IN_PROGRESS || to == CANCELLED;
        case IN_PROGRESS -> to == COMPLETED  || to == CANCELLED;
        default          -> false;
    };
}
```

**Observable outcome:** Wrong transitions must be rejected.

## Stage 3 — Real-World Applications: Observer Pattern: Real-Time Driver Location Updates

- Riders, dispatchers, and ETAs all need to react when a driver's location changes.
- The Observer Pattern decouples location updates from their consumers.

*Applies **caching** to the decision above.*

```java
// Observer interface
interface LocationObserver {
    void onLocationUpdate(String driverId, Location newLocation);
}

// Subject (driver location tracker)
class DriverLocationService {
    private Map<String, List<LocationObserver>> subscribers = new HashMap<>();

    public void subscribe(String driverId, LocationObserver observer) {
        subscribers.computeIfAbsent(driverId, k -> new ArrayList<>()).add(observer);
    }

    public void updateLocation(String driverId, Location loc) {
        subscribers.getOrDefault(driverId, List.of())
                   .forEach(obs -> obs.onLocationUpdate(driverId, loc));
    }
}

// Concrete observer
class RiderEtaTracker implements LocationObserver {
    @Override
    public void onLocationUpdate(String driverId, Location loc) {
        // Recalculate ETA and push to rider's app
        System.out.println("ETA updated for driver " + driverId + " at " + loc);
    }
}
```

**Observable outcome:** The Observer Pattern decouples location updates from their consumers.

## Stage 4 — Matching Algorithm: Finding the Nearest Available Driver

- The simplest valid matching algorithm: 1.
- Filter drivers by status = AVAILABLE.
- For each candidate, compute distance to rider pickup.
- Return the driver with minimum distance.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
graph TD
    A[Ride Request received  pickup location known] --> B[Query driver index: status = AVAILABLE]
    B --> C[For each candidate: compute Haversine distance to pickup]
    C --> D{Any drivers within radius?}
    D -->|No| E[Expand radius or notify rider of no availability]
    D -->|Yes| F[Sort candidates by distance ascending]
    F --> G[Assign nearest driver  send acceptance request]
    G --> H{Driver accepts?}
    H -->|Yes| I[Trip transitions to ACCEPTED]
    H -->|No| F
```

```java
class MatchingService {
    public Optional<Driver> findNearest(Location pickup, List<Driver> drivers) {
        return drivers.stream()
            .filter(d -> d.getStatus() == DriverStatus.AVAILABLE)
            .min(Comparator.comparingDouble(d -> haversine(pickup, d.getLocation())));
    }

    private double haversine(Location a, Location b) {
        double R = 6371.0;
        double dLat = Math.toRadians(b.lat() - a.lat());
        double dLon = Math.toRadians(b.lon() - a.lon());
        double h = Math.sin(dLat/2)*Math.sin(dLat/2)
                 + Math.cos(Math.toRadians(a.lat()))
                 * Math.cos(Math.toRadians(b.lat()))
                 * Math.sin(dLon/2)*Math.sin(dLon/2);
        return 2 * R * Math.asin(Math.sqrt(h));
    }
}
```

**Observable outcome:** Return the driver with minimum distance.

## Stage 5 — Strategy Pattern: Flexible Pricing Rules

- Pricing logic must change at runtime — flat rate, surge, subscription, etc.
- The Strategy Pattern lets you swap rules without modifying TripPricingEngine .

*Applies **design-patterns-gof** to the decision above.*

```java
interface PricingStrategy {
    double calculateFare(double distanceKm, int durationMinutes, double surgeMultiplier);
}

class StandardPricing implements PricingStrategy {
    public double calculateFare(double distKm, int durMin, double surge) {
        return (0.5 + 1.2 * distKm + 0.25 * durMin) * surge;
    }
}

class FlatRatePricing implements PricingStrategy {
    private double flatRate;
    public FlatRatePricing(double rate) { this.flatRate = rate; }
    public double calculateFare(double d, int t, double s) { return flatRate; }
}

class TripPricingEngine {
    private PricingStrategy strategy;
    public TripPricingEngine(PricingStrategy s) { this.strategy = s; }
    public void setStrategy(PricingStrategy s) { this.strategy = s; }
    public double quote(double km, int min, double surge) {
        return strategy.calculateFare(km, min, surge);
    }
}
```

**Observable outcome:** The Strategy Pattern lets you swap rules without modifying TripPricingEngine .

## Stage 6 — OOP Pillars Applied to the Ride-Booking Domain

- Every core class in this design maps directly to one of the four OOP pillars.
- The mapping is explicit, not accidental — each pillar solves a specific design problem in the ride-booking context.
- Driver.status is private — it is only mutated through named domain operations.
- PremiumDriver and EvDriver inherit the full base contract and extend it.

*Applies **low-level-design-systems** to the decision above.*

```mermaid
classDiagram
    class Driver {
        +String id
        +String name
        -DriverStatus status
        +updateLocation(Location loc)
        +acceptRide(TripRequest req)
        +completeRide(Trip trip)
        +isAvailableFor(TripRequest req) bool
    }
    class PremiumDriver {
        +String vehicleClass
        +bool hasWifi
    }
    class EvDriver {
        +double batteryPercent
        +isAvailableFor(TripRequest req) bool
    }
    class MatchingStrategy {
        <<interface>>
        +match(TripRequest req, List~Driver~ available) Optional~Driver~
    }
    class PricingStrategy {
        <<interface>>
        +calculate(TripRequest req, Driver driver) Fare
    }
    class TripRequestService {
        -MatchingStrategy matcher
        -PricingStrategy pricer
        +requestRide(TripRequest req) Trip
    }
    class Trip {
        +String tripId
        +TripStatus status
        +transition(TripStatus next)
    }
    PremiumDriver --|> Driver : extends
    EvDriver --|> Driver : extends
    TripRequestService o-- MatchingStrategy : uses (injected)
    TripRequestService o-- PricingStrategy : uses (injected)
    Driver --> Trip : fulfills
```

```mermaid
classDiagram
    class TripRequest {
        +Location pickup
        +Location dropoff
        +String riderId
    }
    class Trip {
        +String tripId
        -TripStatus status
        +Driver assignedDriver
        +transition(TripStatus) void
    }
    class Driver {
        +String id
        +String name
        -DriverStatus status
        +Location location
        +acceptRide(TripRequest) void
        +completeRide(Trip) void
        +isAvailableFor(TripRequest) boolean
    }
    class PremiumDriver {
        +String vehicleClass
        +boolean hasWifi
    }
    class EvDriver {
        +double batteryPercent
        +isAvailableFor(TripRequest) boolean
    }
    class TripRequestService {
        -MatchingStrategy matcher
        -PricingStrategy pricer
        +requestRide(TripRequest) Trip
    }
    class MatchingStrategy {
        <<interface>>
        +match(TripRequest, List~Driver~) Optional~Driver~
    }
    class PricingStrategy {
        <<interface>>
        +calculate(TripRequest, Driver) Fare
    }
    class LocationObserver {
        <<interface>>
        +onLocationUpdate(String, Location) void
    }
    class DriverLocationService {
        -Map~String,List~ subscribers
        +subscribe(String, LocationObserver) void
        +updateLocation(String, Location) void
    }
    class RiderEtaTracker {
        +onLocationUpdate(String, Location) void
    }
    class TripStatus {
        <<enumeration>>
        REQUESTED
        ACCEPTED
        IN_PROGRESS
        COMPLETED
        CANCELLED
    }
    class DriverStatus {
        <<enumeration>>
        AVAILABLE
        BUSY
        OFFLINE
    }
    PremiumDriver --|> Driver : extends
    EvDriver --|> Driver : extends
    TripRequestService o-- MatchingStrategy : uses (injected)
    TripRequestService o-- PricingStrategy : uses (injected)
    RiderEtaTracker ..|> LocationObserver : implements
    DriverLocationService --> LocationObserver : notifies
    Trip --> TripStatus : state
    Driver --> DriverStatus : state
    Trip --> Driver : assigned to
    TripRequest --> Trip : becomes
```

**Observable outcome:** PremiumDriver and EvDriver inherit the full base contract and extend it.

## End-to-end outcome

When a rider taps "Book Ride," a deceptively complex chain of decisions fires within seconds: 1.

## Alternatives considered

### Decision Guide: LLD Decision Guide for Ride Booking

Decision Guide: LLD Decision Guide for Ride Booking


## Failure and degraded modes

### Trade-offs & Failure Modes: Trade-offs and Production Constraints

- **Detection:** Trade-offs & Failure Modes: Trade-offs and Production Constraints
- **User or operator impact:** Trade-offs & Failure Modes: Trade-offs and Production Constraints



## Scenario context

Building an in-memory message queue is a premier LLD problem testing multithreaded design. By combining the observer pattern with Java reentrant locks, conditions, and concurrent atomic offsets, we implement a thread-safe broker that decouples producers and consumers.

* * *

Imagine you are building an in-memory logging and analytics processing engine for a microservice. Different parts of the application (e.g., HT…

This walkthrough focuses on **Design Challenge: Thread Contention in Event-Driven Systems**.

Before making a design choice, clarify:

- Imagine you are building an in-memory logging and analytics processing engine for a microservice.
- Different parts of the application (e.g., HTTP request loggers, billing events, security auditors) generate messages that must be processed asynchronously by multiple worker threads.
- A naive observer pattern implementation couples the publisher and subscriber.

**Concepts in play:** low-level-design-systems, stack-and-queue-data-structures, jvm-internals-and-garbage-collection, message-queues

## Stage 1 — Scope: System Actors and Core Requirements

- Before implementing the class model, we establish the requirements for our in-memory queue and define how actors interact.
- System Actors Producer: Represents the client thread generating messages.
- It publishes events to specific topics.
- Consumer: An independent execution thread that continuously polls messages from specific topics and partitions.

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** Consumer: An independent execution thread that continuously polls messages from specific topics and partitions.

## Stage 2 — Architectural Blueprint: Class Diagram

- The class diagram below outlines the structural composition of our in-memory queue: This class diagram details the relationships between the core components of our concurrent queue broker.
- The QueueBroker manages multiple Topic objects.
- Each Topic contains multiple TopicPartition structures.
- Each partition encapsulates a thread-safe array of Message entities, utilizing a ReentrantLock and a Condition variable to coordinate producers and consumers safely.

*Applies **stack-and-queue-data-structures** to the decision above.*

```mermaid
classDiagram
    QueueBroker "1" *-- "*" Topic : manages
    Topic "1" *-- "*" TopicPartition : contains
    TopicPartition "1" *-- "*" Message : holds
    ConsumerGroup "1" *-- "*" ConsumerInstance : coordinates
    ConsumerInstance --> QueueBroker : polls from
    class TopicPartition {
        -List~Message~ messages
        -ReentrantLock lock
        -Condition hasMessages
        +append(Message msg) void
        +read(int offset) Message
    }
    class ConsumerInstance {
        -String id
        -ConsumerGroup group
        +poll() void
    }
```

**Observable outcome:** Each partition encapsulates a thread-safe array of Message entities, utilizing a ReentrantLock and a Condition variable to coordinate producers and consumers safely.

## Stage 3 — Core Mechanics: Mapping the OOP Pillars

- Our design leverages the four pillars of Object-Oriented Programming to ensure clean separation of concerns: Abstraction: The QueueBroker abstracts partition management, offsets, and thread coordination.
- Producers simply call publish(topic, message) without managing lock states.
- The details of how messages are stored, indexed, and synchronized are completely hidden from the publisher.
- Encapsulation: The message list and read offsets are encapsulated inside TopicPartition and ConsumerGroup respectively.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

**Observable outcome:** Encapsulation: The message list and read offsets are encapsulated inside TopicPartition and ConsumerGroup respectively.

## Stage 4 — Deep Dive: Thread Synchronization and Consumer Offsets

- Let's look at the concurrency mechanics required to handle high-throughput message ingestion.
- The Internals of Lock-Free Offsets and Blocking Queues To guarantee thread-safety without creating bottlenecks, we isolate lock boundaries.
- If we locked the entire QueueBroker or Topic during a write, we would serialise all operations.
- Producers writing to unrelated topics would block each other.

*Applies **message-queues** to the decision above.*

**Observable outcome:** Producers writing to unrelated topics would block each other.

## Stage 5 — Visualizing Concurrency: The Producer-Consumer Flow

- The flowchart below visualizes the thread interaction between producers appending messages and consumers waiting for new data.
- This concurrency sequence diagram illustrates how producers and consumers synchronize.
- A consumer thread attempting to read from an empty partition enters a waiting state by calling await() on the partition's condition variable.
- When a producer thread locks the partition and appends a message, it invokes signal() .

*Applies **low-level-design-systems** to the decision above.*

```mermaid
flowchart TD
    Producer[Producer Thread] -->|lock| Partition[Topic Partition]
    Partition -->|append message| MsgList[Message List]
    MsgList -->|signal hasMessages| Consumer[Consumer Thread]
    Consumer -->|await on hasMessages| Idle[Waiting State]
    MsgList -->|read message| Consumer
```

**Observable outcome:** When a producer thread locks the partition and appends a message, it invokes signal() .

## Stage 6 — Decision and Extension: Custom Partition Routing

- In production systems, routing messages to partitions depends on the use case.
- By introducing a routing abstraction, we can dynamically change routing behavior without modifying the broker class.
- We compare standard strategies below: Using a polymorphic RoutingStrategy allows the client to select the correct balancing behavior dynamically based on system demands.

*Applies **stack-and-queue-data-structures** to the decision above.*

**Observable outcome:** We compare standard strategies below: Using a polymorphic RoutingStrategy allows the client to select the correct balancing behavior dynamically based on system demands.

## End-to-end outcome

After working through the stages, you should be able to explain:

- Keep these best practices in mind when designing multithreaded queues: 1.
- Avoid Global Locks: Place locks inside individual partitions rather than at the topic level to isolate lock contention.
- Partition Isolation: Place locks inside individual partitions to support concurrent parallel writes.
- Reentrant Locks: Use Java's ReentrantLock and Condition to block and wake up consumer threads safely.

## Alternatives considered

The source focuses on one primary design. A second architecture is not compared, so no alternative is invented here.

## Failure and degraded modes

### Trade-offs and Failure Modes: In-Memory Storage Limits

- **Detection:** Operating an event queue entirely in-memory introduces critical trade-offs: JVM Memory Pressure (Out of Memory): Since messages are stored inside Java lists, a slow consumer group will cause partitio…
- **User or operator impact:** Operating an event queue entirely in-memory introduces critical trade-offs: JVM Memory Pressure (Out of Memory): Since messages are stored inside Java lists, a slow consumer group will cause partitio…



## Scenario context

```architecture
{
  "version": 1,
  "title": "URL Shortener Architecture - Range Allocation & Read-Path Caching",
  "description": "High-throughput redirection architecture combining ZooKeeper range-based ticket allocation with aggressive Redis read caching.",
  "view": "high-level",
  "pattern": "cache-aside",
  "direction": "LR",
  "groups": [
    { "id": "ingress", "label": "Edge Ingress", "tone": "slate" },…

This walkthrough focuses on **Why Base62 and Not MD5?**.

Before making a design choice, clarify:

- Approach A — Hashing (MD5/SHA): - Hash the long URL: MD5("https://...") = 3b94d2a8...
- - Take first 7 chars: 3b94d2a .
- - Problem: Two different URLs might produce the same first 7 chars → collision → wrong redirect.

**Concepts in play:** caching, design-patterns-gof, jvm-internals-and-garbage-collection, low-level-design-systems

## Stage 1 — The Locker Room Analogy

- A locker room assigns locker numbers.
- The attendant doesn't randomly pick numbers — she uses the next available sequential number.
- You get "Locker 5" → you can find it instantly.
- URL shorteners work the same way: assign a unique sequential integer ID , then encode it in a compact string format.

*Applies **caching** to the decision above.*

**Observable outcome:** URL shorteners work the same way: assign a unique sequential integer ID , then encode it in a compact string format.

## Stage 2 — Short Codes, Redirects, and TTL: The Core Vocabulary

- Before building, align on the four concepts everything else depends on.
- Short Code — the compact identifier that replaces a long URL.
- cb , Xk3 , and my-blog are all short codes.
- They appear after the domain: https://tiny.url/cb .

*Applies **design-patterns-gof** to the decision above.*

**Observable outcome:** They appear after the domain: https://tiny.url/cb .

## Stage 3 — OOP Contracts: Interfaces and Collaborations

- The URL shortener's backbone is four focused Java interfaces.
- Each defines a contract — an agreement about what a collaborator can do without revealing how it does it.
- UrlShortenerService holds a reference to each interface and receives them via constructor injection; it never references a concrete class directly.
- Who implements each interface, who calls it, and what it abstracts: Runtime collaboration — how the components interact during a shorten() call: Structural relationships — ownership and implementation: This class diagra…

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```java
interface UrlEncoder {
    String encode(long id);  // converts counter ID to Base62 short code
}

interface CodeStore {
    String save(String longUrl);            // stores mapping, returns short code
    Optional<String> resolve(String code);  // looks up long URL by short code
    boolean exists(String code);            // deduplication check
}

interface AnalyticsTracker {
    void recordClick(String code, String referrer, Instant timestamp);
}

interface AliasValidator {
    boolean isValid(String customAlias);    // checks format, uniqueness, reserved words
}
```

```mermaid
flowchart LR
    Client -->|"shorten(longUrl)"| SVC[UrlShortenerService]
    SVC -->|"save(longUrl)"| Store["CodeStore (RedisStore / InMemoryStore)"]
    Store -->|shortCode| SVC
    SVC -->|"encode(id)"| Encoder["UrlEncoder (Base62Encoder)"]
    Encoder -->|"cb"| SVC
    SVC -->|shortCode| Client
```

**Observable outcome:** Who implements each interface, who calls it, and what it abstracts: Runtime collaboration — how the components interact during a shorten() call: Structural relationships — ownership and implementation: This class diagra…

## Stage 4 — OOP Pillars Applied to the URL Shortener

- Each classical OOP pillar maps directly to a concrete design decision in this system.
- Encapsulation — Base62Encoder owns its alphabet The 62-character alphabet ( a-z A-Z 0-9 ) and the modular-arithmetic encoding loop are private implementation details inside Base62Encoder .
- Callers invoke encode(125) and receive "cb" — they never see the CHARS constant or the while (id 0) loop.
- Swapping the alphabet (say, to a URL-safe Base64 variant) requires editing exactly one class, nowhere else.

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** Swapping the alphabet (say, to a URL-safe Base64 variant) requires editing exactly one class, nowhere else.

## Stage 5 — SOLID Principles in the URL Shortener Design

- SOLID is not an abstract checklist — each principle appears as a specific, verifiable choice here.
- Single Responsibility (SRP) — Each class has exactly one reason to change.
- Base62Encoder changes only if the encoding algorithm changes.
- A CodeStore implementation changes only if the persistence technology changes.

*Applies **caching** to the decision above.*

```java
public class UrlShortenerService {
    private final UrlEncoder encoder;
    private final CodeStore store;
    private final AnalyticsTracker tracker;

    public UrlShortenerService(UrlEncoder encoder, CodeStore store, AnalyticsTracker tracker) {
        this.encoder = encoder;
        this.store   = store;
        this.tracker = tracker;
    }
}
```

**Observable outcome:** A CodeStore implementation changes only if the persistence technology changes.

## Stage 6 — Interface Contracts: The Four Boundaries of the URL Shortener

- Each interface is a stable boundary.
- Anything inside that boundary can change freely; anything outside can only call the methods listed here.
- These four contracts are everything UrlShortenerService needs from the outside world.
- Any Spring @Bean that satisfies an interface can be wired in — production configs, test configs, and migration configs all swap implementations without modifying the service itself.

*Applies **design-patterns-gof** to the decision above.*

```java
/**
 * Converts a numeric counter ID into a compact short-code string.
 * Implementations: Base62Encoder, CustomAliasEncoder, Base58Encoder
 */
interface UrlEncoder {
    String encode(long id);  // e.g. encode(125) → "cb"
}

/**
 * Persists and retrieves short-code ↔ long-URL mappings.
 * Implementations: InMemoryStore (test), RedisStore (staging), DistributedStore (prod)
 */
interface CodeStore {
    String save(String longUrl);            // persists mapping, returns generated short code
    Optional<String> resolve(String code);  // returns long URL for code, or empty if not found
    boolean exists(String code);            // returns true if the code is already in use
}

/**
 * Records analytics for every redirect event.
 * Implementations: NoOpTracker (default), DatabaseTracker (analytics-on)
 */
interface AnalyticsTracker {
    void recordClick(String code, String referrer, Instant timestamp);
}

/**
 * Validates user-supplied custom aliases before storage.
 * Implementations: CustomAliasValidator
 */
interface AliasValidator {
    boolean isValid(String customAlias);  // false if blank, reserved, non-alphanumeric, or taken
}
```

```mermaid
classDiagram
    class UrlEncoder {
        <<interface>>
        +encode(id long) String
        +decode(code String) long
    }
    class CodeStore {
        <<interface>>
        +save(longUrl String) String
        +resolve(code String) Optional~String~
        +exists(code String) boolean
    }
    class AnalyticsTracker {
        <<interface>>
        +recordClick(code String, referrer String, ts Instant) void
    }
    class AliasValidator {
        <<interface>>
        +isValid(customAlias String) boolean
    }
    class Base62Encoder {
        -String CHARS
        +encode(id long) String
        +decode(code String) long
    }
    class CustomAliasEncoder {
        +encode(id long) String
    }
    class InMemoryStore {
        -Map~String,String~ store
        +save(longUrl String) String
        +resolve(code String) Optional~String~
        +exists(code String) boolean
    }
    class RedisStore {
        +save(longUrl String) String
        +resolve(code String) Optional~String~
        +exists(code String) boolean
    }
    class NoOpTracker {
        +recordClick(code, referrer, ts) void
    }
    class DatabaseTracker {
        +recordClick(code, referrer, ts) void
    }
    class CustomAliasValidator {
        +isValid(customAlias String) boolean
    }
    class UrlShortenerService {
        -UrlEncoder encoder
        -CodeStore store
        -AnalyticsTracker tracker
        -AliasValidator validator
        +shorten(longUrl String) String
        +resolve(shortCode String) String
    }
    Base62Encoder ..|> UrlEncoder : implements
    CustomAliasEncoder --|> Base62Encoder : extends
    InMemoryStore ..|> CodeStore : implements
    RedisStore ..|> CodeStore : implements
    NoOpTracker ..|> AnalyticsTracker : implements
    DatabaseTracker ..|> AnalyticsTracker : implements
    CustomAliasValidator ..|> AliasValidator : implements
    UrlShortenerService o-- UrlEncoder : uses (injected)
    UrlShortenerService o-- CodeStore : uses (injected)
    UrlShortenerService o-- AnalyticsTracker : uses (injected)
    UrlShortenerService o-- AliasValidator : uses (injected)
```

**Observable outcome:** Any Spring @Bean that satisfies an interface can be wired in — production configs, test configs, and migration configs all swap implementations without modifying the service itself.

## End-to-end outcome

Approach A — Hashing (MD5/SHA): - Hash the long URL: MD5("https://...") = 3b94d2a8...

## Alternatives considered

### Decision Guide: Choosing the Right URL Shortener Architecture

Start with a single DB + auto-increment.


## Failure and degraded modes

### Trade-offs & Failure Modes: Custom Aliases and Collision Handling

- **Detection:** Users sometimes want custom codes: tiny.url/my-blog .
- **User or operator impact:** Users sometimes want custom codes: tiny.url/my-blog .



Design larger object models with workflows, queues, and real state transitions.

LLD System Case Studies

A low-level design roadmap for SOLID, object modeling, design patterns, and machine-coding rounds.