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

low-level-design-guide

Learn how to design and implement a stateful, graph-based agent orchestration engine in Java with full OOP design.

Low-Level Design for an AI Agent Orchestration Engine: Designing a Stateful Execution Framework

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

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

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

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

## Scenario context

In this guide, we design a stateful, graph-based AI agent execution engine in Java using clean object-oriented principles. By structuring execution as nodes and edges over a shared state, we prevent memory leaks, manage complex routing, and create a highly extensible framework.

---

Imagine you are building a customer support automation platform. Your agent needs to read incoming emails, decide whether to fetch dat…

This walkthrough focuses on **The Design Challenge: Imperative Spaghetti vs. Graph-Based Orchestration**.

Before making a design choice, clarify:

- Imagine you are building a customer support automation platform.
- Your agent needs to read incoming emails, decide whether to fetch data from an internal billing system, call a validation model to ensure compliance, and either reply automatically or escalate to a human.
- When you start, you might implement this as a series of nested service class calls: This nested imperative code works fine for simple trees.

**Concepts in play:** graph-traversal-algorithms, llm-agents-and-langgraph, event-driven-architecture, low-level-design-systems

## Stage 1 — Use Cases & Actors

- Before diving into code, we must define the functional boundary of our engine.
- Actors End User: Submits a natural language query or task to the system.
- Orchestrator Platform: The core engine that loads the execution graph, tracks history, and manages state transitions.
- AI Model (LLM): The reasoning provider that determines planning steps or formatting.

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

**Observable outcome:** AI Model (LLM): The reasoning provider that determines planning steps or formatting.

## Stage 2 — Core Mechanics: Class Relationships and State Transitions

- To build a reliable graph orchestration engine, we must separate the structural configuration of our graph from the dynamic execution state.
- This distinction is captured in the class diagram below, detailing how static node models coordinate with thread-safe data context structures.
- This structural blueprint explains how the graph metadata is decoupled from runtime context.
- The StateGraph acts as a composite holding a map of Node interfaces and transition Edge instances.

*Applies **llm-agents-and-langgraph** to the decision above.*

```mermaid
classDiagram
    class StateGraph {
        -Map~String, Node~ nodes
        -Map~String, List~Edge~~ edges
        +addNode(String id, Node node)
        +addEdge(String fromNode, String toNode)
        +addConditionalEdge(String fromNode, String toNode, String stateKey, String expectedValue)
        +getNodes() Map~String, Node~
        +getTransitions(String nodeId) List~Edge~
    }

    class Node {
        <<interface>>
        +execute(AgentState state) NodeResult
    }

    class BaseNode {
        <<abstract>>
        -String name
        +getName() String
    }

    class LLMReasoningNode {
        -LLMClient llmClient
        -String promptTemplate
        +execute(AgentState state) NodeResult
    }

    class ToolExecutionNode {
        -ToolRegistry toolRegistry
        +execute(AgentState state) NodeResult
    }

    class HumanApprovalNode {
        +execute(AgentState state) NodeResult
    }

    class Edge {
        -String fromNode
        -String toNode
        -TransitionCondition condition
        +getFrom() String
        +getTo() String
        +evaluate(AgentState state) boolean
    }

    class AgentState {
        -String executionId
        -Map~String, Object~ values
        -List~String~ history
        +get(String key) Object
        +put(String key, Object val)
        +recordVisit(String nodeId)
        +getHistory() List~String~
    }

    class AgentExecutor {
        -StateGraph graph
        -StateStore stateStore
        +run(String executionId, String startNodeId) AgentState
        +resume(String executionId, Map~String, Object~ humanInput) AgentState
    }

    class Tool {
        <<interface>>
        +execute(Map~String, Object~ params) Map~String, Object~
    }

    class ToolRegistry {
        -Map~String, Tool~ tools
        +register(String name, Tool tool)
        +getTool(String name) Tool
    }

    StateGraph "1" *-- "*" Node : contains
    StateGraph "1" *-- "*" Edge : contains
    BaseNode ..|> Node : implements
    LLMReasoningNode --|> BaseNode : extends
    ToolExecutionNode --|> BaseNode : extends
    HumanApprovalNode --|> BaseNode : extends
    AgentExecutor --> StateGraph : executes
    AgentExecutor --> AgentState : modifies
    ToolExecutionNode --> ToolRegistry : uses
    ToolRegistry "1" *-- "*" Tool : manages
```

**Observable outcome:** The StateGraph acts as a composite holding a map of Node interfaces and transition Edge instances.

## Stage 3 — OOP Pillars Mapping

- Our design enforces the core object-oriented programming pillars to ensure clean separation of concerns: Encapsulation: The AgentState class encapsulates the internal map storing execution parameters and a list represen…
- Access to this state is restricted via getters and mutators, protecting the integrity of thread-local state during runs.
- Abstraction: The Node interface abstracts the behavior of graph execution blocks.
- The executor does not need to know whether a node calls an LLM, invokes a local database query, or prompts for human input; it simply invokes execute(AgentState) .

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

**Observable outcome:** The executor does not need to know whether a node calls an LLM, invokes a local database query, or prompts for human input; it simply invokes execute(AgentState) .

## Stage 4 — SOLID Principles Walkthrough

- Single Responsibility Principle (SRP): StateGraph is responsible only for maintaining the topology (nodes and edges) of the graph.
- It does not manage active thread executions.
- AgentExecutor handles the runtime lifecycle, coordinate state persistence, and manages step advancement.
- ToolRegistry is responsible solely for indexing and looking up executable tools.

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

**Observable outcome:** ToolRegistry is responsible solely for indexing and looking up executable tools.

## Stage 5 — Interface Contracts Inventory

- Below, we detail the interfaces that serve as boundaries between different subsystems.
- Node Purpose: Represents a single logical execution block inside the graph.
- Method Signature: NodeResult execute(AgentState state) : Executes the node operation using the current workflow state.
- Parameters: AgentState state (read-write access to current execution state).

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

**Observable outcome:** Parameters: AgentState state (read-write access to current execution state).

## Stage 6 — Deep Dive: Stateful Execution Internals

- Orchestrator engines operate like low-overhead virtual machines running steps sequentially, writing to a persistent ledger at each transition boundary.
- Here, we analyze the runtime mechanics, mathematical models, and latency characteristics under high concurrencies.
- The Internals The core execution path inside the AgentExecutor is a sequential state transition loop.
- When execution is initiated, the engine reads the active node configuration, executes the business logic inside a database transaction sandbox, and checks the conditional edge evaluate functions to calculate the next ta…

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** When execution is initiated, the engine reads the active node configuration, executes the business logic inside a database transaction sandbox, and checks the conditional edge evaluate functions to calculate the next ta…

## End-to-end outcome

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

- Beware Infinite Loop Cycles: If an LLM node continuously triggers a tool node, and the tool outputs keep failing validation, the agent can enter an infinite loop, draining API budgets.
- Always declare an iteration counter limit within the state properties and force termination if it is exceeded.
- State-Graph vs Callbacks: Avoid nested class calls when building agent loops; model them as nodes (execution blocks) and edges (transition paths) over a shared, serializable state context.
- Pause and Resume: Asynchronous loops require state suspension models.

## Alternatives considered

### The Design Challenge: Imperative Spaghetti vs. Graph-Based Orchestration

Imagine you are building a customer support automation platform.

### Decision Guide: State Storage Framework Comparison

When designing your agent database layer, choose your storage system based on operational latency constraints and auditing requirements.


## Failure and degraded modes

### Architectural Trade-offs and Failure Modes

- **Detection:** Latency: Writing state snapshots to database disks at every node step ensures recovery after hardware failure, but adds database write latency (~10-20ms per step).
- **User or operator impact:** Latency: Writing state snapshots to database disks at every node step ensures recovery after hardware failure, but adds database write latency (~10-20ms per step).



## 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.



## 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 .



## 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

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.



Step 1

Apply SOLID OOP design principles, design patterns, state machines, and concurrent cache controllers.

Low-Level Design Patterns