Meet Sam. Four months ago, Sam joined a fast-growing document management startup as a backend developer. The company's product processes documents in various formats, JSON, XML, YAML, CSV, and more. Sam's job? Build a robust document parsing system.

Sounds straightforward, right? It was... until it wasn't.

It's Thursday, 4:23 PM. Sam is in a meeting with the product team.

Product Manager (Emma): "Great news! We just signed a huge enterprise client. They need support for TOML, INI, and PDF text extraction. Can you add those by Monday?"

Sam (internally screaming): "Sure, let me check the code..."

Sam opens the laptop. The color drains from Sam's face.

The Current Code

Here's what Sam has been dealing with:

// THE NIGHTMARE - Sam's current parser selection code.

// In document_service.rs.
pub fn parse_document(content: &str, format: &str) -> Result<ParsedDoc, Error> {
    let parser: Box<dyn Parser> = if format == "json" {
        Box::new(JsonParser::new())
    } else if format == "xml" {
        Box::new(XmlParser::new())
    } else if format == "yaml" {
        Box::new(YamlParser::new())
    } else if format == "csv" {
        Box::new(CsvParser::new())
    } else if format == "markdown" {
        Box::new(MarkdownParser::new())
    } else if format == "html" {
        Box::new(HtmlParser::new())
    } else if format == "toml" {
        Box::new(TomlParser::new())
    } else if format == "ini" {
        Box::new(IniParser::new())
    } else {
        return Err(Error::UnsupportedFormat(format.to_string()));
    };

    parser.parse(content)
}

// In file_processor.rs - SAME CODE AGAIN!
pub fn process_file(path: &Path) -> Result<ParsedDoc, Error> {
    let extension = path.extension()...;
    let parser: Box<dyn Parser> = if extension == "json" {
        Box::new(JsonParser::new())
    } else if extension == "xml" {
        Box::new(XmlParser::new())
    } else if extension == "yaml" {
        Box::new(YamlParser::new())
    }
    // ... DUPLICATED 8 MORE TIMES!
}

// In api_handler.rs - SAME CODE THIRD TIME!
async fn handle_upload(file: MultipartFile) -> Result<Response> {
    let format = detect_format(&file);
    let parser: Box<dyn Parser> = if format == "json" {
        Box::new(JsonParser::new())
    }
    // ... DUPLICATED AGAIN!
}

// In batch_processor.rs - FOURTH TIME!
// In validator.rs - FIFTH TIME!
// In converter.rs - SIXTH TIME!
// ... This pattern repeats in 15+ FILES!

Let me break down what's happening here for those new to Rust.

The code is trying to create a "parser", a piece of code that reads a document and makes sense of its structure. Since different file formats (JSON, XML, YAML) need different parsing logic, Sam created separate parser types for each one. The Box<dyn Parser> syntax is Rust's way of saying "give me any type that knows how to parse, and I don't care which specific one." That's actually a good idea!

The problem isn't the concept, it's the execution. Every single file that needs a parser has to include this massive decision tree. Want to parse a document in the API handler? Copy the if-else chain. Need to parse in the batch processor? Copy it again. File validator? You guessed it, copy it a third time. Now imagine adding a new format like TOML. You'd have to hunt down every single copy of this chain and add a new branch. Miss one? That's a bug waiting to happen in production.

If you've been coding for any length of time, you've probably felt that sinking feeling Sam is experiencing right now. That moment when you realise the codebase has grown into something unwieldy, and every small change requires touching a dozen files.

Sam's internal monologue:

"Every time we add a new format, I have to modify FIFTEEN different files. Each with the same giant if-else chain. Last time I added HTML parser, I missed updating it in two places and we had a production bug. How am I supposed to add THREE new formats by Monday?!"

The specific horrors:

1. Massive Duplication: Same if-else chain in 15+ files.

2. Error-Prone: Easy to miss updating one place.

3. No Single Source of Truth: Parser selection logic scattered everywhere.

4. Hard to Test: Can't test parser creation independently.

5. No Extensibility: Can't add parsers without recompiling.

6. Maintenance Nightmare: Every change touches multiple files.

The Parser Chaos

Let's break down exactly what's wrong with Sam's code. If you're new to software design, this section will help you recognise patterns in your own projects that might be heading toward the same cliff.

Problem 1: The If-Else Chain

// This appears in 15 different files!
let parser: Box<dyn Parser> = if format == "json" {
    Box::new(JsonParser::new())
} else if format == "xml" {
    Box::new(XmlParser::new())
} else if format == "yaml" {
    Box::new(YamlParser::new())
} else if format == "csv" {
    Box::new(CsvParser::new())
} else if format == "markdown" {
    Box::new(MarkdownParser::new())
} else if format == "html" {
    Box::new(HtmlParser::new())
} else if format == "toml" {
    Box::new(TomlParser::new())
} else if format == "ini" {
    Box::new(IniParser::new())
} else {
    return Err(Error::UnsupportedFormat(format.to_string()));
};

Problems with this approach:

• Length: 18 lines just to create a parser.

• Duplication: Repeated 15+ times across the codebase.

• Fragility: Typo in one place equals a bug.

• Not Extensible: Can't add formats without modifying code

Problem 2: No Abstraction

Every piece of code that needs a parser must know all possible parser types, how to construct each one, the exact string matching logic, and the mapping from format string to parser type. This violates something called the Dependency Inversion Principle, one of the fundamental rules of clean software design. In simple terms, high-level code (like your document service) shouldn't depend on low-level implementation details (like knowing about JsonParser, XmlParser, and every other concrete parser type).

Think of it like this: when you order coffee at a cafe, you don't need to know the exact temperature of the water, the grind size of the beans, or which brand of espresso machine they're using. You just say "I'll have a latte" and the barista handles the details. That's the abstraction we're missing here.

Problem 3: Testing

#[test]
fn test_parse_json() {
    // To test, must include full if-else chain.
    let parser = if format == "json" {
        Box::new(JsonParser::new())
    } else if format == "xml" {
        // ... need entire chain!
    };

    // Can't easily mock or stub.
    // Can't test parser creation in isolation.
}

When you can't test something easily, you tend not to test it at all. And untested code is a ticking time bomb waiting to explode in production.

The Real-World Impact

Sam keeps a log of incidents:

Week 1: Added HTML parser, forgot to update batch_processor.rs
        → Batch jobs crashed, 2 hours downtime

Week 2: Typo "yml" vs "yaml" in one file caused inconsistent behavior
        → Customer complaints, had to hotfix

Week 3: Added TOML parser, updated 14 files, missed 1
        → CLI tool couldn't parse TOML, support tickets

Week 4: Tried to write unit test, realized it's impossible to test
        → No tests = more bugs in production

Week 5: Boss wants 3 new formats by Monday
        → Sam considers quitting

What's cyclomatic complexity? It's a fancy way of measuring how many different paths your code can take. Each if or else branch adds to the complexity. A cyclomatic complexity of 9 means there are 9 different paths through that function which means 9 different ways things can go wrong, and 9 different scenarios you need to test. That's way too high for what should be a simple "give me the right parser" operation.

"I'm not solving problems anymore. I'm just copying and pasting if-else statements. There has to be a better way!"

The Breaking Point

Friday morning. Sam is called into a meeting with Emma (Product Manager) and the CTO, David.

Emma: "Sam, I know we just talked about adding three new formats, but I have more news..."

Sam (nervously): "More?"

Emma: "Our new enterprise client uses 12 different document formats. They need support for all of them. Can we…"

Sam (interrupting): "No. We can't. Not with the current architecture."

David: "What do you mean?"

Sam (frustrated): "Every time we add a new format, I have to modify 15 different files. Each one has the same giant if-else chain. It takes hours, it's error-prone, and I've already introduced bugs three times this month."

Sam opens the laptop and shows them the code.

Sam: "Look at this. This if-else chain is duplicated everywhere. Adding your 12 formats means updating it 15 times per format. That's 180 places I have to modify. And if I miss even ONE, we get production bugs."

David (understanding dawning): "Oh. That's... not good."

Emma: "Is there a way to fix this?"

David: "Yes. We need to refactor. Sam, have you heard of the Factory Pattern?"

Sam: "Factory? Like a factory that makes things?"

David draws on the whiteboard:

Sam: "So instead of everyone knowing how to create parsers, they just ask the factory?"

David: "Right! And we can make it even better with a registry. That way, you can add new parsers without even modifying the factory."

Sam (excited): "So adding the 12 new formats would just mean creating 12 new parser structs and registering them?"

David: "Exactly. No changes to existing code."

Emma: "How long would this refactoring take?"

David: "A few days for the factory. But then adding new formats becomes trivial, maybe 30 minutes each."

Sam: "Let's do it. I can't keep maintaining this mess."

Enter the Factory Pattern

Sam spends the weekend reading about the Factory Pattern. Monday morning, armed with coffee and determination, Sam is ready to refactor.

What is the Factory Pattern?

The Factory Pattern is what we call a creational design pattern. Design patterns are essentially battle-tested solutions to common programming problems, recipes that generations of developers have refined over decades. The Factory Pattern specifically deals with the problem of creating objects.

Here's the core insight: instead of scattering object creation code throughout your application, you centralise it in one place. That "one place" is the factory.

The Core Idea

Instead of this:

Client Code → Directly creates object
           → Knows about all concrete types
           → Scattered creation logic

We do this:

Client Code → Asks factory for object
Factory → Creates the right type
       → Centralizes creation logic
       → Hides concrete types

It's like the difference between cooking at home versus ordering from a restaurant. When you cook at home, you need to know all the recipes, have all the ingredients, and understand every technique. When you order from a restaurant, you just say what you want and the kitchen handles everything.

Let's break down what each piece does:

1. Product Interface (DocumentParser): This is a trait in Rust (similar to an interface in other languages). It defines a contract, "here's what all parsers must be able to do." Every parser promises to implement parse(), name(), and supported_extensions().

2. Concrete Products (JsonParser, XmlParser, etc.): These are the actual implementations. Each one knows how to parse its specific format. JsonParser knows JSON, XmlParser knows XML, and so on.

3. Factory (ParserFactory): This is the star of the show. It takes a format string like "json" and returns the appropriate parser. Client code never needs to know which concrete type it's getting, it just works with the trait.

4. Client: This is any code that needs a parser. It asks the factory, gets a parser, and uses it. Simple.

Real-World Analogy

David's explanation:

"Think of a car factory. You walk in and say 'I want a sedan.' You don't need to know:

• How to build a sedan

• What parts it needs

• The assembly process

The factory handles all that. You just get your car.

Same with parser factory. You say 'I want a JSON parser.' You don't need to know:

• How to construct it

• What dependencies it has

• Implementation details

The factory gives you a parser. You just use it."

Factory Pattern & Our Code

Let's dive deeper into how the Factory Pattern works and why it solves Sam's problem.

Before vs After

BEFORE (Without Factory):

// In document_service.rs.
let parser = if format == "json" {
    Box::new(JsonParser::new())
} else if format == "xml" {
    Box::new(XmlParser::new())
}
// ... 8 more branches.

// In file_processor.rs.
let parser = if format == "json" {  // DUPLICATED!
    Box::new(JsonParser::new())
} else if format == "xml" {
    Box::new(XmlParser::new())
}
// ... 8 more branches.

// In api_handler.rs.
let parser = if format == "json" {  // DUPLICATED AGAIN!
    Box::new(JsonParser::new())
}
// ... you get the idea.

AFTER (With Factory):

// In document_service.rs
let parser = ParserFactory::create(format)?;

// In file_processor.rs
let parser = ParserFactory::create(format)?;  // Same call, but OK!

// In api_handler.rs
let parser = ParserFactory::create(format)?;  // Consistent!

From 18 lines per file to 1 line per file!

The magic here isn't just that the code is shorter, it's that every file now does the same thing in the same way. If you need to change how parsers are created, you change it in ONE place, and the change propagates everywhere automatically.

This diagram shows the dance that happens when you request a parser. The client never talks directly to JsonParser or XmlParser, it only talks to the Factory. The Factory is the matchmaker, connecting requests to the right implementations.

Key Benefits

1. Centralised Creation: One place to modify when adding or changing parsers.

2. Encapsulation: Hides construction complexity from client code.

3. Flexibility: Easy to change what's created without affecting callers.

4. Testability: Can mock the factory for unit tests.

5. Maintainability: Changes don't ripple across the codebase.

The SOLID Principles

If you're not familiar with SOLID, these are five principles of object-oriented design that help create maintainable software. The Factory Pattern naturally supports several of them:

1. Single Responsibility Principle

Each piece of code should do one thing and do it well:

• Factory's only job: create parsers

• Parser's only job: parse documents

• Clear separation of concerns

2. Open/Closed Principle

Software should be open for extension but closed for modification. With our factory:

• Open for extension: we can add new parsers

• Closed for modification: we don't need to change existing client code

• This is achieved through the registry pattern (coming up!)

3. Dependency Inversion Principle

High-level code shouldn't depend on low-level details:

• Client depends on the Parser trait (abstraction)

• Not on JsonParser, XmlParser (concrete types)

• Factory bridges the gap

The Solution

"Alright," Sam says, opening a fresh terminal. "Let's build this factory!"

Step 1: Define the Parser Trait

First, we need the interface that all parsers will implement. In Rust, we use a trait for this, it's like a contract that says "any type that wants to be a parser must provide these capabilities."

Create src/parser_trait.rs:

use std::error::Error;

/// The core Parser trait - all parsers implement this.
///
/// This is the "Product" interface in Factory Pattern terminology.
pub trait DocumentParser: Send + Sync {
    /// Parse the document content and return structured data.
    fn parse(&self, content: &str) -> Result<serde_json::Value, Box<dyn Error>>;

    /// Get the parser name. (e.g., "JSON", "XML")
    fn name(&self) -> &str;

    /// Get supported file extensions. (e.g., ["json", "jsonl"])
    fn supported_extensions(&self) -> Vec<&str>;

    /// Get a human-readable description.
    fn description(&self) -> &str;
}

What's happening here?

The DocumentParser trait defines four methods that every parser must implement. The Send + Sync bounds are Rust-specific, they tell the compiler that parsers can be safely shared between threads. This matters because our API might handle multiple requests simultaneously.

The parse method returns Result<serde_json::Value, Box<dyn Error>>. In Rust, Result is how we handle operations that might fail. It's either Ok(value) for success or Err(error) for failure. serde_json::Value is a flexible type that can represent any JSON structure, perfect for our parsed documents.

Sam's note: "This trait defines what ALL parsers must do. Any parser can be used interchangeably because they all implement this interface. That's the power of abstraction!"

Step 2: Create Concrete Parsers

Now let's build the actual parsers. Each one implements the trait in its own way.

Create src/parsers/json_parser.rs:

use crate::parser_trait::DocumentParser;
use std::error::Error;

/// JSON document parser.
pub struct JsonParser;

impl JsonParser {
    pub fn new() -> Self {
        Self
    }
}

impl DocumentParser for JsonParser {
    fn parse(&self, content: &str) -> Result<serde_json::Value, Box<dyn Error>> {
        // Parse JSON using serde_json.
        let value: serde_json::Value = serde_json::from_str(content)?;
        Ok(value)
    }

    fn name(&self) -> &str {
        "JSON"
    }

    fn supported_extensions(&self) -> Vec<&str> {
        vec!["json", "jsonl"]
    }

    fn description(&self) -> &str {
        "Parses JSON (JavaScript Object Notation) documents"
    }
}

Notice how simple this is! The JsonParser struct is actually empty, it's what Rust calls a "zero-sized type." It doesn't need to store any data; it just provides the parsing behaviour.

The ? operator in serde_json::from_str(content)? is Rust's way of propagating errors. If parsing fails, the error automatically gets returned to the caller. No try-catch blocks needed.

Let's create a YAML parser too:

Create src/parsers/yaml_parser.rs:

use crate::parser_trait::DocumentParser;
use std::error::Error;

/// YAML document parser.
pub struct YamlParser;

impl YamlParser {
    pub fn new() -> Self {
        Self
    }
}

impl DocumentParser for YamlParser {
    fn parse(&self, content: &str) -> Result<serde_json::Value, Box<dyn Error>> {
        // Parse YAML and convert to JSON value.
        let value: serde_json::Value = serde_yaml::from_str(content)?;
        Ok(value)
    }

    fn name(&self) -> &str {
        "YAML"
    }

    fn supported_extensions(&self) -> Vec<&str> {
        vec!["yaml", "yml"]
    }

    fn description(&self) -> &str {
        "Parses YAML (YAML Ain't Markup Language) documents"
    }
}

Sam: "Each parser is now a standalone module. They don't know about each other. Perfect separation of concerns!"

Step 3: Create the Factory

Now for the main event, the factory itself! This is where the magic happens.

Create src/factory.rs:

use crate::parser_trait::DocumentParser;
use crate::parsers::*;
use std::sync::Arc;

/// Parser Factory - Creates parsers based on format.
///
/// This is the FACTORY in Factory Pattern terminology.
pub struct ParserFactory;

impl ParserFactory {
    /// Create a parser based on format string.
    ///
    /// This is a STATIC FACTORY METHOD - no instance needed.
    pub fn create(format: &str) -> Result<Arc<dyn DocumentParser>, String> {
        match format.to_lowercase().as_str() {
            "json" | "jsonl" => Ok(Arc::new(JsonParser::new())),
            "xml" | "xhtml" => Ok(Arc::new(XmlParser::new())),
            "yaml" | "yml" => Ok(Arc::new(YamlParser::new())),
            "csv" | "tsv" => Ok(Arc::new(CsvParser::new())),
            "md" | "markdown" => Ok(Arc::new(MarkdownParser::new())),
            _ => Err(format!("Unsupported format: {}", format)),
        }
    }

    /// Create parser from filename extension.
    pub fn create_from_filename(filename: &str) -> Result<Arc<dyn DocumentParser>, String> {
        let extension = filename
            .rsplit('.')
            .next()
            .ok_or_else(|| "No file extension found".to_string())?;

        Self::create(extension)
    }
}

What just happened?

Let's break this down piece by piece:

• match expression: This replaces the ugly if-else chain. Rust's match is exhaustive, the compiler ensures you handle all cases. The _ arm catches anything not explicitly matched.

• format.to_lowercase(): We normalise the input so "JSON", "Json", and "json" all work the same way. Small detail, big usability improvement.

• Arc<dyn DocumentParser>: Arc stands for "Atomic Reference Counted." It's a smart pointer that allows multiple parts of your code to share ownership of the same parser safely. The dyn DocumentParser means "any type that implements DocumentParser", that's how we achieve polymorphism in Rust.

• create_from_filename: A convenience method. If someone has a file path like "data.json", this extracts "json" and creates the right parser.

The transformation:

// Before: 18 lines of if-else per file.
// After: 1 line.
let parser = ParserFactory::create("json")?;

Sam (amazed): "That's it? That's the whole factory?"

David: "Yep! Simple, clean, and now there's only ONE place to update when adding new formats."

Step 4: Using the Factory

Now let's update the document service to use our shiny new factory:

// BEFORE (the nightmare):
pub fn parse_document(content: &str, format: &str) -> Result<ParsedDoc, Error> {
    let parser: Box<dyn Parser> = if format == "json" {
        Box::new(JsonParser::new())
    } else if format == "xml" {
        Box::new(XmlParser::new())
    } else if format == "yaml" {
        Box::new(YamlParser::new())
    } else if format == "csv" {
        Box::new(CsvParser::new())
    } else if format == "markdown" {
        Box::new(MarkdownParser::new())
    } else {
        return Err(Error::UnsupportedFormat(format.to_string()));
    };

    parser.parse(content)
}

// AFTER (clean and beautiful):
pub fn parse_document(content: &str, format: &str) -> Result<ParsedDoc, Error> {
    let parser = ParserFactory::create(format)
        .map_err(|e| Error::UnsupportedFormat(e))?;

    parser.parse(content).map_err(Error::from)
}

From 18 lines to 5 lines! And this same transformation happens in ALL 15 files that needed parser creation.

Step 5: Testing the Factory

One of the biggest wins with the Factory Pattern is testability. Now we can test parser creation independently:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_factory_creates_json_parser() {
        let parser = ParserFactory::create("json").unwrap();
        assert_eq!(parser.name(), "JSON");
    }

    #[test]
    fn test_factory_creates_yaml_parser() {
        let parser = ParserFactory::create("yaml").unwrap();
        assert_eq!(parser.name(), "YAML");
    }

    #[test]
    fn test_factory_handles_case_insensitivity() {
        let parser1 = ParserFactory::create("JSON").unwrap();
        let parser2 = ParserFactory::create("json").unwrap();
        assert_eq!(parser1.name(), parser2.name());
    }

    #[test]
    fn test_factory_from_filename() {
        let parser = ParserFactory::create_from_filename("data.json").unwrap();
        assert_eq!(parser.name(), "JSON");
    }

    #[test]
    fn test_factory_unsupported_format() {
        let result = ParserFactory::create("unsupported");
        assert!(result.is_err());
    }

    #[test]
    fn test_parse_json() {
        let parser = ParserFactory::create("json").unwrap();
        let content = r#"{"name": "test", "value": 42}"#;
        let result = parser.parse(content);
        assert!(result.is_ok());
    }
}

Sam: "Look! I can test the factory independently! And each parser independently! This was impossible before!"

The Registry Pattern

David: "Sam, the factory is great. But we can make it even better with a registry."

Sam: "A registry?"

David: "Right now, to add a new parser, you still have to modify the factory's match statement. What if we could register parsers dynamically?"

The Problem with the Simple Factory

Even with our nice factory, adding a new parser requires changing the factory code:

// To add TOML parser, must modify this:
pub fn create(format: &str) -> Result<Arc<dyn DocumentParser>, String> {
    match format.to_lowercase().as_str() {
        "json" | "jsonl" => Ok(Arc::new(JsonParser::new())),
        "xml" | "xhtml" => Ok(Arc::new(XmlParser::new())),
        // ... existing parsers ...
        "toml" => Ok(Arc::new(TomlParser::new())),  // NEW! Must edit factory.
        _ => Err(format!("Unsupported format: {}", format)),
    }
}

It's way better than before, but can we do even better?

The Registry Solution

A registry is like a phone book for parsers. Instead of hardcoding which parsers exist, we maintain a dynamic collection that can be modified at runtime.

Create src/registry.rs:

use crate::parser_trait::DocumentParser;
use once_cell::sync::Lazy;
use std::collections::HashMap;
use std::sync::{Arc, RwLock};

/// Parser Registry - Extensible parser registration system.
///
/// This allows adding new parsers WITHOUT modifying the factory!
pub struct ParserRegistry {
    parsers: RwLock<HashMap<String, Arc<dyn DocumentParser>>>,
}

impl ParserRegistry {
    fn new() -> Self {
        Self {
            parsers: RwLock::new(HashMap::new()),
        }
    }

    /// Register a new parser for a given format.
    pub fn register(&self, format: String, parser: Arc<dyn DocumentParser>) {
        let mut parsers = self.parsers.write().unwrap();
        parsers.insert(format.to_lowercase(), parser);
    }

    /// Get a parser by format name.
    pub fn get(&self, format: &str) -> Option<Arc<dyn DocumentParser>> {
        let parsers = self.parsers.read().unwrap();
        parsers.get(&format.to_lowercase()).cloned()
    }

    /// List all registered parsers.
    pub fn list_all(&self) -> Vec<(String, Arc<dyn DocumentParser>)> {
        let parsers = self.parsers.read().unwrap();
        parsers
            .iter()
            .map(|(k, v)| (k.clone(), Arc::clone(v)))
            .collect()
    }
}

/// Global parser registry singleton.
static PARSER_REGISTRY: Lazy<ParserRegistry> = Lazy::new(|| {
    let registry = ParserRegistry::new();

    // Pre-register default parsers.
    use crate::parsers::*;
    registry.register("json".to_string(), Arc::new(JsonParser::new()));
    registry.register("xml".to_string(), Arc::new(XmlParser::new()));
    registry.register("yaml".to_string(), Arc::new(YamlParser::new()));
    registry.register("csv".to_string(), Arc::new(CsvParser::new()));
    registry.register("markdown".to_string(), Arc::new(MarkdownParser::new()));

    registry
});

/// Get the global parser registry.
pub fn get_registry() -> &'static ParserRegistry {
    &PARSER_REGISTRY
}

Let's unpack what's happening here:

The RwLock<HashMap<...>> is a thread-safe way to store our parsers. RwLock allows multiple readers OR one writer at a time, perfect for a registry that's read often but written rarely.

Lazy from the once_cell crate gives us lazy initialisation. The registry isn't created until the first time someone calls get_registry(). After that, the same instance is reused forever. This is the Singleton pattern working alongside our Factory pattern.

The default parsers are registered when the registry is first accessed. But here's the key insight: you can call register() at any time to add more parsers!

Using the Registry

// Get parser from registry.
let parser = get_registry()
    .get("json")
    .ok_or("Parser not found")?;

// Add new parser WITHOUT modifying existing code!
get_registry().register(
    "toml".to_string(),
    Arc::new(TomlParser::new())
);

Sam (excited): "So to add TOML, I just create TomlParser and register it? No changes to factory OR client code?"

David: "Exactly! You could even load parsers from plugins at runtime if you wanted!"

Adding a New Parser

Here's the complete process for adding TOML support:

// Step 1: Create the parser. (new file: src/parsers/toml_parser.rs)
pub struct TomlParser;

impl DocumentParser for TomlParser {
    fn parse(&self, content: &str) -> Result<serde_json::Value, Box<dyn Error>> {
        let value: toml::Value = toml::from_str(content)?;
        // Convert TOML value to JSON value for consistency.
        let json = serde_json::to_value(value)?;
        Ok(json)
    }

    fn name(&self) -> &str {
        "TOML"
    }

    fn supported_extensions(&self) -> Vec<&str> {
        vec!["toml"]
    }

    fn description(&self) -> &str {
        "Parses TOML (Tom's Obvious, Minimal Language) configuration files"
    }
}

// Step 2: Register it. (in main.rs or initialization code)
get_registry().register("toml".to_string(), Arc::new(TomlParser::new()));

// Step 3: Done! No other changes needed!

That's it! No modifications to:

• Factory code

• Client code

• Other parsers

• API handlers

• Tests

Just:

• Create new parser

• Register it

• It works everywhere!

Sam (amazed): "This is incredible! Emma wanted 12 new formats. With the registry, I can add all 12 without touching ANY existing code!"

The Resolution

Monday Morning - The Demo

Sam calls a meeting with Emma and David to show the new system.

Sam: "Alright, remember when you wanted support for 12 new formats? Watch this."

Sam opens the terminal:

# Create a new parser (takes 5 minutes)
# src/parsers/toml_parser.rs - 30 lines of code.

# Register it (takes 1 line)
# registry.register("toml".to_string(), Arc::new(TomlParser::new()));

# Test it immediately.
curl -X POST http://localhost:3000/parse \
  -H "Content-Type: application/json" \
  -d '{"content": "name = \"test\"\nvalue = 42", "format": "toml"}'

# Response: Success!

Emma (amazed): "Wait, that's it? You just added TOML support in 5 minutes?"

Sam: "Yep. And I didn't touch ANY existing code. No changes to handlers, no changes to other parsers, no changes to tests."

David: "That's the power of the Factory Pattern with Registry. Show them the before/after metrics."

The Metrics That Matter

Before (If-Else Hell):

After (Factory + Registry):

Architecture Evolution

Before:

If-Else Chains Everywhere
document_service.rs    ────┐
file_processor.rs      ────┤
api_handler.rs         ────┤
batch_processor.rs     ────┤  All contain
validator.rs           ────┼─ same 18-line
converter.rs           ────┤  if-else chain
cli_tool.rs            ────┤
upload_handler.rs      ────┤
... 8 more files       ────┘

Adding format = Modify 15+ files

After:

Clean Factory + Registry
                    ┌──────────────┐
All Clients ───────▶│   Registry   │
                    │  (Singleton) │
                    └──────┬───────┘
                           │
            ┌──────────────┼──────────────┐
            ▼              ▼              ▼
        JsonParser    YamlParser    CsvParser
            ▼              ▼              ▼
        XmlParser    TomlParser    ... more

Adding format = Create 1 file + 1 line to register

Code Quality Transformation

Team Reaction

Emma: "So you can add all 12 formats for the enterprise client?"

Sam: "I can add them this week. Probably 2-3 hours total for all 12."

Emma (excited): "Last time you estimated 3 hours PER format!"

Sam: "That was before the refactor. Now it's just:

1. Create parser (15 min)

2. Write tests (10 min)

3. Register it (1 line)

4. Done!"

David: "And the best part? The code is now maintainable. When we hire new developers, they won't need to hunt through 15 files to understand parser selection. It's all in one place."

Production Deployment

Sam deploys the new factory-based system to production.

Deployment Log:

All existing parsers working
Zero breaking changes
Response times improved (10% faster)
Memory usage down (parsers shared via Arc)
Test coverage up from 12% to 87%
Code complexity down 78%

Incident Log (Next 30 Days):

Week 1: 0 parser-related bugs (was 2-3/week)
Week 2: 0 parser-related bugs
Week 3: 0 parser-related bugs
Week 4: 0 parser-related bugs

Total: 0 bugs!

Feature Velocity:

Formats added: 12 (all enterprise client formats)
Time taken: 3.5 hours total
Bugs introduced: 0
Files modified: 12 new files, 0 existing files modified

When to Use (and Not Use) Factory Pattern

Now that you've seen the Factory Pattern in action, let's talk about when it makes sense and when it doesn't.

Use Factory Pattern When:

1. Creating objects requires complex logic

If you find yourself with multiple conditional branches, configuration-based instantiation, or object creation that varies based on input, a factory can help centralise and simplify that logic.

2. You have a family of related classes

When you have multiple types that implement the same interface and are used interchangeably (like our parsers), a factory provides a clean way to select between them.

3. Object creation is scattered

The biggest red flag is finding the same creation code duplicated across your codebase. That's exactly what Sam was dealing with, and exactly what the factory fixed.

4. You want loose coupling

If you want client code to work with abstractions rather than concrete types, a factory acts as the bridge. Clients ask for "a parser" without knowing or caring about the specific implementation.

Don't Use Factory Pattern When:

1. Object creation is simple

If creating an object is just calling new() with no complex logic, a factory adds unnecessary abstraction:

// Overkill.
let user = UserFactory::create(name, email);

// Better - just use new directly.
let user = User::new(name, email);

2. You only have one concrete type

If there's no polymorphism needed, no variants to choose from, a factory adds no value.

3. Performance is critical

Factories add a small amount of indirection. For most applications this is negligible, but in performance-critical hot paths, direct instantiation may be faster. Always profile before optimizing!

4. Added complexity not justified

If your team doesn't understand the pattern, or if you're solving a simple problem with a complex solution, step back and ask if you really need it. Remember YAGNI, You Aren't Gonna Need It.

Conclusion

When I first started writing backend systems, I made the same mistakes Sam did. I'd copy-paste code, add another else if branch, and tell myself "I'll clean this up later." Spoiler: later never came. Instead, the codebase grew into something I dreaded opening every morning.

The Factory Pattern wasn't something I learned from a textbook and immediately understood. It clicked for me only after I'd experienced the pain firsthand, after I'd introduced production bugs because I forgot to update one of twelve files, after I'd spent entire weekends doing what should have been a thirty-minute task.

Here's what I want you to take away from this:

Design patterns aren't academic exercises. They're battle scars turned into blueprints. Every pattern exists because thousands of developers before us hit the same wall and figured out how to climb over it. The Factory Pattern exists because object creation gets messy, and centralising that mess into one place makes everything else cleaner.

Start simple, refactor when it hurts. I'm not saying you should use the Factory Pattern everywhere from day one. If you're building something small with two or three types, direct instantiation is fine. But pay attention to the warning signs: duplicated creation logic, fear of adding new types, bugs that keep appearing in the same places. When you feel that pain, that's when patterns become your friend.

The Registry Pattern is underrated. Combining Factory with Registry gave me something I didn't expect, the ability to extend the system without touching existing code. That's not just convenient; it's liberating. New requirements stopped feeling like a burden and started feeling like opportunities.

Rust makes this elegant. Traits, Arc, match expressions, Rust's type system practically guides you toward clean factory implementations. The compiler catches mistakes that would have been runtime bugs in other languages. If you're coming from a dynamically typed background, lean into Rust's strictness. It's not fighting you; it's protecting you.

Looking back at the document parser API we built together, I'm genuinely proud of how it turned out. It's not over-engineered. It's not clever for the sake of being clever. It's just... clean. And clean code is code you can hand off to someone else without writing a novel of documentation. It's code you can come back to six months later and actually understand.

If you've made it this far, thank you for reading. I hope Sam's story resonated with you, and I hope the next time you find yourself drowning in if-else chains, you'll remember there's a better way.

Now go build something. And when it gets messy, because it will, you'll know what to do.

Meet Bob. Two months ago, they joined a fast-growing data analytics startup as a backend developer. The company's main product is a data warehouse API that lets customers query massive datasets. Bob's job? Build a client library that makes it easy to interact with this API.

Sounds simple, right? Not quite.

It's 2:47 PM on a Tuesday. Bob stares at the screen, eyes twitching. The code review comments just came in:

"This is unreadable. I have no idea which parameter is which. Also, you forgot to set the timeout on line 47, causing a production incident."

The Current Code (The Mess)

Here's what Bob has been dealing with:

// The current API request builder - not pretty.
let request = WarehouseRequest {
    endpoint: "reports".to_string(),
    method: HttpMethod::GET,
    query_params: Some(query_params),
    headers: None,
    body: None,
    auth: AuthType::Bearer("token".into()),
    timeout_seconds: Some(30),
    retry_count: Some(3),
    cache_results: true,
};

// Creating a POST request - even worse.
let request = WarehouseRequest {
    endpoint: "analytics/query".to_string(),
    method: HttpMethod::POST,
    query_params: None,
    headers: Some(headers),
    body: Some(body_params), // Can be a huge JSON written inline here.
    auth: AuthType::Bearer("token".into()),
    timeout_seconds: None,
    retry_count: None,
    cache_results: false,
};

// A week later, Bob can't remember which field is which...
let request = WarehouseRequest {
    endpoint: "users".to_string(),
    method: HttpMethod::GET,
    query_params: Some(params),
    headers: None,
    body: Some(body),
    auth: AuthType::None,
    timeout_seconds: Some(30),
    retry_count: Some(retry),
    cache_results: true,
};

Bob's internal monologue goes something like this:

"Every time I create a request, I spend 5 minutes double-checking the field order. Is it query_params then headers, or headers then body? Why do I need to specify None for fields I don't care about? And the worst part? If I forget a crucial field like timeout_seconds, I only find out when the request hangs forever in production."

The Pain Points

Let's visualise Bob's suffering:

The specific problems:

1. Parameter Soup: 9 fields, most are Option<T> - which ones are required?

2. No Guidance: No hints about what's required versus optional.

3. Order Matters: Struct fields must be in exact order.

4. Easy to Forget: Miss one field? Runtime error or silent failure.

5. No Validation: Can set contradictory values. (GET with body)

6. Unreadable Code: Looking at the code, can you tell what it does?

// Quick! What does this request do?
let request = WarehouseRequest {
    endpoint: "data".to_string(),
    method: HttpMethod::POST,
    query_params: None,
    headers: None,
    body: Some(serde_json::json!({"query": "SELECT *"})),
    auth: AuthType::None,
    timeout_seconds: None,
    retry_count: None,
    cache_results: false,
};

// Answer: Creates an analytics query without auth, timeout, or retry.
// But you had to READ EVERY SINGLE LINE to figure that out!

Most requests don't need headers, custom timeouts, or retry logic. But you still have to write headers: None, timeout_seconds: None, retry_count: None for every single request. A simple GET request that only needs an endpoint ends up being 9 lines of code, with 6 of those lines just saying "I don't need this." This bloats the codebase and makes every request harder to read and maintain.

The Constructor Chaos

Let's break down why Bob's code is such a nightmare.

Positional Parameters

When constructors take many parameters in a specific order, reading the code becomes a guessing game. You see values like None, Some(30), and true lined up, but without the function signature open in another window, you have no idea what each position represents. This forces developers to constantly jump between files or count commas to understand simple function calls.

// Traditional constructor. (if it existed)
impl WarehouseRequest {
    fn new(
        endpoint: String,
        method: HttpMethod,
        query_params: Option<QueryParams>,
        headers: Option<Headers>,
        body: Option<BodyParams>,
        auth: AuthType,
        timeout_seconds: Option<u64>,
        retry_count: Option<u32>,
        cache_results: bool,
    ) -> Self {
        Self {
            endpoint,
            method,
            query_params,
            headers,
            body,
            auth,
            timeout_seconds,
            retry_count,
            cache_results,
        }
    }
}

// Using it:
let request = WarehouseRequest::new(
    "reports".to_string(),
    HttpMethod::GET,
    Some(params),
    None,  // Which field is this?
    None,  // And this?
    AuthType::Bearer("token".into()),
    Some(30),  // Wait, timeout or retry?
    Some(3),   // Definitely lost now.
    true,
);

Nobody can read this! You need to count parameters and cross-reference with the function signature.

Optional Field Explosion

With six optional fields, there are 64 mathematically possible combinations of which fields to set. In practice, nobody knows which combinations make sense for their use case. Should a GET request have retry logic? Does caching require authentication? Without clear patterns, every developer creates requests differently, leading to inconsistent code across the codebase and making it impossible to establish best practices.

With 9 fields and 6 optional, that's 2^6 = 64 possible combinations!

// All these are valid, but which is correct?
let r1 = WarehouseRequest { /* all None */ };
let r2 = WarehouseRequest { /* only timeout */ };
let r3 = WarehouseRequest { /* timeout + retry */ };
let r4 = WarehouseRequest { /* timeout + retry + headers */ };
// ... 60 more combinations!

No Compile-Time Guarantees

The struct accepts any values that match the types, even when those values make no sense. An empty endpoint, a POST request without a body, or a timeout of zero seconds all compile successfully. The type system can't encode business rules, so invalid states slip through compilation and only surface as runtime errors in production when real users are affected.

// This compiles fine but crashes at runtime!
let request = WarehouseRequest {
    endpoint: "".to_string(),  // Empty endpoint!
    method: HttpMethod::POST,
    query_params: None,
    headers: None,
    body: None,  // POST without body!
    auth: AuthType::None,
    timeout_seconds: Some(0),  // Zero timeout!
    retry_count: Some(100),    // 100 retries!
    cache_results: true,
};

// Runtime: BOOM!

The compiler is happy, but the code is broken.

The Real-World Impact

These aren't just theoretical problems. Bob's production logs show the real cost: hung requests from missing timeouts, failed operations from forgotten retry logic, and support tickets from malformed requests. Each incident means frustrated users, emergency debugging sessions, and post-mortems. The current approach isn't just inconvenient; it's actively causing business problems that could be prevented with better API design.

Bob keeps a log of production incidents:

Week 1: Forgot to set timeout → Request hung for 10 minutes → User complained.
Week 2: Set body on GET request → 400 Bad Request → Monitoring alerted.
Week 3: Typo in endpoint ("repots" instead of "reports") → 404 → Support ticket.
Week 4: Forgot retry_count → Single network blip caused failure → Data loss.
Week 5: Set timeout to 0 → Instant timeout on all requests → Service down.

The Breaking Point

Friday afternoon. Bob's manager, Casey, schedules a code review.

"Bob, we need to talk about the API client code."

Bob, a bit defensive: "I know it's not perfect, but it works!"

Casey pulls up the screen: "Does it? Look at this production log from yesterday."

[ERROR] Request to warehouse failed: timeout after 0ms
[ERROR] Endpoint '' not found (404)
[ERROR] POST request to /reports missing required body
[ERROR] Invalid retry count: 255

"All of these are from your client library. The warehouse API is fine. It's how we're calling it."

"But... I tested all these requests locally!"

"Did you test every possible combination of optional parameters? All 64 of them?"

Silence.

"Look, I'm not blaming you. The API is hard to use. But we need a better solution. Have you heard of the Builder Pattern?"

"Builder? Like... building things?"

"Sort of. It's a design pattern that makes constructing complex objects easier. Instead of this..."

Builder is a creational design pattern that lets you construct complex objects step by step. The pattern allows you to produce different types and representations of an object using the same construction code.

Casey points at the screen:

let request = WarehouseRequest {
    endpoint: "reports".to_string(),
    method: HttpMethod::GET,
    query_params: Some(params),
    headers: None,
    body: None,
    auth: AuthType::Bearer("token".into()),
    timeout_seconds: Some(30),
    retry_count: Some(3),
    cache_results: true,
};

"...we could have this:"

let request = WarehouseQueryBuilder::new()
    .endpoint("reports")
    .query_params(params)
    .bearer_auth("token")
    .timeout(30)
    .retry(3)
    .cache(true)
    .build()?;

Bob's eyes widen: "That's... actually readable! I can tell exactly what it's doing!"

"And check this out - in Rust, we can use the type system to enforce that required fields are set at compile time. If you forget the endpoint, it won't even compile."

"No more runtime errors for missing fields?"

"Exactly. Let me show you how it works."

Enter the Builder Pattern

Casey pulls up a browser and starts sketching on the whiteboard.

"The Builder Pattern separates the construction of a complex object from its representation. Think of it like building a house."

Casey draws:

Building a House:

WITHOUT Builder:
House(foundation, walls, roof, windows, doors, plumbing, electrical, ...)
↑ All at once, in exact order, can't skip any

WITH Builder:
HouseBuilder()
  .foundation(concrete)
  .walls(brick)
  .roof(tile)
  .plumbing(copper)
  .build()
↑ Step by step, any order, skip optional parts

"The key benefits are:"

1. Readability: Each method call is self-documenting

2. Flexibility: Set parameters in any order

3. Optional Parameters: Only set what you need

4. Validation: Check correctness before building

5. Immutability: Builder is consumed, final object is immutable

"So instead of one massive constructor, we have many small methods that each set one thing?"

"Exactly! And in Rust, we can make it even better with the type-state pattern."

The Type-State Pattern

The type-state pattern is Rust's secret weapon for catching bugs at compile time. It uses generic type parameters to track what state an object is in, then uses the type system to control which methods are available in each state. This means the compiler can enforce that you must set required fields before building the final object. Unlike runtime validation that checks for errors when the code runs, type-state validation happens during compilation, making entire classes of bugs impossible.

Casey draws another diagram:

Type-State Pattern (Compile-time guarantees):

State 1: NoEndpoint
  ↓ .endpoint("reports")
State 2: HasEndpoint
  ↓ .query_param(...), .timeout(...), etc.
State 3: ReadyToBuild
  ↓ .build()
Final: WarehouseRequest

Rules enforced by TYPE SYSTEM:
- Can only call .build() in HasEndpoint state
- Can't build without setting endpoint
- Compiler catches mistakes!

"Wait, so if I forget to set the endpoint, the code won't even compile?"

"Right! The compiler will say 'build() doesn't exist for WarehouseQueryBuilder'"

"That's amazing! So many of our production bugs would be caught at compile time!"

"Exactly. Ready to implement it?"

"Let's do this!"

What is Builder Pattern?

The Core Idea

Instead of this:

Create object with all parameters at once
↓
Hope everything is correct
↓
Runtime errors if something wrong

We do this:

Create builder
↓
Set parameters one by one (fluent API)
↓
Validate
↓
Build final object

UML Diagram

Comparison

Traditional Constructor:

// Hard to read, easy to mess up.
let request = WarehouseRequest::new(
    "reports",
    HttpMethod::GET,
    Some(params),
    None,
    None,
    AuthType::Bearer("token".into()),
    Some(30),
    Some(3),
    true
);

Builder Pattern:

// Clear, self-documenting, flexible.
let request = WarehouseQueryBuilder::new()
    .endpoint("reports")
    .method(HttpMethod::GET)
    .query_params(params)
    .bearer_auth("token")
    .timeout(30)
    .retry(3)
    .cache(true)
    .build()?;

Key Differences:

Rust's Type-State Pattern

Casey continues: "Now here's where Rust really shines. We can use the type system to track the builder's state and enforce rules at compile time."

The Problem with Simple Builders

// Simple builder (WITHOUT type-state)
let request = WarehouseQueryBuilder::new()
    .timeout(30)
    .retry(3)
    .build()?;  // Runtime error: missing endpoint!

This compiles fine, but crashes at runtime when we call build().

The Type-State Solution

// Type-state builder.
let request = WarehouseQueryBuilder::new()  // Type: Builder<NoEndpoint>
    .timeout(30)
    .retry(3)
    .build();  // COMPILE ERROR: build() doesn't exist!

// Correct usage:
let request = WarehouseQueryBuilder::new()  // Type: Builder<NoEndpoint>
    .endpoint("reports")                     // Type: Builder<HasEndpoint>
    .timeout(30)
    .retry(3)
    .build()?;  // OK! build() exists for HasEndpoint.

How It Works

Phantom Types

use std::marker::PhantomData;

// Define marker traits for states.
trait EndpointState {}
struct NoEndpoint;
struct HasEndpoint;

impl EndpointState for NoEndpoint {}
impl EndpointState for HasEndpoint {}

// Builder is generic over state.
struct WarehouseQueryBuilder<E: EndpointState> {
    endpoint: Option<String>,
    // ... other fields ...
    _endpoint_state: PhantomData<E>,  // Zero-cost type marker.
}

What is PhantomData?

PhantomData<E> is a special zero-sized type in Rust. It doesn't take up any memory at runtime, but it carries type information that the compiler uses to enforce rules. Think of it as a compile-time flag that costs nothing in performance but gives us compile-time safety.

Why do we need it?

Without PhantomData, the compiler would complain that the generic type parameter E is unused. PhantomData<E> tells the compiler "I'm intentionally using this type parameter for compile-time type checking, even though it doesn't appear in any fields."

"So it's like a compile-time flag?" Bob asks.

"Exactly! It costs nothing at runtime, but gives us compile-time safety."

Method Availability Based on State

impl WarehouseQueryBuilder<NoEndpoint> {
    // Only available in NoEndpoint state.
    fn new() -> Self { ... }

    // Transitions to HasEndpoint state.
    fn endpoint(self, endpoint: String) -> WarehouseQueryBuilder<HasEndpoint> {
        WarehouseQueryBuilder {
            endpoint: Some(endpoint),
            // ... transfer other fields ...
            _endpoint_state: PhantomData,  // New state!
        }
    }
}

impl WarehouseQueryBuilder<HasEndpoint> {
    // Only available in HasEndpoint state.
    fn method(mut self, method: HttpMethod) -> Self { ... }
    fn timeout(mut self, seconds: u64) -> Self { ... }
    fn retry(mut self, count: u32) -> Self { ... }

    // Only HasEndpoint can build!
    fn build(self) -> Result<WarehouseRequest, BuildError> { ... }
}

Understanding Ownership and self

Notice that endpoint() takes self (not &self or &mut self). This means it consumes the builder - takes ownership of it. It then returns a new builder in a different state. This is key to the type-state pattern!

For the other methods like timeout(), we use mut self, which also takes ownership, modifies the builder, and returns it. This enables method chaining.

"Oh! So .build() literally doesn't exist until you've set the endpoint. The compiler won't even let you call it!"

"Bingo! This is the power of Rust's type system. Entire categories of bugs are prevented at compile time."

Compile-Time Error Examples

// COMPILE ERROR: build() doesn't exist for NoEndpoint.
let request = WarehouseQueryBuilder::new()
    .timeout(30)
    .build();

// Compiler says:
// error[E0599]: no method named `build` found for struct.
// `WarehouseQueryBuilder<NoEndpoint>`

// COMPILE ERROR: endpoint() doesn't exist for HasEndpoint.
let request = WarehouseQueryBuilder::new()
    .endpoint("reports")
    .endpoint("users")  // Can't set endpoint twice!
    .build();

// Compiler says:
// error[E0599]: no method named `endpoint` found for struct.
// `WarehouseQueryBuilder<HasEndpoint>`

Bob is amazed: "This is incredible! The compiler is like a super-strict code reviewer that never gets tired!"

The Solution

Now comes the fun part - actually building the type-safe builder. We'll walk through each step incrementally, starting with basic Rust structs and gradually adding the type-state pattern. This isn't just theory; we'll write real, working code that you can compile and run. By the end, you'll understand not just what the builder pattern is, but how to implement it in Rust using advanced type system features that make invalid states unrepresentable at compile time.

"Alright," Bob says, cracking knuckles. "Let's build this thing!"

Project Setup

cargo new warehouse-query-api
cd warehouse-query-api

Update Cargo.toml:

[package]
name = "warehouse-query-api"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tower = "0.4"
tower-http = { version = "0.5", features = ["cors"] }
chrono = { version = "0.4", features = ["serde"] }
reqwest = { version = "0.11", features = ["json"] }
thiserror = "1.0"

About the dependencies:

• axum: Web framework for building the HTTP API

• tokio: Async runtime (required by axum)

• serde & serde_json: Serialization / deserialization

• tower & tower-http: Middleware support

• chrono: Date/time handling

• reqwest: HTTP client for making requests

• thiserror: Easy error type creation

Define the Target Struct

Create src/models.rs:

//! Core data models for the Warehouse Query API.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// HTTP methods supported by the API.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum HttpMethod {
    GET,
    POST,
    PUT,
    DELETE,
    PATCH,
}

/// Authentication mechanisms.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AuthType {
    None,
    Bearer(String),
    ApiKey(String),
    Basic { username: String, password: String },
}

pub type QueryParams = HashMap<String, String>;
pub type Headers = HashMap<String, String>;
pub type BodyParams = serde_json::Value;

// ...

/// Request payload for building a query.
#[derive(Debug, Deserialize)]
pub struct BuildQueryRequest {
    pub endpoint: String,
    pub method: Option<String>,
    pub query_params: Option<QueryParams>,
    pub headers: Option<Headers>,
    pub body: Option<BodyParams>,
    pub auth_token: Option<String>,
    pub timeout_seconds: Option<u64>,
    pub retry_count: Option<u32>,
    pub cache_results: Option<bool>,
}

/// Response containing the built query.
#[derive(Debug, Serialize)]
pub struct BuildQueryResponse {
    pub request: WarehouseRequest,
    pub message: String,
}

Understanding the derives:

• Debug: Allows printing the struct with {:?} for debugging

• Clone: Allows creating copies of the struct

• Serialize: Converts struct to JSON (via serde)

• Deserialize: Converts JSON to struct (via serde)

Bob's note: "This is what we're trying to build. 9 fields, 6 optional. Perfect candidate for a builder!"

Define State Markers

Create src/query_builder.rs:

use std::marker::PhantomData;

/// Marker trait for endpoint state.
pub trait EndpointState {}

/// State: No endpoint set yet.
pub struct NoEndpoint;

/// State: Endpoint has been set.
pub struct HasEndpoint;

impl EndpointState for NoEndpoint {}
impl EndpointState for HasEndpoint {}

Casey: "These are our type-level states. They exist only at compile time - zero runtime cost!"

What are marker traits?

Marker traits are traits with no methods. They're used purely for compile-time type checking. EndpointState is a marker trait that both NoEndpoint and HasEndpoint implement, allowing us to constrain our builder to only accept types that represent endpoint states.

Create the Builder Struct

/// The Builder.
pub struct WarehouseQueryBuilder<E: EndpointState> {
    endpoint: Option<String>,
    method: HttpMethod,
    query_params: Option<QueryParams>,
    headers: Option<Headers>,
    body: Option<BodyParams>,
    auth: AuthType,
    timeout_seconds: Option<u64>,
    retry_count: Option<u32>,
    cache_results: bool,
    _endpoint_state: PhantomData<E>,  // Type-level state marker.
}

Bob: "So the builder holds all the same fields as WarehouseRequest, plus a phantom type for state tracking."

Implement Initial State (NoEndpoint)

impl WarehouseQueryBuilder<NoEndpoint> {
    /// Create a new builder.
    ///
    /// Starts in NoEndpoint state.
    pub fn new() -> Self {
        Self {
            endpoint: None,
            method: HttpMethod::GET,  // Sensible default.
            query_params: None,
            headers: None,
            body: None,
            auth: AuthType::None,
            timeout_seconds: None,
            retry_count: None,
            cache_results: false,
            _endpoint_state: PhantomData,
        }
    }

    /// Set the endpoint. (REQUIRED)
    ///
    /// This transitions from NoEndpoint to HasEndpoint state.
    pub fn endpoint(self, endpoint: impl Into<String>) -> WarehouseQueryBuilder<HasEndpoint> {
        WarehouseQueryBuilder {
            endpoint: Some(endpoint.into()),
            method: self.method,
            query_params: self.query_params,
            headers: self.headers,
            body: self.body,
            auth: self.auth,
            timeout_seconds: self.timeout_seconds,
            retry_count: self.retry_count,
            cache_results: self.cache_results,
            _endpoint_state: PhantomData,  // New state!
        }
    }
}

What is impl Into<String>?

This is a trait bound that accepts anything that can be converted into a String. This includes &str, String, and other types. It makes the API more flexible - users can pass "reports" (a string slice) instead of "reports".to_string().

Key insight: The endpoint() method consumes self (takes ownership) and returns a builder in a different state!

Implement Builder Methods (HasEndpoint)

impl WarehouseQueryBuilder<HasEndpoint> {
    /// Set HTTP method.
    pub fn method(mut self, method: HttpMethod) -> Self {
        self.method = method;
        self
    }

    /// Set query parameters.
    pub fn query_params(mut self, params: QueryParams) -> Self {
        self.query_params = Some(params);
        self
    }

    /// Add a single query parameter.
    pub fn query_param(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        let mut params = self.query_params.unwrap_or_default();
        params.insert(key.into(), value.into());
        self.query_params = Some(params);
        self
    }

    /// Set headers.
    pub fn headers(mut self, headers: Headers) -> Self {
        self.headers = Some(headers);
        self
    }

    /// Add a single header.
    pub fn header(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        let mut headers = self.headers.unwrap_or_default();
        headers.insert(key.into(), value.into());
        self.headers = Some(headers);
        self
    }

    /// Set request body.
    pub fn body(mut self, body: BodyParams) -> Self {
        self.body = Some(body);
        self
    }

    /// Set bearer token authentication.
    pub fn bearer_auth(mut self, token: impl Into<String>) -> Self {
        self.auth = AuthType::Bearer(token.into());
        self
    }

    /// Set timeout in seconds.
    pub fn timeout(mut self, seconds: u64) -> Self {
        self.timeout_seconds = Some(seconds);
        self
    }

    /// Set retry count.
    pub fn retry(mut self, count: u32) -> Self {
        self.retry_count = Some(count);
        self
    }

    /// Enable result caching.
    pub fn cache(mut self, enabled: bool) -> Self {
        self.cache_results = enabled;
        self
    }
}

Bob: "Each method takes mut self, modifies it, and returns self. That's the 'fluent API' pattern!"

Casey: "Right! It enables method chaining: .timeout(30).retry(3).cache(true)"

Understanding mut self:

When we write mut self, we're taking ownership of self and declaring we can mutate it. After modifying the builder, we return it so the next method in the chain can use it. This is different from &mut self, which would borrow the builder mutably but not consume it.

Implement build() Method

/// Build errors.
#[derive(Debug, thiserror::Error)]
pub enum BuildError {
    #[error("Endpoint cannot be empty")]
    EmptyEndpoint,

    #[error("Body is required for POST/PUT/PATCH requests")]
    MissingBody,

    #[error("Invalid JSON body: {0}")]
    InvalidJson(#[from] serde_json::Error),
}

impl WarehouseQueryBuilder<HasEndpoint> {
    /// Build the final WarehouseRequest.
    ///
    /// This method is ONLY available in HasEndpoint state!
    pub fn build(self) -> Result<WarehouseRequest, BuildError> {
        // Validation.
        if let Some(ref endpoint) = self.endpoint {
            if endpoint.is_empty() {
                return Err(BuildError::EmptyEndpoint);
            }
        }

        // Method-specific validation.
        match self.method {
            HttpMethod::POST | HttpMethod::PUT | HttpMethod::PATCH => {
                if self.body.is_none() {
                    return Err(BuildError::MissingBody);
                }
            }
            _ => {}
        }

        Ok(WarehouseRequest {
            endpoint: self.endpoint.unwrap(), // Safe! Type system guarantees it's Some.
            method: self.method,
            query_params: self.query_params,
            headers: self.headers,
            body: self.body,
            auth: self.auth,
            timeout_seconds: self.timeout_seconds,
            retry_count: self.retry_count,
            cache_results: self.cache_results,
        })
    }
}

Understanding Result<T, E>:

Result is Rust's way of handling operations that might fail. Result<WarehouseRequest, BuildError> means the function either returns a WarehouseRequest (wrapped in Ok) or a BuildError (wrapped in Err). The ? operator can be used to propagate errors up the call stack.

Understanding thiserror:

The thiserror crate makes it easy to create custom error types. The #[error(...)] attribute defines the error message, and #[from] automatically implements conversion from other error types (like serde_json::Error).

Bob is excited: "Look! The unwrap() on endpoint is safe because the type system guarantees it's Some. We're in HasEndpoint state, which means .endpoint() was called!"

Casey: "Exactly! No runtime panic possible here. The type system has our back."

Add Preset Builders (Bonus!)

impl WarehouseQueryBuilder<NoEndpoint> {
    /// Preset for fetching reports. (GET request)
    pub fn fetch_reports() -> WarehouseQueryBuilder<HasEndpoint> {
        WarehouseQueryBuilder::new()
            .endpoint("reports")
            .method(HttpMethod::GET)
            .cache(true)
    }

    /// Preset for creating a report. (POST request)
    pub fn create_report() -> WarehouseQueryBuilder<HasEndpoint> {
        WarehouseQueryBuilder::new()
            .endpoint("reports")
            .method(HttpMethod::POST)
            .header("Content-Type", "application/json")
    }

    /// Preset for analytics query.
    pub fn analytics_query() -> WarehouseQueryBuilder<HasEndpoint> {
        WarehouseQueryBuilder::new()
            .endpoint("analytics/query")
            .method(HttpMethod::POST)
            .timeout(300)  // Long-running queries.
            .retry(3)
    }
}

Bob: "These are awesome! Common patterns pre-configured. Users can just call fetch_reports() and customise from there!"

Usage Examples

// Example 1: Simple GET request.
let request = WarehouseQueryBuilder::new()
    .endpoint("reports")
    .build()?;

// Example 2: GET with query params and auth.
let request = WarehouseQueryBuilder::new()
    .endpoint("users")
    .query_param("limit", "10")
    .query_param("offset", "0")
    .bearer_auth("my-token")
    .build()?;

// Example 3: POST with body.
let body = serde_json::json!({
    "query": "SELECT * FROM sales WHERE year = 2024"
});
let request = WarehouseQueryBuilder::new()
    .endpoint("analytics/query")
    .method(HttpMethod::POST)
    .body(body)
    .bearer_auth("my-token")
    .timeout(300)
    .retry(3)
    .build()?;

// Example 4: Using a preset.
let request = WarehouseQueryBuilder::fetch_reports()
    .query_param("limit", "20")
    .bearer_auth("my-token")
    .build()?;

The Complete Implementation

Let's see how everything fits together in the API.

The Warehouse Client

Create src/warehouse_client.rs:

use crate::models::*;
use crate::query_builder::WarehouseQueryBuilder;

/// Client for executing warehouse API requests.
pub struct WarehouseClient {
    base_url: String,
}

impl WarehouseClient {
    pub fn new(base_url: impl Into<String>) -> Self {
        Self {
            base_url: base_url.into(),
        }
    }

    /// Execute a warehouse request.
    pub async fn execute(&self, request: WarehouseRequest) -> Result<WarehouseResponse, String> {
        println!("Executing warehouse request:");
        println!("   URL: {}/{}", self.base_url, request.endpoint);
        println!("   Method: {:?}", request.method);

        if let Some(ref params) = request.query_params {
            println!("   Query Params: {:?}", params);
        }

        // Simulate response.
        let response_data = serde_json::json!({
            "success": true,
            "data": {
                "reports": [
                    {"id": 1, "name": "Sales Report Q1"},
                    {"id": 2, "name": "Sales Report Q2"}
                ],
                "total": 2
            }
        });

        Ok(WarehouseResponse {
            status: 200,
            data: response_data,
            cached: request.cache_results,
            execution_time_ms: 150,
        })
    }

    /// Convenience method: Fetch reports with pagination.
    pub async fn fetch_reports(&self, limit: u32, offset: u32) -> Result<WarehouseResponse, String> {
        // Look how clean this is!
        let request = WarehouseQueryBuilder::fetch_reports()
            .query_param("limit", limit.to_string())
            .query_param("offset", offset.to_string())
            .bearer_auth("demo-token")
            .build()
            .map_err(|e| e.to_string())?;

        self.execute(request).await
    }
}

Understanding async and .await:

In Rust, async functions return a Future that must be .awaited to execute. This enables efficient concurrent I/O operations. When you call an async function, it doesn't execute immediately - you need to .await it.

Bob: "Look how readable fetch_reports() is now! Before, it was 20 lines of struct initialization. Now it's 5 lines of fluent API calls!"

Testing Our Builder

Running the Server

cargo run

Output:

Starting Warehouse Query API...

Warehouse Query API running on http://127.0.0.1:3000

API Endpoints:
   POST   /query/build    - Build a warehouse query
   POST   /query/execute  - Build and execute a query
   GET    /query/examples - Get example queries
   GET    /health         - Health check

Using Builder Pattern for flexible query construction!

Simple GET Request

curl -X POST http://localhost:3000/query/build \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "reports",
    "method": "GET",
    "cache_results": true
  }'

Response:

{
  "request": {
    "endpoint": "reports",
    "method": "GET",
    "query_params": null,
    "headers": null,
    "body": null,
    "auth": "None",
    "timeout_seconds": null,
    "retry_count": null,
    "cache_results": true
  },
  "message": "Query built successfully using builder pattern"
}

Clean and simple! Only specified what we needed.

POST with All Options

curl -X POST http://localhost:3000/query/build \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "analytics/query",
    "method": "POST",
    "body": {
      "query": "SELECT * FROM sales WHERE year = 2024"
    },
    "auth_token": "secret-token-123",
    "timeout_seconds": 300,
    "retry_count": 3,
    "cache_results": false
  }'

Response:

{
  "request": {
    "endpoint": "analytics/query",
    "method": "POST",
    "query_params": null,
    "headers": null,
    "body": {
      "query": "SELECT * FROM sales WHERE year = 2024"
    },
    "auth": {
      "Bearer": "secret-token-123"
    },
    "timeout_seconds": 300,
    "retry_count": 3,
    "cache_results": false
  },
  "message": "Query built successfully using builder pattern"
}

Perfect! All options set clearly.

Validation (Missing Body)

curl -X POST http://localhost:3000/query/build \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "reports",
    "method": "POST"
  }'

Response:

Status: 400 Bad Request

Validation works! POST request without body is rejected.

The Resolution

Monday Morning Code Review

Bob submits the pull request with the new builder pattern implementation. Casey reviews it immediately.

Casey is impressed: "Bob, this is excellent work! Look at the diff stats:"

Files changed:
src/query_builder.rs: +350 lines (new)
src/warehouse_client.rs: -120 lines, +45 lines
src/handlers.rs: -80 lines, +60 lines
tests/: +150 lines (new tests)
Overall: -200 lines of messy code, +400 lines of clean, type-safe code

"But more importantly, look at the usage:"

Before:

let request = WarehouseRequest {
    endpoint: "analytics/query".to_string(),
    method: HttpMethod::POST,
    query_params: None,
    headers: Some(headers),
    body: Some(serde_json::json!({"query": query_string})),
    auth: AuthType::Bearer(token.clone()),
    timeout_seconds: Some(300),
    retry_count: Some(3),
    cache_results: false,
};

After:

let request = WarehouseQueryBuilder::analytics_query()
    .body(serde_json::json!({"query": query_string}))
    .bearer_auth(token)
    .build()?;

"From 11 lines to 4 lines. And infinitely more readable!"

Team Adoption

The rest of the team starts using the builder. The results are immediate:

Week 1:

• 5 pull requests updated to use builder

• 0 production incidents (down from 3-5 per week)

• Code review time cut in half

Week 2:

• Junior developer Sarah: "I just built my first warehouse query. Took 5 minutes. The fluent API told me exactly what I needed!"

• Senior developer Marcus: "The type-state pattern caught 3 bugs in my code before I even ran it. Compiler is our best QA!"

Week 3:

• Support team: "We haven't had a single 'malformed request' ticket this week!"

• DevOps: "Error rates down 80%"

Metrics Comparison

Bob's Reflection

Bob writes in the team Slack:

"Team update: The builder pattern has been a game-changer.

Before: I dreaded creating warehouse requests. Every time was a minefield of potential bugs.

After: I actually enjoy it! The fluent API guides me, the compiler catches my mistakes, and the code reads like English.

My favourite part? Zero-cost abstractions. All that type-safety has ZERO runtime overhead. It's compile-time magic!"

Casey's response:

"Great work Bob! This is what good software engineering looks like:

1. Identify a real problem

2. Apply an appropriate pattern

3. Measure the improvement

4. Share the knowledge

You've made our entire team more productive."

When to Use (and Not Use) Builder Pattern

Use Builder Pattern When:

1. Object has many parameters (5+)

   • Configuration objects

   • API requests/responses

   • Complex domain objects

   • UI component props

2. Many parameters are optional

   • Default values make sense

   • Not all combinations are valid

   • Different use cases need different fields

3. Parameter order is confusing

   • Positional parameters are unclear

   • Multiple parameters of same type

   • Easy to mix up order

4. Immutability is desired

   • Build once, use many times

   • Thread-safe sharing

   • Functional programming style

5. Validation is complex

   • Cross-field validation

   • Business rules

   • Type-state enforcement

6. Fluent API improves readability

   • Code reads like English

   • Self-documenting

   • IDE autocomplete helps

Don't Use Builder Pattern When:

1. Object is simple (1-3 parameters)

// Overkill.
let user = UserBuilder::new()
    .name("Alice")
    .build();

// Better.
let user = User::new("Alice");

2. All parameters are required

// Unnecessary.
let point = PointBuilder::new()
    .x(10.0)
    .y(20.0)
    .build();

// Better.
let point = Point::new(10.0, 20.0);

3. Object is frequently modified

   • Builder creates immutable objects

   • If you need mutation, use direct field access

Conclusion

When I first started working on this warehouse API client, I genuinely thought the problem was me. Every production incident felt like a personal failure - another timeout I forgot to set, another malformed request I should have caught. I kept detailed logs, trying to spot patterns in my mistakes, hoping I'd eventually memorize all the edge cases and stop breaking things.

But the real problem wasn't me. It was the API itself. When you force developers to specify nine fields in exact order, with no guidance about what's required and what's optional, you're not building an API - you're building a minefield. Every request becomes an exercise in careful counting, constant cross-referencing, and hoping you didn't miss anything important.

The builder pattern changed everything. Not because it's clever or elegant, but because it solves real problems that were costing us time, money, and sleep. Type-state builders let the compiler do what compilers do best: catch mistakes before they become production incidents. The code is more readable, yes, but more importantly, it's safer. My junior teammates can write correct requests on their first try because the fluent API guides them. Our error rates dropped not through better discipline, but through better design.

This is what good engineering looks like. Not clever abstractions for their own sake, but practical solutions to concrete problems. The builder pattern isn't perfect for everything, but for complex object construction with validation requirements, it's been transformative. If you're fighting with constructors that have too many parameters or dealing with runtime errors that should be compile-time errors, give builders a try. Your future self will thank you.

Thanks for reading! May your APIs always be fluent!

Written by Bob*, Senior Developer and Builder Pattern enthusiast.*

Meet Jordan. Six months ago, Jordan joined a promising startup called "FastAPI Co." as a DevOps engineer. The company's main product is a high-traffic API service that handles configuration management for thousands of micro-services. At peak times, they process 5,000+ requests per minute.

Everything seemed fine during the first few months. The monitoring metrics looked acceptable, users were happy, and the product was growing. But then came December 20th, 2025.

The Incident

It's 3:17 AM on a cold Friday morning. Jordan's phone vibrates violently on the nightstand, then starts blaring alerts:

🚨 CRITICAL: HIGH MEMORY USAGE: 95% (Threshold: 80%)
🚨 CRITICAL: DATABASE: Too many connections (ERROR 1040)
🚨 WARNING: RESPONSE TIME: 5247ms (Normal: 45-60ms)
🚨 CRITICAL: SERVER CRASH IMMINENT - OOM Killer Active
🚨 ALERT: Error rate: 45% (Normal: <0.1%)

Jordan jolts awake, grabs the laptop with shaking hands, and logs into the monitoring dashboard. The graphs look like a horror movie:

Monitoring Dashboard Snapshot:

• Memory usage: Climbing steadily from 2GB to 7.8GB in 90 minutes

• Database connection pools: 523 active pools!?

• Config file reads: 14,247 in the last hour

• Active database connections: 8,941 (PostgreSQL limit: 100)

• Cache misses: 99.7%

Jordan's internal monologue:

"What the hell is happening? Why are there 523 database connection pools? We should only need ONE! And why is the config file being read 14 THOUSAND times? We have caching, don't we? Why are different parts of the app seeing DIFFERENT configuration values? This doesn't make ANY sense! We're about to hit OOM and the database is rejecting connections... I need to figure this out NOW."

The Current Code

Jordan opens the codebase and starts tracing execution paths. What they find is terrifying:

// ❌ THE PROBLEM CODE - What Jordan inherited.
// This code is scattered across 30+ files!

// In src/database.rs
pub fn connect_to_database() -> DatabaseConnection {
    // PROBLEM 1: Reading config file from disk EVERY TIME!
    let config = read_config_from_file("config.json");

    // PROBLEM 2: Creating a NEW connection pool EVERY TIME!
    let pool = ConnectionPool::new(
        &config.database_url,
        config.max_connections  // Each pool holds 10-50 connections!
    );

    DatabaseConnection { pool }
}

// In src/handlers.rs
async fn handle_api_request(req: Request) -> Response {
    // ANOTHER config read from disk!
    let config = read_config_from_file("config.json");

    // Each request reads config for feature flags.
    if config.enable_feature_x {
        // Process with feature X.
    }

    if config.enable_caching {
        // Check cache... but wait, cache is also initialized per request!
        let cache = Cache::new(config.cache_size);  // NEW CACHE!
    }

    // ... more logic.
}

// In src/logger.rs
pub fn log(level: &str, message: &str) {
    // YET ANOTHER config read!
    let config = read_config_from_file("config.json");

    // Check log level threshold.
    if should_log(level, &config.log_level) {
        // Initialize NEW logger instance!
        let logger = Logger::new(&config.log_file_path);  // NEW LOGGER!
        logger.write(level, message);
    }
}

// In src/middleware/auth.rs
async fn auth_middleware(req: Request, next: Next) -> Response {
    // ANOTHER ONE!
    let config = read_config_from_file("config.json");

    let start = Instant::now();

    let response = next.run(req).await;

    // Check timeout.
    if start.elapsed().as_secs() > config.api_timeout_seconds {
        return timeout_response();
    }

    response
}

// This pattern repeats in 30+ files across the codebase!
// EVERY function that needs configuration creates NEW instances of EVERYTHING!

The Symptoms

Jordan creates a comprehensive diagram to visualise what's actually happening:

The Pain Points:

1. Performance Killer - Repeated Disk I/O

   • What: Config file read from disk on EVERY request

   • Why it's bad: Disk I/O is 100,000x slower than RAM access

   • Impact: Each request wasted 2-6ms just reading config

   • Math: 5,000 requests/min × 4ms = 20,000ms = 20 seconds wasted per minute!

2. Memory Leak - Resource Multiplication

   • What: New database connection pool created for each request

   • Why it's bad: Each pool holds 10-50 database connections

   • Impact: 500 requests = 500 pools = 5,000-25,000 DB connections

   • Math: PostgreSQL default max_connections = 100. We hit that in seconds!

3. Resource Exhaustion - Database Rejection

   • What: Database refuses new connections -3.

   • Why it's bad: Database has a hard limit on connections

   • Impact: Requests start failing with "Too many connections" error

   • Math: After 10-20 requests, database connection limit reached

4. Race Conditions - Inconsistent State

   • What: Config file updated during request processing

   • Why it's bad: Different threads see different configuration

   • Impact: Inconsistent behaviour, hard-to-debug issues

   • Example: Thread A sees max_connections=10, Thread B sees 50

5. Initialisation Storm - Repeated Setup

   • What: Logger, cache, metrics collectors all initialised repeatedly

   • Why it's bad: Initialisation is expensive (allocations, setup)

   • Impact: CPU cycles wasted, memory fragmented

   • Math: 1ms per initialisation × 500 requests = 500ms wasted

The Disaster

Let's break down EXACTLY what's happening at the system level. Understanding the problem deeply is crucial for appreciating why the Singleton pattern is the right solution.

Problem 1: Repeated File I/O (The I/O Bottleneck)

Imagine if every time you wanted to check the time, you had to walk to the library, find a clock on the wall, read it, and walk back. That's essentially what's happening here. The application is reading the configuration file from disk for every single operation that needs config data, instead of keeping it in memory. Disk operations are incredibly slow compared to memory access, we're talking about a difference of 100,000x in speed. This seemingly innocent function call is creating a massive performance bottleneck that compounds with every request.

// This innocent-looking function is called THOUSANDS of times!
fn read_config_from_file(path: &str) -> Config {
    // Step 1: Open file. (syscall to operating system)
    let file = File::open(path).unwrap();  // ~1-2ms

    // Step 2: Create buffered reader.
    let reader = BufReader::new(file);

    // Step 3: Parse JSON. (CPU-intensive)
    serde_json::from_reader(reader).unwrap()  // ~0.5-1ms
}

What's actually happening under the hood:

Performance Reality Check:

Multiplication Effect:

• 1 request: ~2ms for config (acceptable)

• 100 requests: ~200ms wasted (noticeable)

• 1,000 requests: ~2 seconds wasted (bad)

• 5,000 requests/min: ~10 seconds wasted per minute (catastrophic!)

Memory Impact:

// Each config read allocates memory:
struct Config {
    server_host: String,        // 24 bytes + heap allocation.
    server_port: u16,           // 2 bytes.
    database_url: String,       // 24 bytes + heap allocation.
    max_connections: u32,       // 4 bytes.
    log_level: String,          // 24 bytes + heap allocation.
    // ... more fields.
}

// Total: ~150-200 bytes per Config instance.
// 5,000 requests × 200 bytes = 1MB just for config copies!
// But wait... each config is cloned in multiple places!
// Real impact: 5-10 MB wasted memory per minute.

Problem 2: Resource Multiplication

This is where things get truly catastrophic. Every time a request needs database access, it creates a brand new connection pool. Think of it like building an entire new highway system every time a single car wants to travel somewhere. Each connection pool maintains multiple active TCP connections to the database, consuming memory and holding valuable database connection slots. With hundreds of concurrent requests, we're creating hundreds of pools, thousands of connections, and exhausting both our server's memory and the database's connection limit. The database eventually says "no more!" and starts rejecting connections, causing a cascade of failures.

// Every request creates a NEW connection pool!
pub struct DatabaseConnection {
    pool: ConnectionPool,  // This is the killer.
}

pub struct ConnectionPool {
    connections: Vec<Connection>,  // Holds 10-50 actual TCP connections!
    url: String,
    max_size: u32,
}

Visual representation of resource multiplication:

Database Connection States:

Problem 3: Inconsistent State (The Race Condition)

When multiple threads are reading the configuration file independently, they can end up with different versions of the config at the same time. This is like having a company where the sales team is looking at last month's price list while the support team is looking at this month's updated prices! If an administrator updates the config file while the application is running, some threads will see the old values while others see the new ones. This creates unpredictable behavior that's extremely difficult to debug because it only happens under specific timing conditions.

// Scenario: Sys admin updates config while app is running.

// Timeline:
// T=0: config.json contains: { "max_connections": 10 }

// T=1: Thread 1 starts processing request
let config = read_config_from_file("config.json");
// Thread 1 sees: max_connections = 10

// T=2: Sys admin updates config.json
// New content: { "max_connections": 50 }

// T=3: Thread 2 starts processing request
let config = read_config_from_file("config.json");
// Thread 2 sees: max_connections = 50

// T=4: Thread 1 creates database connection with max=10
let db1 = DatabaseConnection::new(&config.database_url, 10);

// T=5: Thread 2 creates database connection with max=50
let db2 = DatabaseConnection::new(&config.database_url, 50);

// PROBLEM: Two different configurations in the same running application!
// This leads to:
// - Unpredictable behavior
// - Hard-to-reproduce bugs
// - Inconsistent resource limits
// - Data race conditions

Visual timeline of the race condition:

Problem 4: The Memory Usage Graph

Numbers and code are important, but sometimes a graph tells the story best. When Jordan pulled up the monitoring dashboard, the memory usage graph painted a terrifying picture: a steady, relentless climb from normal operating levels to near-crash conditions in just under two hours. This isn't a memory leak in the traditional sense, the memory is technically being used, but it's being wasted on thousands of duplicate instances of objects that should exist only once. The graph shows the inevitable trajectory toward system failure, with memory consumption accelerating as traffic increases.

Jordan pulls up the actual monitoring dashboard and exports the data:

Jordan's realisation:

"Oh my god. We're not reusing ANYTHING! Every single request creates new instances of everything. We have 523 connection pools when we should have ONE. We have 892 logger instances when we should have ONE. We have 456 cache instances when we should have ONE!

The actual application data - the stuff users care about - is only 10% of our memory usage. The other 90% is completely wasted duplication.

We need ONE config, ONE logger, ONE connection pool, ONE cache manager. Everything should be shared safely across all requests. But how do we do that in Rust?"

The Breaking Point

Monday morning, 9:00 AM. The post-incident review meeting. The atmosphere is tense.

Attendees:

• Maria (CTO)

• Alex (Senior Backend Engineer)

• Jordan (DevOps Engineer - looking exhausted)

• Sarah (Product Manager)

• Mike (Database Administrator)

Maria (pulling up crash reports): "Alright team. Let's break down what happened Friday night. Jordan, can you walk us through the incident?"

Jordan (opening laptop, screen showing monitoring graphs): "At 3:17 AM, we had a catastrophic failure. Memory usage went from normal 2GB to 7.8GB in 90 minutes. The database started rejecting connections. Response times went from 50ms to over 5 seconds. The system crashed at 3:42 AM."

Mike (database admin, frustrated): "I was getting alerts about too many connections. We have a limit of 100 concurrent connections. But I was seeing connection attempts in the thousands! How is that even possible?"

Jordan (pulling up code): "I traced through the codebase. Every single request creates a new database connection pool. Each pool tries to establish 10 connections. So after just 10-20 requests, we hit the database limit."

Alex (leaning forward): "Wait, what? Show me the code."

Jordan (sharing screen):

// This is in our request handler.
async fn handle_request(req: Request) -> Response {
    let config = read_config_from_file("config.json");
    let db = DatabaseConnection::new(&config);  // Creates NEW pool!
    // ...
}

Alex (eyes widening): "Oh no. OH NO. Are we reading the config file on every request?"

Jordan (nodding grimly): "Not just every request. Every FUNCTION that needs config. I counted 30+ places in the codebase. We're reading that file thousands of times per minute."

Sarah (confused): "But... why doesn't it just use the same config? Can't we just... keep it in memory?"

Alex: "We can and we should! What we're seeing here is the classic anti-pattern: no singleton. We're creating new instances of everything that should be shared."

Jordan: "Singleton? I've heard the term but never really understood it. What is it?"

Alex (standing up and walking to the whiteboard): "Alright, let me explain. A singleton is a design pattern that ensures you have exactly ONE instance of something in your entire application. Not two, not a thousand - ONE."

Alex draws on the whiteboard:

Current State (THE PROBLEM):
============================
Request 1 → Config #1, DB Pool #1, Logger #1, Cache #1
Request 2 → Config #2, DB Pool #2, Logger #2, Cache #2
Request 3 → Config #3, DB Pool #3, Logger #3, Cache #3
...
Request N → Config #N, DB Pool #N, Logger #N, Cache #N

Result: N requests = N instances of EVERYTHING!
Memory: 500 requests × 15MB = 7.5GB
DB connections: 500 pools × 10 = 5,000 connections
Config file reads: 500 requests × 6 functions = 3,000 I/O operations!

Desired State (WITH SINGLETON):
================================
Request 1 ↘
Request 2 → ONE Config, ONE DB Pool, ONE Logger, ONE Cache
Request 3 ↗
Request 4 ↗
...
Request N ↗

Result: N requests = 1 instance of shared resources!
Memory: 15MB (constant, regardless of request count!)
DB connections: 1 pool × 10 = 10 connections
Config file reads: 1 (total, for entire application lifetime!)

Maria: "So we need to refactor to use singletons. How long will this take?"

Alex: "In most languages, creating thread-safe singletons is tricky and error-prone. But in Rust, the compiler helps us. We can use Arc, RwLock, and once_cell to create singletons that are thread-safe by default."

Jordan (determined): "I can do this. Give me until Wednesday, and I'll have a solution."

Alex: "I'll pair with you. This is important to get right."

Maria: "Alright. Jordan and Alex, this is your top priority. Sarah, let's communicate with customers about Friday's downtime. Mike, increase the database connection limit temporarily as a band-aid, but we know the real fix needs to happen in the code."

Mike: "Already done. I bumped it to 500, but that's just delaying the inevitable if we don't fix the root cause."

Jordan: "We'll fix the root cause. No more band-aids."

The Discovery

Alex: "Alright Jordan, let's build your understanding from the ground up. First, what do you think a singleton is?"

Jordan: "From what you said yesterday... it's a way to ensure only one instance of something exists?"

Alex: "Exactly! Let me give you some real-world analogies to make this concrete."

Real-World Singleton Examples

Alex's whiteboard:

Real-World Singletons:
======================

1. The Sun in our solar system
   - We have exactly ONE sun
   - Everyone on Earth sees the SAME sun
   - You can't create a second sun
   - It exists for the lifetime of the solar system

2. The President of a country
   - A country has ONE president at any given time
   - All citizens interact with the SAME president
   - You can't have multiple presidents simultaneously
   - When the term ends, a new president is elected (but still ONE)

3. A Company's Configuration System
   - A company has ONE HR policy manual
   - All employees follow the SAME policies
   - If each department had different policies = chaos!
   - Updates to the manual apply to everyone immediately

In Software:
============

1. Application Configuration
   - ONE config for the entire app
   - All modules read the SAME values
   - Ensures consistency

2. Logger
   - ONE central logging system
   - All components write to the SAME log
   - Makes debugging easier

3. Database Connection Pool
   - ONE pool manager for the database
   - All requests share connections from the SAME pool
   - Prevents connection exhaustion

4. Cache Manager
   - ONE cache for the application
   - All components share the SAME cached data
   - Maximizes cache hit rate

Jordan: "Okay, that makes sense. But how do we enforce 'only one instance' in code? What stops someone from creating a second instance?"

Alex: "Great question! Let's look at how other languages do it first, then we'll see why Rust is better."

The Traditional Singleton

Alex writes Java code on the whiteboard:

// Traditional Singleton in Java.
public class ConfigManager {
    // Private static instance.
    private static ConfigManager instance;

    // Private constructor - can't create instance from outside!
    private ConfigManager() {
        // Load configuration.
    }

    // Public static method to get the instance.
    public static ConfigManager getInstance() {
        if (instance == null) {
            instance = new ConfigManager();  // Create on first access.
        }
        return instance;
    }
}

// Usage:
ConfigManager config = ConfigManager.getInstance();  // Gets the ONLY instance.

Alex: "See the pattern? The constructor is private, so nobody can call new ConfigManager(). The only way to get an instance is through getInstance(), which creates it once and reuses it."

Jordan: "That's clever! But wait... what if two threads call getInstance() at the same time?"

Alex (grinning): "EXACTLY! You've found the problem! If two threads enter getInstance() simultaneously, before the instance is created, you can end up with TWO instances!"

Jordan: "So it's not actually a singleton anymore?"

Alex: "Right. In Java, you need to add synchronisation:"

// Thread-safe singleton in Java. (more complex)
public class ConfigManager {
    private static volatile ConfigManager instance;

    private ConfigManager() {}

    public static ConfigManager getInstance() {
        if (instance == null) {  // First check (no locking)
            synchronized (ConfigManager.class) {  // Lock for thread-safety.
                if (instance == null) {  // Second check. (inside lock)
                    instance = new ConfigManager();
                }
            }
        }
        return instance;
    }
}

Alex: "This is called 'double-checked locking'. It's tricky to get right. People mess it up all the time. And it has performance overhead because of the synchronisation."

Jordan: "Yikes. That looks complicated."

Alex: "Now let me show you the Rust way."

The Rust Advantage

Alex writes Rust code:

// Singleton in Rust - Simple and Thread-Safe!
use once_cell::sync::Lazy;

static CONFIG: Lazy<ConfigManager> = Lazy::new(|| {
    ConfigManager::new()
});

// Usage:
let config = &*CONFIG;  // Gets the ONLY instance

Jordan: "That's... it? Just three lines?"

Alex: "Yep! And it's automatically thread-safe. The Lazy type from once_cell guarantees that the initialisation happens exactly once, even if a thousand threads try to access it simultaneously."

Jordan: "How does it work?"

Alex: "Under the hood, Lazy uses atomic operations and locks efficiently. But the key is: we don't have to think about it! The library handles all the thread-safety for us, and the Rust compiler ensures we use it correctly."

Jordan: "Okay, but what if we need to modify the config? Like when we hot-reload it?"

Alex: "Ah, now we need interior mutability. That's where Arc and RwLock come in."

Alex draws a more complete example:

use once_cell::sync::Lazy;
use parking_lot::RwLock;  // Better performance than std::sync::RwLock.
use std::sync::Arc;

// The singleton instance.
static CONFIG: Lazy<Arc<RwLock<ConfigManager>>> = Lazy::new(|| {
    println!("Initializing config - this prints EXACTLY ONCE");
    Arc::new(RwLock::new(ConfigManager::default()))
});

// Safe concurrent reads.
pub fn get_config() -> ConfigManager {
    CONFIG.read().clone()  // Multiple threads can read simultaneously.
}

// Safe exclusive writes.
pub fn update_config(new_config: ConfigManager) {
    let mut config = CONFIG.write();  // Only one thread can write.
    *config = new_config;
}

Jordan: "Okay, now I have more questions. What's Arc? What's RwLock? And why do we need both?"

Alex: "Perfect! Let's break down each component. Understanding these is crucial for building safe concurrent systems in Rust."

The Singleton Pattern

Let's dive deep into the Singleton pattern - what it is, why it exists, and how it works.

Breaking it down:

1. "Ensure a class has only one instance"

   • Not zero instances (that would be useless)

   • Not two or more instances (that defeats the purpose)

   • Exactly ONE instance for the entire application lifetime

2. "Provide a global point of access to it"

   • Anyone who needs the instance can get it

   • No need to pass it around as parameters

   • Consistent access mechanism

The Structure

When to Use Singletons

Use Singletons When:

1. Exactly one instance must exist

    // Application configuration - one source of truth.
    static CONFIG: Lazy<Arc<RwLock<Config>>> = ...;
   
    // Logger - centralized logging.
    static LOGGER: Lazy<Logger> = ...;
   
    // Database connection pool - manage limited resources.
    static DB_POOL: Lazy<Arc<ConnectionPool>> = ...;
   

2. Global access is genuinely needed

    // Accessed from many different modules/layers.
    mod handlers {
        use crate::CONFIG;
        fn handle() { let config = CONFIG.read(); }
    }
   
    mod database {
        use crate::CONFIG;
        fn connect() { let config = CONFIG.read(); }
    }
   
    mod middleware {
        use crate::CONFIG;
        fn auth() { let config = CONFIG.read(); }
    }
   

3. Initialisation is expensive

    // Loading large reference data
    static COUNTRY_DATA: Lazy<HashMap<String, Country>> = Lazy::new(|| {
        // Load 200MB of country/city data once
        load_countries_from_disk()  // Expensive!
    });
   
    // Singleton ensures this expensive operation happens only once.
   

Don't Use Singletons When:

1. You need multiple instances

    // ❌ DON'T: User sessions should NOT be singletons!
    // Each user needs their own session.
    struct UserSession { /* ... */ }
   
    // ✅ DO: Create instances per user.
    let session1 = UserSession::new(user1);
    let session2 = UserSession::new(user2);
   

2. Testing is difficult

    // ❌ Singletons make unit testing harder.
    #[test]
    fn test_something() {
        // Hard to mock or reset singleton state between tests.
        let result = some_function_using_singleton();
    }
   
    // ✅ Better: Dependency injection.
    fn some_function(config: &Config) -> Result { /* ... */ }
   
    #[test]
    fn test_something() {
        let mock_config = Config::test_default();
        let result = some_function(&mock_config);  // Easy to test!
    }
   

The Lifecycle

Rust Concepts for Thread-Safe Singletons

Before we build the solution, we need to understand the Rust primitives that make thread-safe singletons possible. This is where Rust truly shines compared to other languages.

1. Static Variables in Rust

Static variables live for the entire program duration and have a fixed memory address.

// Static variable - lives forever.
static COUNTER: i32 = 0;

fn main() {
    println!("{}", COUNTER);  // ✅ Can read.
    // COUNTER += 1;          // ❌ Can't mutate!
}

The problem:

// You might think: just make it mutable!
static mut COUNTER: i32 = 0;  // ⚠️ This requires unsafe!

fn main() {
    unsafe {
        COUNTER += 1;  // ⚠️ Unsafe! No compiler protection!
    }
}

Why is static mut unsafe?

// Data race! Multiple threads modifying COUNTER simultaneously.
use std::thread;

static mut COUNTER: i32 = 0;

fn main() {
    let handles: Vec<_> = (0..10)
        .map(|_| {
            thread::spawn(|| {
                unsafe {
                    // All threads increment simultaneously
                    // No synchronization!
                    // Final value is unpredictable!
                    COUNTER += 1;  // ⚠️ DATA RACE!
                }
            })
        })
        .collect();

    for handle in handles {
        handle.join().unwrap();
    }

    unsafe {
        // Expected: 10
        // Actual: ??? (could be anything from 1 to 10!)
        println!("Counter: {}", COUNTER);
    }
}

The solution: Interior mutability with thread-safe synchronisation

use std::sync::Mutex;

// Safe! Mutex provides interior mutability + thread safety.
static COUNTER: Mutex<i32> = Mutex::new(0);

fn main() {
    let mut counter = COUNTER.lock().unwrap();
    *counter += 1;  // Safe! Compiler-enforced locking.
}

2. once_cell::Lazy - Lazy Initialisation

The problem: How do we initialise complex types at runtime?

// ❌ This doesn't work!
static CONFIG: AppConfig = AppConfig::new();
// Error: cannot call non-const fn in static.

// Why? Static variables must be initialized at compile-time,
// but AppConfig::new() runs at runtime!

The solution: once_cell::Lazy

use once_cell::sync::Lazy;

static CONFIG: Lazy<AppConfig> = Lazy::new(|| {
    println!("Initializing config...");
    AppConfig::load_from_env()  // Runs at first access!
});

fn main() {
    // First access - triggers initialization.
    let config1 = &*CONFIG;
    // Prints: "Initializing config..."

    // Second access - reuses existing instance.
    let config2 = &*CONFIG;
    // No print! Uses existing instance.

    // config1 and config2 point to THE SAME data!
}

How Lazy works internally:

3. Arc<T> - Atomic Reference Counting

The problem: How do we share ownership across multiple threads?

// Regular references don't work across threads:
let data = vec![1, 2, 3];
let data_ref = &data;

thread::spawn(move || {
    println!("{:?}", data_ref);  // Error! Can't send reference across threads.
});

The solution: Arc (Atomic Reference Counted)

use std::sync::Arc;
use std::thread;

let data = Arc::new(vec![1, 2, 3]);

// Clone the Arc (cheap! just increments reference count)
let data_clone1 = Arc::clone(&data);
let data_clone2 = Arc::clone(&data);

// Now we can send to threads!
let handle1 = thread::spawn(move || {
    println!("Thread 1: {:?}", data_clone1);  // Works!
});

let handle2 = thread::spawn(move || {
    println!("Thread 2: {:?}", data_clone2);  // Works!
});

handle1.join().unwrap();
handle2.join().unwrap();

// Original Arc still valid.
println!("Main: {:?}", data);  // Works!

How Arc works - Memory Layout:

4. RwLock<T> - Reader-Writer Lock

The problem: How do we allow multiple readers OR one writer?

// With Mutex, only ONE thread can access at a time:
use std::sync::{Arc, Mutex};

let data = Arc::new(Mutex::new(0));

// Reader 1 locks.
let guard1 = data.lock().unwrap();
println!("Reader 1: {}", *guard1);

// Reader 2 wants to read... but must wait!
// Even though reading doesn't conflict with other reads!

The solution: RwLock (Reader-Writer Lock)

use std::sync::{Arc, RwLock};

let data = Arc::new(RwLock::new(0));

// Multiple readers can hold read locks simultaneously!
let reader1 = data.read().unwrap();
let reader2 = data.read().unwrap();  // OK! Both reading.
let reader3 = data.read().unwrap();  // OK! All reading.
println!("{} {} {}", *reader1, *reader2, *reader3);

// But writer must wait for all readers...
let mut writer = data.write().unwrap();
// ⏳ Blocks until reader1, reader2, reader3 are dropped

*writer = 42;  // Now writer has exclusive access.

RwLock State Machine:

When to use RwLock vs Mutex:

5. Putting It All Together

Now we combine all these primitives to create the perfect singleton:

use once_cell::sync::Lazy;
use parking_lot::RwLock;
use std::sync::Arc;

/// The Complete Singleton Pattern in Rust.
static CONFIG: Lazy<Arc<RwLock<AppConfig>>> = Lazy::new(|| {
    println!("Initializing config singleton!");
    Arc::new(RwLock::new(AppConfig::default()))
});

// Let's break down each layer:

// Layer 1: Lazy<...>
// - Delays initialization until first access
// - Guarantees initialization happens exactly once
// - Thread-safe initialization

// Layer 2: Arc<...>
// - Allows shared ownership across threads
// - Reference counted (atomically)
// - Data is freed when last Arc is dropped

// Layer 3: RwLock<...>
// - Allows multiple readers OR one writer
// - Interior mutability (modify through shared reference)
// - Thread-safe access to the data

// Layer 4: AppConfig
// - The actual data we want to store

How they work together:

Getting the Complete Code

The complete working implementation of the singleton pattern we've discussed is available in the GitHub repository.

Clone it, run it, and experiment with it to solidify your understanding!

git clone https://github.com/kartikmehta8/config-manager-api.git
cd config-manager-api
cargo run

The Learning Session

Jordan (leaning back in the chair, mind buzzing with new knowledge): "Wow. Okay. So we've covered:

• Static variables and why they're immutable by default

• Lazy for deferred initialisation

• Arc for shared ownership across threads

• RwLock for concurrent reads with exclusive writes

• And how they all work together to create a perfect singleton"

Alex (smiling): "Exactly! And the beautiful thing about Rust is that the compiler enforces all the safety guarantees. You literally cannot create a data race or deadlock without using unsafe. The type system guides you toward correct concurrent code."

Jordan: "I have to admit, when I first saw Lazy<Arc<RwLock<T>>>, it looked intimidating. But now I understand why each layer is necessary and what it does."

Alex: "That's the Rust learning curve. It looks complex at first, but once you understand the primitives, you realise they're all simple concepts that compose elegantly. Each type has one job and does it well."

Jordan (opening laptop): "Alright, I'm ready to start implementing. Let me create the config singleton first, then the logger, then refactor the database connections."

Alex (standing up): "Perfect! That's the spirit! I'll be at my desk if you need help. You've got this, Jordan."

The Conclusion

The singleton pattern might seem simple on the surface, "just one instance, right?" but as we've seen, implementing it correctly in a concurrent environment requires careful consideration of thread safety, lazy vs eager initialisation, read vs write patterns, and memory management.

Rust gives us the tools to handle all of these concerns with compile-time guarantees. No other mainstream language offers this level of safety without garbage collection or runtime overhead.

As Jordan discovered, the learning curve is worth it. The initial complexity of Lazy<Arc<RwLock<T>>> pays dividends in correctness, performance, and peace of mind.

Thanks for reading! If you found this helpful, star the repo and share it with fellow Rustaceans!

Stay caffeinated, stay rusty! 🦀

Meet Alex. Three months ago, Alex fulfilled a lifelong dream: opening "Rusty Bean", a cozy coffee shop in downtown Portland. Business is booming! Students camp out with their laptops, seniors meet for their morning ritual, and the loyalty program is attracting regulars.

But there's a problem. A big one.

It's 2 AM, and Alex is staring at the laptop screen in the empty shop. The code that handles discount calculations has become a monster. What started as a simple "if student, then 20% off" has grown into an unmaintainable nightmare.

The Mess

Let's take a look at what Alex is dealing with. The discount calculation system started simple enough, a few if statements to handle student discounts. But as the coffee shop grew and more discount types were added (seniors, loyalty members, different coffee types), the function spiraled out of control. What you're about to see is the reality of technical debt: a function that's been copy-pasted, modified, and patched so many times that it's become unmaintainable.

The Current Code

// Alex's current discount calculation function.
// WARNING: This is the BEFORE code - the mess we need to fix!

fn calculate_price(
    coffee_type: &str,
    customer_type: &str,
    base_price: f64
) -> f64 {
    if customer_type == "student" {
        if coffee_type == "espresso" {
            base_price * 0.8  // 20% off.
        } else if coffee_type == "latte" {
            base_price * 0.8  // 20% off.
        } else if coffee_type == "cappuccino" {
            base_price * 0.8  // 20% off.
        } else {
            base_price * 0.8  // default to 20% off.
        }
    } else if customer_type == "senior" {
        if coffee_type == "espresso" {
            base_price * 0.85  // 15% off.
        } else if coffee_type == "latte" {
            base_price * 0.85  // 15% off.
        } else if coffee_type == "cappuccino" {
            base_price * 0.85  // 15% off.
        } else {
            base_price * 0.85  // default to 15% off.
        }
    } else if customer_type == "loyalty_member" {
        if coffee_type == "espresso" {
            base_price * 0.9  // 10% off.
        } else if coffee_type == "latte" {
            base_price * 0.9  // 10% off.
        } else if coffee_type == "cappuccino" {
            base_price * 0.9  // 10% off.
        } else {
            base_price * 0.9  // default to 10% off.
        }
    } else {
        base_price  // no discount.
    }
}

// And this is just for simple percentage discounts!
// There's another function for "buy 2 get 1 free" deals...
// And another for "happy hour" discounts...
// It goes on and on...

"This is insane. I copy-pasted this code 47 times. FORTY-SEVEN! Last week, I changed the student discount from 20% to 25% and had to modify it in 12 different places. I missed three of them and gave some students 20% off while others got 25% off. My accountant is NOT happy."

The Pain Points

Let's break down why this code is a disaster:

1. Massive Duplication: The same discount logic repeated for every coffee type

2. Hard to Modify: Changing a discount percentage means hunting through the entire codebase

3. Error-Prone: Easy to miss one place when making changes

4. Hard to Test: How do you test this? Mock every possible combination?

5. Not Scalable: Adding a new discount type means copying everything again

Understanding the Chaos

Let's visualise what's happening in Alex's code:

Notice the problem? Every customer type branches into checking the coffee type, even though the coffee type doesn't affect the discount! This is unnecessary complexity.

The core problems are:

1. Mixing "What" with "How": The code mixes WHAT discount to apply with HOW to calculate it

2. Lack of Encapsulation: Discount logic is scattered, not contained

3. Tight Coupling: The main function knows too much about every discount type

4. No Abstraction: Each discount is just a number in an if-else chain

Monday morning, 8:37 AM. Alex's phone rings. It's the Marketing Manager, Jamie.

Jamie: "Alex! Great news! We're launching a 'Happy Hour' promotion - 25% off all drinks from 3 PM to 5 PM. Can you have it ready by Friday?"

Alex (already feeling the dread): "Um... sure. Let me check the code..."

Alex opens the laptop. To add Happy Hour discount, Alex needs to:

1. Add another if-else condition for time checking

2. Copy-paste it for every coffee type

3. Make sure it doesn't conflict with student/senior/loyalty discounts

4. Modify the order processing logic

5. Update the receipt printing code

6. Modify the daily sales report generator

7. Touch at least 8 different files

Alex (voice cracking): "Jamie... I'll need until next Wednesday. Maybe Thursday."

Jamie: "But it's just one discount! The competitor down the street implemented it in a day!"

After the call, Alex stares at the screen. There's got to be a better way.

The Mentor

Tuesday afternoon. Sarah, a regular customer who works as a senior Rust developer at a tech company, notices Alex's frustrated expression.

Sarah: "Rough day?"

Alex: "You could say that. I'm drowning in discount calculations. Every time marketing wants a new promotion, I need to modify code in a dozen places."

Sarah: "Mind if I take a look?"

Alex shows her the code. Sarah's eyes widen.

Sarah: "Ah, I see the problem. You're experiencing the 'God Function' anti-pattern. This function is trying to do everything."

The God Function/Object Anti-Pattern describes a single class or function that takes on far too many responsibilities, knowing and doing too much, violating the Single Responsibility Principle (SRP) by handling unrelated tasks like data access, UI logic, and business rules, leading to code that's hard to maintain, test, understand, and extend due to high coupling and ripple-effect bugs.

Alex: "How would you solve it?"

Sarah: "Ever heard of the Strategy Pattern?"

Alex: "Design patterns? I've heard of them but never really used them..."

Sarah pulls out a napkin and starts drawing.

Sarah: "Think of it this way. You have different discount strategies: student discount, senior discount, loyalty discount. Right now, you're choosing which strategy to use and HOW to calculate it in the same place. That's the problem."

She draws three boxes:

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  Student        │      │  Senior          │      │  Loyalty        │
│  Discount       │      │  Discount        │      │  Discount       │
│  Strategy       │      │  Strategy        │      │  Strategy       │
│                 │      │                  │      │                 │
│  20% off        │      │  15% off         │      │  10% off        │
└─────────────────┘      └──────────────────┘      └─────────────────┘

Sarah: "Each discount strategy is a separate, independent piece of code. Your order just says, 'Hey, apply whatever discount strategy you have.' It doesn't know or care HOW the discount is calculated."

Alex: "So... separate the WHAT from the HOW?"

• WHAT = Which discount to apply (student, senior, loyalty, etc.)

• HOW = The actual calculation logic (20% off, 15% off, etc.)

Alex pauses, thinking it through. "So in my current code, I'm doing both at the same time, checking WHO the customer is AND calculating their discount, all tangled together. But with this pattern, I'd just say 'This customer needs the student discount strategy' without knowing or caring that it's 20% off. The strategy itself knows the HOW part, the math. My order just knows WHAT strategy to use." A light bulb moment. "It's like when a customer orders a 'latte', I don't need to know HOW to make every drink. I just hand them the latte they ordered. The barista knows HOW to make it!"

Sarah: "Exactly! In Rust, we can use traits for this. Let me show you."

The Strategy Pattern

The Strategy Pattern is a behavioural design pattern that lets you define a family of algorithms, encapsulate each one, and make them interchangeable.

The Key Idea

The Three Components

Every Strategy Pattern implementation has three essential pieces working together. Let's break them down in a way that makes sense for our coffee shop scenario:

Looking at this diagram, here's what each part means:

1. Strategy Interface (DiscountStrategy trait): This is the blueprint that defines what all discounts must be able to do. Think of it as a contract: "If you want to be a discount in this system, you MUST be able to calculate a price." It doesn't care HOW you calculate it, just that you CAN.

2. Concrete Strategies (StudentDiscount, SeniorDiscount, etc.): These are the actual implementations, the workers who follow the blueprint. Each one says, "Yes, I can calculate a discount, and here's MY specific way of doing it." StudentDiscount does 20% off, SeniorDiscount does 15% off, and so on. They all follow the same interface, but each does it their own way.

3. Context (CoffeeOrder): This is the user of strategies. It's your coffee order that needs a discount applied. The crucial part? It doesn't know OR care which specific discount it has. It just knows, "I have some discount strategy, and when I need to calculate the final price, I'll ask it to do its thing."

Think of payment methods at a store:

• Strategy Interface: "Process Payment"

• Concrete Strategies: Cash, Credit Card, Mobile Payment, Cryptocurrency

• Context: Your purchase

The cashier doesn't need to know HOW each payment method works internally. They just say, "Process this payment," and each method handles it differently.

Sarah: "In your case, the 'Strategy Interface' is 'Calculate Discount.' Each discount type (student, senior, loyalty) is a 'Concrete Strategy.' And your coffee order is the 'Context' that uses whichever strategy is appropriate."

Alex: "So when I add Happy Hour discount, I just create a new strategy? I don't touch any existing code?"

Sarah: "Exactly! That's the Open/Closed Principle: open for extension, closed for modification."

The Open/Closed Principle (OCP) states that software entities (classes, modules, functions, etc.) should be open for extension but closed for modification.

This means you should be able to add new functionality or behaviours to a system without changing its existing, stable source code. The principle significantly improves the modularity and maintainability of code by preventing modifications in one area from introducing bugs in another.

The Refresher

Before we dive into the implementation, let's understand the Rust concepts we'll use.

1. Traits: Rust's Interfaces

A trait defines behaviour that types can implement. It's like a contract - if a type implements a trait, it promises to provide certain functionality.

Learn More: For a comprehensive guide to traits, see the official Rust book chapter on traits.

// A trait is like a promise:
// I can do "these things" FOR SURE.
trait DiscountStrategy {
    fn apply_discount(&self, base_price: f64) -> f64;
}

Any type implementing this trait must provide an apply_discount method.

Why traits?

• Define shared behaviour: Multiple types can share the same interface without sharing implementation

• Polymorphism: Different types can be used interchangeably through the same trait

• Zero-cost abstraction: Trait methods can be optimised away at compile time

• Composition over inheritance: Rust doesn't have traditional inheritance; traits provide a more flexible alternative

Traits vs Interfaces in Other Languages:

// In Java/C#, you might write:
// interface Discount {
//     double applyDiscount(double basePrice);
// }

// In Rust, it's:
trait Discount {
    fn apply_discount(&self, base_price: f64) -> f64;
}

The key difference? Rust traits can be implemented for types you don't own, and they support default implementations:

trait DiscountStrategy {
    fn apply_discount(&self, base_price: f64) -> f64;

    // Default implementation.
    fn apply_and_round(&self, base_price: f64) -> f64 {
        self.apply_discount(base_price).round()
    }
}

Sarah: "Think of traits as capabilities. When you say 'this type implements DiscountStrategy,' you're saying 'this type has the capability to calculate discounts.' The compiler then ensures you actually provide that capability."

2. Box: Dynamic Dispatch

Learn More: Understanding Box<T> is crucial for heap allocation. Read more in the Rust book's chapter on Box and trait objects.

// This can hold ANY type that implements DiscountStrategy.
let strategy: Box<dyn DiscountStrategy> = Box::new(StudentDiscount);

Breaking it down:

• Box<T>: A smart pointer that allocates T on the heap

  • Why heap? Because we don't know the size of the concrete type at compile time

  • Each strategy might have different sizes if they store data

  • The Box gives us a fixed-size pointer (8 bytes on 64-bit systems)

• dyn Trait: Dynamic dispatch - the method to call is determined at runtime

  • "dyn" stands for "dynamic"

  • Tells Rust: "I don't know the exact type, but it implements this trait"

  • Uses a vtable (virtual method table) to look up method implementations

• Combined: A heap-allocated value of unknown type that implements the trait

Visual representation:

What's a vtable?

A vtable (virtual method table) is a lookup table of function pointers:

When you call strategy.apply_discount(), Rust:

1. Looks at the vtable pointer

2. Finds the entry for apply_discount

3. Calls the function at that address

This small runtime cost (one pointer indirection) gives us flexibility!

Alex: "So every time we call a method, it has to look it up in this table?"

Sarah: "Yes, but it's incredibly fast - just one memory lookup. The trade-off is worth it when you need runtime flexibility."

3. Static vs Dynamic Dispatch

Static Dispatch (Compile-time):

fn calculate<T: DiscountStrategy>(strategy: T, price: f64) -> f64 {
    strategy.apply_discount(price)
}
// Compiler generates specific code for each type.
// Fast! But increases binary size.

Dynamic Dispatch (Runtime):

fn calculate(strategy: Box<dyn DiscountStrategy>, price: f64) -> f64 {
    strategy.apply_discount(price)
}
// Compiler uses vtable to look up method.
// Slight overhead, but more flexible.

For our use case, we need dynamic dispatch because we don't know which discount strategy to use until runtime (when the customer orders).

4. Ownership and Borrowing in Strategies

trait DiscountStrategy {
    // &self means "borrow self immutably".
    // The strategy doesn't need to own or modify itself.
    fn apply_discount(&self, base_price: f64) -> f64;
}

The &self means our strategies are immutable and can be shared safely.

5. Send and Sync Traits

Learn More: For a deep dive into thread safety, see the Rustonomicon chapter on Send and Sync.

trait DiscountStrategy: Send + Sync {
    fn apply_discount(&self, base_price: f64) -> f64;
}

These are marker traits that tell the compiler about thread safety:

• Send: A type is Send if it can be transferred between threads

  • Ownership can move from one thread to another

  • Most types are Send (integers, strings, your custom structs)

• Sync: A type is Sync if it can be shared between threads (via &T)

  • Multiple threads can have immutable references simultaneously

  • If &T is Send, then T is Sync

  • Example: Arc<T> (atomic reference counted) is Sync

Imagine you have toy blocks:

• Send: You can give your block to another kid (but then you don't have it anymore)

• Sync: Multiple kids can look at the same block at the same time (like through a display case)

In our coffee shop:

• Send: A discount can be passed from one part of the program to another

• Sync: Multiple customers can use the discount rules at the exact same time

The magic: Rust checks this automatically. If you mess up, it won't even let your code compile!

Why do we need this for our coffee shop?

Our web server (Axum) uses async/await and might handle requests on different threads. When a request comes in:

Thread 1: Customer orders coffee → Creates StudentDiscount strategy
Thread 2: Processes the order → Uses that same strategy

Without Send + Sync, the compiler would reject our code because it can't guarantee thread safety!

Visual example of thread safety:

// This is SAFE because DiscountStrategy is Send + Sync.
use std::sync::Arc;
use std::thread;

let strategy = Arc::new(StudentDiscount);  // Arc = Atomically Reference Counted.

// Thread 1 can use it.
let strategy_clone = strategy.clone();
let handle1 = thread::spawn(move || {
    println!("Thread 1: {}", strategy_clone.apply_discount(10.0));
});

// Thread 2 can also use it simultaneously.
let strategy_clone2 = strategy.clone();
let handle2 = thread::spawn(move || {
    println!("Thread 2: {}", strategy_clone2.apply_discount(15.0));
});

handle1.join().unwrap();
handle2.join().unwrap();

Wait, what is Arc?

Let's break down Arc::new(StudentDiscount) because it's crucial for multithreaded applications:

Arc stands for "Atomically Reference Counted" - that's a mouthful, but here's what it means in simple terms:

• Reference Counted: It keeps track of HOW MANY parts of your code are using this data. When the count reaches zero, the data is cleaned up automatically.

• Atomically: The counting is done in a thread-safe way. Multiple threads can safely update the count at the same time without corrupting it.

Why do we need Arc instead of just Box?

Remember Box<T> from earlier? It's great for single ownership. But here's the problem with threads:

// This WON'T work!
let strategy = Box::new(StudentDiscount);
let handle1 = thread::spawn(move || {
    // strategy moved here - Thread 1 owns it now.
});
let handle2 = thread::spawn(move || {
    // ERROR! Can't move strategy again - Thread 1 already took it!
});

With Box, once Thread 1 takes ownership (via move), Thread 2 can't use it. But we need BOTH threads to access the same discount!

Arc solves this by allowing shared ownership. This is the beauty of Rust: If your code compiles, you know it's thread-safe. No data races, no mysterious bugs!

Alex: "So Rust won't even let me compile code that could have threading issues?"

Sarah: "Exactly! The compiler is like a really pedantic code reviewer who never gets tired. It might feel strict at first, but it saves you from countless debugging nightmares."

The Solution

Alright! Let's build this thing. We'll start simple and gradually improve.

Want to see the complete working code? Check out the full implementation on GitHub: coffee-shop-api repository

Feel free to clone it and follow along!

Setting Up the Project

# Create a new Rust project.
cargo new coffee-shop-api
cd coffee-shop-api

Open Cargo.toml and add dependencies:

[package]
name = "coffee-shop-api"
version = "0.1.0"
edition = "2024"

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tower = "0.4"
tower-http = { version = "0.5", features = ["cors"] }

Why these dependencies?

• axum: Web framework (built on top of tokio and hyper)

• tokio: Async runtime for handling concurrent requests

• serde: Serialization/deserialization for JSON

• tower & tower-http: Middleware utilities

Define the Strategy Trait (The Contract)

Create src/strategies.rs:

// This is the heart of the Strategy Pattern.
// Every discount strategy MUST implement this trait.

pub trait DiscountStrategy: Send + Sync {
    /// Calculate the final price after applying the discount.
    ///
    /// # Arguments
    /// * `base_price` - The original price before discount.
    ///
    /// # Returns
    /// The final price after discount is applied.
    fn apply_discount(&self, base_price: f64) -> f64;

    /// Get the name of this discount strategy.
    /// Useful for logging and displaying to users.
    fn name(&self) -> &str;

    /// Get a description of how this discount works.
    /// Helps customers understand what discount they're getting.
    fn description(&self) -> &str;
}

What we just did:

• Defined a contract: any discount strategy must implement these three methods

• Added Send + Sync for thread-safety (required by Axum)

Implement Our First Strategy - Student Discount

Still in src/strategies.rs:

/// Student Discount: 20% off all drinks.
/// Requires valid student ID verification.
pub struct StudentDiscount;

impl DiscountStrategy for StudentDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        // Students get 20% off.
        // So they pay 80% of the original price.
        base_price * 0.80
    }

    fn name(&self) -> &str {
        "Student Discount"
    }

    fn description(&self) -> &str {
        "20% off all drinks with valid student ID"
    }
}

Key points:

• pub struct StudentDiscount; - This is a zero-sized type (no data)

• We implement the trait we defined

• The calculation is simple and localized

• This strategy doesn't need any configuration or state

Let's test it:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_student_discount_calculation() {
        let strategy = StudentDiscount;
        let base_price = 10.0;
        let final_price = strategy.apply_discount(base_price);

        assert_eq!(final_price, 8.0); // 20% off means pay 80%.
    }

    #[test]
    fn test_student_discount_name() {
        let strategy = StudentDiscount;
        assert_eq!(strategy.name(), "Student Discount");
    }
}

Run the test:

cargo test

Output:

running 2 tests
test strategies::tests::test_student_discount_calculation ... ok
test strategies::tests::test_student_discount_name ... ok

Implement More Strategies

Let's add the rest of our discount strategies:

/// Senior Discount: 15% off all drinks.
/// For customers 65 years or older.
pub struct SeniorDiscount;

impl DiscountStrategy for SeniorDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * 0.85  // 15% off.
    }

    fn name(&self) -> &str {
        "Senior Discount"
    }

    fn description(&self) -> &str {
        "15% off all drinks for seniors (65+)"
    }
}

/// Loyalty Card Discount: 10% off all drinks.
/// Plus earns points for future rewards (not implemented here, can be extended).
pub struct LoyaltyDiscount;

impl DiscountStrategy for LoyaltyDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * 0.90  // 10% off.
    }

    fn name(&self) -> &str {
        "Loyalty Card Discount"
    }

    fn description(&self) -> &str {
        "10% off all drinks + earn points towards free drinks"
    }
}

/// No Discount: Full price.
/// For regular customers without any discount eligibility.
pub struct NoDiscount;

impl DiscountStrategy for NoDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price  // No discount, pay full price
    }

    fn name(&self) -> &str {
        "Regular Price"
    }

    fn description(&self) -> &str {
        "Standard pricing with no discount"
    }
}

Notice the pattern? Each strategy:

1. Is a simple struct

2. Implements the DiscountStrategy trait

3. Has its own calculation logic

4. Is completely independent of other strategies

Sarah: "See how clean this is? Each discount strategy is self-contained. If the student discount changes, you only modify StudentDiscount. Nothing else."

Creating the Context (CoffeeOrder)

Create src/order.rs:

use crate::models::DiscountType;
use crate::strategies::{
    DiscountStrategy, LoyaltyDiscount, NoDiscount, SeniorDiscount, StudentDiscount,
};

/// Represents a coffee order with an applied discount strategy.
///
/// This is the "Context" in Strategy Pattern terminology.
/// It uses a strategy without knowing which specific one it is.
pub struct CoffeeOrder {
    pub coffee_type: String,
    pub base_price: f64,
    // This is the magic! It can be ANY strategy.
    discount_strategy: Box<dyn DiscountStrategy>,
}

What's happening here?

• CoffeeOrder holds a reference to a discount strategy

• It doesn't know or care which specific strategy it is

• Box<dyn DiscountStrategy> allows runtime strategy selection

Now let's add methods:

impl CoffeeOrder {
    /// Create a new coffee order with the specified discount strategy.
    ///
    /// This is a Factory Method that creates the appropriate strategy
    /// based on the customer type.
    pub fn new(
        coffee_type: String,
        base_price: f64,
        discount_type: DiscountType
    ) -> Self {
        // FACTORY METHOD: Select the right strategy based on discount type.
        let discount_strategy: Box<dyn DiscountStrategy> = match discount_type {
            DiscountType::Student => Box::new(StudentDiscount),
            DiscountType::Senior => Box::new(SeniorDiscount),
            DiscountType::Loyalty => Box::new(LoyaltyDiscount),
            DiscountType::None => Box::new(NoDiscount),
        };

        Self {
            coffee_type,
            base_price,
            discount_strategy,
        }
    }

    /// Calculate the final price by applying the discount strategy.
    ///
    /// THIS IS THE KEY METHOD!
    /// It delegates to the strategy without knowing which one it is.
    pub fn calculate_final_price(&self) -> f64 {
        // Ask the strategy to calculate the discount.
        // We don't know if it's student, senior, or loyalty.
        // We don't care! That's the power of the pattern.
        self.discount_strategy.apply_discount(self.base_price)
    }

    /// Get the discount amount (convenience method).
    pub fn get_discount_amount(&self) -> f64 {
        self.base_price - self.calculate_final_price()
    }

    /// Get the name of the applied discount strategy.
    pub fn get_discount_name(&self) -> &str {
        self.discount_strategy.name()
    }

    /// Get the description of the applied discount strategy.
    pub fn get_discount_description(&self) -> &str {
        self.discount_strategy.description()
    }
}

The magic moment: Look at calculate_final_price(). It just calls self.discunt_strategy.apply_discount(). It doesn't have any if-else logic. It doesn't know which discount type it is. That's polymorphism in action!

Define Data Models

Create src/models.rs:

use serde::{Deserialize, Serialize};

/// Request body for creating an order.
#[derive(Debug, Deserialize)]
pub struct OrderRequest {
    pub coffee_type: String,
    pub customer_type: String, // "student", "senior", "loyalty", or "none".
    pub base_price: f64,
}

/// Response body for order calculation.
#[derive(Debug, Serialize)]
pub struct OrderResponse {
    pub coffee_type: String,
    pub base_price: f64,
    pub discount_type: String,
    pub discount_description: String,
    pub discount_amount: f64,
    pub final_price: f64,
}

/// Enum representing different discount types.
#[derive(Debug, Clone, Copy)]
pub enum DiscountType {
    Student,
    Senior,
    Loyalty,
    None,
}

impl DiscountType {
    /// Parse a string into a DiscountType.
    pub fn from_string(s: &str) -> Option<Self> {
        match s.to_lowercase().as_str() {
            "student" => Some(DiscountType::Student),
            "senior" => Some(DiscountType::Senior),
            "loyalty" => Some(DiscountType::Loyalty),
            "none" => Some(DiscountType::None),
            _ => None,
        }
    }
}

Create API Handlers

Create src/handlers.rs:

use axum::{http::StatusCode, Json};
use crate::models::{DiscountInfo, DiscountsResponse, OrderRequest, OrderResponse};
use crate::order::CoffeeOrder;
use crate::models::DiscountType;

/// Handler for POST /order.
///
/// This endpoint:
/// 1. Receives order details from the client
/// 2. Validates the input
/// 3. Creates a CoffeeOrder with appropriate strategy
/// 4. Calculates the final price
/// 5. Returns the result
pub async fn calculate_order(
    Json(payload): Json<OrderRequest>,
) -> Result<Json<OrderResponse>, StatusCode> {
    // Validation: Check if base price is valid.
    if payload.base_price <= 0.0 {
        return Err(StatusCode::BAD_REQUEST);
    }

    // Parse the customer type string into a DiscountType enum.
    let discount_type = DiscountType::from_string(&payload.customer_type)
        .ok_or(StatusCode::BAD_REQUEST)?;

    // Create the order with the appropriate discount strategy.
    // This is where the Factory Method pattern comes in.
    let order = CoffeeOrder::new(
        payload.coffee_type.clone(),
        payload.base_price,
        discount_type,
    );

    // Calculate prices using the strategy.
    let final_price = order.calculate_final_price();
    let discount_amount = order.get_discount_amount();

    // Build response.
    let response = OrderResponse {
        coffee_type: payload.coffee_type,
        base_price: payload.base_price,
        discount_type: order.get_discount_name().to_string(),
        discount_description: order.get_discount_description().to_string(),
        discount_amount,
        final_price,
    };

    Ok(Json(response))
}

Flow visualisation:

Set Up the Web Server

Update src/main.rs:

use axum::{
    routing::{get, post},
    Router,
};
use tower_http::cors::CorsLayer;

mod handlers;
mod models;
mod order;
mod strategies;

#[tokio::main]
async fn main() {
    // Build our application with routes.
    let app = Router::new()
        .route("/order", post(handlers::calculate_order))
        .route("/discounts", get(handlers::list_discounts))
        .layer(CorsLayer::permissive());

    // Run the server.
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();

    println!("Rusty Bean Coffee Shop API running on http://localhost:3000");

    axum::serve(listener, app).await.unwrap();
}

The Implementation

Let's see the complete files:

Complete src/strategies.rs

// The Strategy Pattern: Each discount strategy implements this trait.
// This allows us to swap discount algorithms at runtime without changing the order logic.

/// The core trait that all discount strategies must implement.
/// This is the "Strategy" in Strategy Pattern.
pub trait DiscountStrategy: Send + Sync {
    /// Calculate the final price after applying the discount.
    fn apply_discount(&self, base_price: f64) -> f64;

    /// Get the name of this discount strategy.
    fn name(&self) -> &str;

    /// Get a description of how this discount works.
    fn description(&self) -> &str;
}

// ============================================================================
// CONCRETE STRATEGIES - Each one is a different discount algorithm
// ============================================================================

/// Student Discount: 20% off all drinks.
/// Used for customers with valid student ID.
pub struct StudentDiscount;

impl DiscountStrategy for StudentDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * 0.80 // 20% off.
    }

    fn name(&self) -> &str {
        "Student Discount"
    }

    fn description(&self) -> &str {
        "20% off all drinks with valid student ID"
    }
}

/// Senior Discount: 15% off all drinks.
/// Used for customers 65 years or older.
pub struct SeniorDiscount;

impl DiscountStrategy for SeniorDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * 0.85 // 15% off.
    }

    fn name(&self) -> &str {
        "Senior Discount"
    }

    fn description(&self) -> &str {
        "15% off all drinks for seniors (65+)"
    }
}

/// Loyalty Card Discount: 10% off all drinks.
/// Also earns points for future rewards (can be extended for this feature).
pub struct LoyaltyDiscount;

impl DiscountStrategy for LoyaltyDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * 0.90 // 10% off.
    }

    fn name(&self) -> &str {
        "Loyalty Card Discount"
    }

    fn description(&self) -> &str {
        "10% off all drinks + earn points towards free drinks"
    }
}

/// No Discount: Regular price.
/// Used for customers without any discount eligibility.
pub struct NoDiscount;

impl DiscountStrategy for NoDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price // No discount applied.
    }

    fn name(&self) -> &str {
        "Regular Price"
    }

    fn description(&self) -> &str {
        "Standard pricing with no discount"
    }
}

// ============================================================================
// BONUS: Happy Hour Discount (Added easily thanks to Strategy Pattern!)
// ============================================================================

/// Happy Hour Discount: 25% off all drinks.
/// Only available during happy hour (3-5 PM).
/// This shows how easy it is to add new strategies!
#[allow(dead_code)] // We're not using this in the API yet, but it's here to demonstrate extensibility.
pub struct HappyHourDiscount;

impl DiscountStrategy for HappyHourDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * 0.75 // 25% off.
    }

    fn name(&self) -> &str {
        "Happy Hour Discount"
    }

    fn description(&self) -> &str {
        "25% off all drinks during happy hour (3-5 PM)"
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_student_discount() {
        let strategy = StudentDiscount;
        assert_eq!(strategy.apply_discount(10.0), 8.0);
    }

    #[test]
    fn test_senior_discount() {
        let strategy = SeniorDiscount;
        assert_eq!(strategy.apply_discount(10.0), 8.5);
    }

    #[test]
    fn test_loyalty_discount() {
        let strategy = LoyaltyDiscount;
        assert_eq!(strategy.apply_discount(10.0), 9.0);
    }

    #[test]
    fn test_no_discount() {
        let strategy = NoDiscount;
        assert_eq!(strategy.apply_discount(10.0), 10.0);
    }
}

Testing Our Solution

Running the Server:

cargo run

Output:

Rusty Bean Coffee Shop API running on http://localhost:3000
    Compiling coffee-shop-api v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 3.21s
     Running `target/debug/coffee-shop-api`

Success! The server is running. Now let's test it.

Testing with curl

Let's test our API with some real requests:

Test 1: Student orders a latte

curl -X POST http://localhost:3000/order \
  -H "Content-Type: application/json" \
  -d '{
    "coffee_type": "Latte",
    "customer_type": "student",
    "base_price": 5.00
  }'

Response:

{
  "coffee_type": "Latte",
  "base_price": 5.0,
  "discount_type": "Student Discount",
  "discount_description": "20% off all drinks with valid student ID",
  "discount_amount": 1.0,
  "final_price": 4.0
}

The student gets 20% off their $5.00 latte, paying only $4.00.

Test 2: Senior orders a cappuccino

curl -X POST http://localhost:3000/order \
  -H "Content-Type: application/json" \
  -d '{
    "coffee_type": "Cappuccino",
    "customer_type": "senior", 
    "base_price": 4.50
  }'

Response:

{
  "coffee_type": "Cappuccino",
  "base_price": 4.5,
  "discount_type": "Senior Discount",
  "discount_description": "15% off all drinks for seniors (65+)",
  "discount_amount": 0.675,
  "final_price": 3.825
}

The senior citizen gets 15% off.

Test 3: Regular customer orders an espresso

curl -X POST http://localhost:3000/order \
  -H "Content-Type: application/json" \
  -d '{
    "coffee_type": "Espresso",
    "customer_type": "none",
    "base_price": 3.00
  }'

Response:

{
  "coffee_type": "Espresso",
  "base_price": 3.0,
  "discount_type": "Regular Price",
  "discount_description": "Standard pricing with no discount",
  "discount_amount": 0.0,
  "final_price": 3.0
}

Regular customers pay full price.

Missing Pieces

Let's add the missing handler for listing available discounts:

Complete src/handlers.rs:

use crate::models::DiscountType;
use crate::models::{DiscountInfo, DiscountsResponse, OrderRequest, OrderResponse};
use crate::order::CoffeeOrder;
use crate::strategies::{
    DiscountStrategy, LoyaltyDiscount, NoDiscount, SeniorDiscount, StudentDiscount,
};
use axum::{Json, http::StatusCode};

/// Calculates the final price with the selected discount strategy.
/// REQUEST METHOD: POST
/// REQUEST URL: /order
/// REQUEST BODY: { "coffee_type": "latte", "customer_type": "student", "base_price": 5.0 }
pub async fn calculate_order(
    Json(payload): Json<OrderRequest>,
) -> Result<Json<OrderResponse>, StatusCode> {
    if payload.base_price <= 0.0 {
        return Err(StatusCode::BAD_REQUEST);
    }

    let discount_type =
        DiscountType::from_string(&payload.customer_type).ok_or(StatusCode::BAD_REQUEST)?;
    let order = CoffeeOrder::new(
        payload.coffee_type.clone(),
        payload.base_price,
        discount_type,
    );

    let final_price = order.calculate_final_price();
    let discount_amount = order.get_discount_amount();

    let response = OrderResponse {
        coffee_type: payload.coffee_type,
        base_price: payload.base_price,
        discount_type: order.get_discount_name().to_string(),
        discount_description: order.get_discount_description().to_string(),
        discount_amount,
        final_price,
    };

    Ok(Json(response))
}

/// Lists all available discount strategies.
/// REQUEST METHOD: GET
/// REQUEST URL: /discounts
pub async fn list_discounts() -> Json<DiscountsResponse> {
    let student: Box<dyn DiscountStrategy> = Box::new(StudentDiscount);
    let senior: Box<dyn DiscountStrategy> = Box::new(SeniorDiscount);
    let loyalty: Box<dyn DiscountStrategy> = Box::new(LoyaltyDiscount);
    let none: Box<dyn DiscountStrategy> = Box::new(NoDiscount);

    let discounts = vec![
        DiscountInfo {
            code: "student".to_string(),
            name: student.name().to_string(),
            description: student.description().to_string(),
        },
        DiscountInfo {
            code: "senior".to_string(),
            name: senior.name().to_string(),
            description: senior.description().to_string(),
        },
        DiscountInfo {
            code: "loyalty".to_string(),
            name: loyalty.name().to_string(),
            description: loyalty.description().to_string(),
        },
        DiscountInfo {
            code: "none".to_string(),
            name: none.name().to_string(),
            description: none.description().to_string(),
        },
    ];

    Json(DiscountsResponse {
        available_discounts: discounts,
    })
}

Complete src/models.rs:

use serde::{Deserialize, Serialize};

/// Request body for creating an order.
#[derive(Debug, Deserialize)]
pub struct OrderRequest {
    pub coffee_type: String,
    pub customer_type: String, // "student", "senior", "loyalty", or "none".
    pub base_price: f64,
}

/// Response body for order calculation.
#[derive(Debug, Serialize)]
pub struct OrderResponse {
    pub coffee_type: String,
    pub base_price: f64,
    pub discount_type: String,
    pub discount_description: String,
    pub discount_amount: f64,
    pub final_price: f64,
}

/// Response for listing available discounts.
#[derive(Debug, Serialize)]
pub struct DiscountInfo {
    pub code: String,
    pub name: String,
    pub description: String,
}

/// Response body for listing all available discounts.
#[derive(Debug, Serialize)]
pub struct DiscountsResponse {
    pub available_discounts: Vec<DiscountInfo>,
}

/// Enum representing different discount types.
/// This is used to select which strategy to use.
#[derive(Debug, Clone, Copy)]
pub enum DiscountType {
    Student,
    Senior,
    Loyalty,
    None,
}

impl DiscountType {
    /// Parse a string into a DiscountType.
    /// Returns None if the string doesn't match any known type.
    pub fn from_string(s: &str) -> Option<Self> {
        match s.to_lowercase().as_str() {
            "student" => Some(DiscountType::Student),
            "senior" => Some(DiscountType::Senior),
            "loyalty" => Some(DiscountType::Loyalty),
            "none" => Some(DiscountType::None),
            _ => None,
        }
    }

    /// Convert DiscountType to a string code.
    #[allow(dead_code)]
    pub fn to_string(&self) -> &str {
        match self {
            DiscountType::Student => "student",
            DiscountType::Senior => "senior",
            DiscountType::Loyalty => "loyalty",
            DiscountType::None => "none",
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_discount_type_parsing() {
        assert!(matches!(
            DiscountType::from_string("student"),
            Some(DiscountType::Student)
        ));
        assert!(matches!(
            DiscountType::from_string("SENIOR"),
            Some(DiscountType::Senior)
        ));
        assert!(DiscountType::from_string("invalid").is_none());
    }
}

Test the discounts endpoint:

curl http://localhost:3000/discounts

Response:

{
  "discounts": [
    {
      "name": "Student Discount",
      "description": "20% off all drinks with valid student ID",
      "percentage": "20%",
      "example_savings": "$2.00 off on a $10.00 drink"
    },
    {
      "name": "Senior Discount",
      "description": "15% off all drinks for seniors (65+)",
      "percentage": "15%",
      "example_savings": "$1.50 off on a $10.00 drink"
    },
    {
      "name": "Loyalty Card Discount",
      "description": "10% off all drinks + earn points towards free drinks",
      "percentage": "10%",
      "example_savings": "$1.00 off on a $10.00 drink"
    },
    {
      "name": "Regular Price",
      "description": "Standard pricing with no discount",
      "percentage": "0%",
      "example_savings": "$0.00 off on a $10.00 drink"
    }
  ]
}

Let's run our unit tests to make sure everything works:

cargo test

Output:

running 7 tests
test strategies::tests::test_student_discount ... ok
test strategies::tests::test_senior_discount ... ok
test strategies::tests::test_loyalty_discount ... ok
test strategies::tests::test_no_discount ... ok
test order::tests::test_order_with_student_discount ... ok
test order::tests::test_order_with_no_discount ... ok
test order::tests::test_order_with_senior_discount ... ok

test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Our implementation is solid.

Alex leans back in the chair, a smile spreading across their face.

The Resolution

Three weeks later. Friday evening, 7:15 PM.

Alex stands behind the counter, watching the last customers of the day leave. The laptop is open, showing a dashboard of the day's sales. Everything has been running smoothly since implementing the Strategy Pattern.

Sarah walks in, ordering her usual cappuccino.

Sarah: "So? How's the new system working out?"

Alex (beaming): "Sarah, you saved my business. Remember that Happy Hour discount that Jamie wanted? The one that would've taken me a week to implement with the old code?"

Sarah: "The one that was going to ruin your life?"

Alex: "I implemented it in 45 minutes."

Sarah: (raising her eyebrows) "Seriously?"

Alex: "Watch this."

Alex opens the laptop and added a new strategy in src/strategies.rs:

/// Happy Hour Discount: 25% off all drinks.
/// Valid from 3 PM to 5 PM on weekdays.
pub struct HappyHourDiscount;

impl DiscountStrategy for HappyHourDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * 0.75 // 25% off.
    }

    fn name(&self) -> &str {
        "Happy Hour Special"
    }

    fn description(&self) -> &str {
        "25% off all drinks (3 PM - 5 PM weekdays)"
    }
}

Then adds one line to models.rs:

pub enum DiscountType {
    Student,
    Senior,
    Loyalty,
    HappyHour,  // <- Just this!
    None,
}

And updates the parser:

impl DiscountType {
    pub fn from_string(s: &str) -> Option<Self> {
        match s.to_lowercase().as_str() {
            "student" => Some(DiscountType::Student),
            "senior" => Some(DiscountType::Senior),
            "loyalty" => Some(DiscountType::Loyalty),
            "happyhour" => Some(DiscountType::HappyHour),  // <- And this!
            "none" => Some(DiscountType::None),
            _ => None,
        }
    }
}

Finally, updates the factory in order.rs:

let discount_strategy: Box<dyn DiscountStrategy> = match discount_type {
    DiscountType::Student => Box::new(StudentDiscount),
    DiscountType::Senior => Box::new(SeniorDiscount),
    DiscountType::Loyalty => Box::new(LoyaltyDiscount),
    DiscountType::HappyHour => Box::new(HappyHourDiscount),  // <- Just this line!
    DiscountType::None => Box::new(NoDiscount),
};

Alex: "That's it. Three small changes. No touching the existing strategies. No modifying the order calculation logic. No hunting through 12 different files. Just add the new strategy and plug it in."

Sarah: "And it just... works?"

Alex: "It just works. And you know what the best part is?"

Sarah: "What?"

Alex: "Last month, Jamie asked for a 'Buy One Get One Free' discount for couples. With the old code, I would've panicked. But now?"

Alex shows Sarah another strategy:

/// BOGO Discount for couples: Buy one drink, get second 50% off.
pub struct CoupleDiscount;

impl DiscountStrategy for CoupleDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        // First drink: full price.
        // Second drink: 50% off.
        // Average per drink: 75% of normal price.
        base_price * 0.75
    }

    fn name(&self) -> &str {
        "Couples Special"
    }

    fn description(&self) -> &str {
        "Buy one drink, get second 50% off"
    }
}

Alex: "Fifteen minutes. Implemented, tested, and deployed."

Sarah (genuinely impressed): "You've really internalised this pattern."

Alex: "You know what's crazy? I was up until 2 AM for three weeks straight, fighting with that if-else nightmare. Now I close on time, the code is clean, and I actually enjoy adding new features. I even started a blog about it!"

Sarah: "A blog?"

Alex: "Yeah, 'The Coffee Shop Crisis' Figured other people might be struggling with the same stuff. Got 500 readers in the first week."

Sarah smiles, picking up her cappuccino: "That's the power of good software design, Alex. It doesn't just make your code better, it makes your life better."

Alex: "Thank you, Sarah. Really. You didn't just help me fix my code. You taught me how to think about problems differently."

As Sarah heads out, Alex looks at the clean, organised codebase on the screen. Three months ago, this coffee shop was a dream filled with stress. Now it's a dream that works.

And it's all because Alex learned to think in patterns.

The Use (And No Use)

The Strategy Pattern is powerful, but it's not always the right tool. Here's when to use it and when to avoid it.

Use Strategy Pattern When:

1. You Have Family of Algorithms

When you have multiple ways to accomplish the same task:

// Good use case: Different payment methods.
trait PaymentStrategy {
    fn process_payment(&self, amount: f64) -> Result<(), String>;
}

struct CreditCardPayment;
struct PayPalPayment;
struct CryptoPayment;

2. Behaviour Needs to Change at Runtime

When you don't know which algorithm to use until runtime:

// The discount applied depends on customer data we fetch at runtime.
let customer = fetch_customer_from_database(customer_id);
let discount = match customer.status {
    CustomerStatus::New => Box::new(WelcomeDiscount),
    CustomerStatus::VIP => Box::new(VIPDiscount),
    CustomerStatus::Regular => Box::new(NoDiscount),
};

3. You Want to Avoid Complex Conditionals

When you have this:

// DON'T DO THIS
fn calculate_shipping(method: &str, weight: f64) -> f64 {
    if method == "standard" {
        if weight < 5.0 {
            5.99
        } else if weight < 20.0 {
            12.99
        } else {
            25.99
        }
    } else if method == "express" {
        if weight < 5.0 {
            15.99
        } else if weight < 20.0 {
            28.99
        } else {
            50.99
        }
    } else if method == "overnight" {
        // ... you get the idea.
    }
}

Do this instead:

// DO THIS.
trait ShippingStrategy {
    fn calculate_cost(&self, weight: f64) -> f64;
}

struct StandardShipping;
impl ShippingStrategy for StandardShipping {
    fn calculate_cost(&self, weight: f64) -> f64 {
        if weight < 5.0 { 5.99 }
        else if weight < 20.0 { 12.99 }
        else { 25.99 }
    }
}

4. Open/Closed Principle Matters

When you want to add new behaviours without modifying existing code:

// Adding a new discount doesn't require touching existing code.
pub struct SeasonalDiscount {
    percentage: f64,
}

impl DiscountStrategy for SeasonalDiscount {
    fn apply_discount(&self, base_price: f64) -> f64 {
        base_price * (1.0 - self.percentage)
    }

    fn name(&self) -> &str {
        "Seasonal Sale"
    }

    fn description(&self) -> &str {
        "Limited time seasonal discount"
    }
}

Don't Use Strategy Pattern When:

1. You Only Have One Algorithm

If there's only one way to do something, don't over-engineer:

// BAD: Unnecessary abstraction.
trait EmailSender {
    fn send_email(&self, to: &str, body: &str);
}

struct SmtpEmailSender;  // Only one implementation.

// GOOD: Just write the function.
fn send_email(to: &str, body: &str) {
    // Send email using SMTP.
}

2. The Algorithms are Simple and Rarely Change

// BAD: Over-engineering a simple calculation.
trait TaxStrategy {
    fn calculate_tax(&self, amount: f64) -> f64;
}

// GOOD: Simple function is fine.
fn calculate_tax(amount: f64, tax_rate: f64) -> f64 {
    amount * tax_rate
}

3. Performance is Critical and Predictable

If you need maximum performance and know the algorithm at compile time:

// Use generics (static dispatch) instead of trait objects (dynamic dispatch).
fn process<T: Strategy>(strategy: T, data: &Data) {
    strategy.execute(data)  // No vtable lookup, can be inlined.
}

4. The Strategies Share a Lot of Common Code

If implementations are mostly the same with small variations:

// Instead of Strategy Pattern, use configuration
struct DiscountConfig {
    percentage: f64,
    min_purchase: f64,
}

fn apply_discount(price: f64, config: &DiscountConfig) -> f64 {
    if price >= config.min_purchase {
        price * (1.0 - config.percentage)
    } else {
        price
    }
}

The Conclusion

We started with Alex's nightmare: a tangled mess of if-else statements that made every change painful. Through the Strategy Pattern, we transformed that chaos into clean, maintainable code.

What we learned:

1. Strategy Pattern separates WHAT from HOW: The order doesn't know how discounts are calculated, it just knows to apply them

2. Traits enable polymorphism in Rust: Different types sharing the same interface

3. Box enables runtime flexibility: Choose algorithms dynamically

4. Open/Closed Principle in action: Add new discounts without modifying existing code

5. Thread safety with Send + Sync: Our strategies work seamlessly in async contexts

But more importantly, we learned that good software design isn't just about the code, it's about making your life easier. Alex went from drowning in technical debt to enjoying feature development. That's the real power of design patterns.

Written with ❤️ by a developer who's been in Alex's shoes. We've all had our 2 AM debugging sessions. Design patterns are the coffee that keeps our code awake and healthy.

Special thanks to the Rust community for building such an amazing language and ecosystem.

Stay caffeinated, stay rusty! 🦀

And it's not just personal computers. Think about enterprise environments, NAS (Network-Attached Storage) devices, Active Directory file shares, departmental folders on shared drives. Multiple people have access, but how do you ensure only the right people with the right verified attributes can decrypt specific folders? You can't just rely on usernames and passwords when compliance requires proof of age, sanctions screening, or other identity attributes.

That's when it hit me. What if I could gate access to files not just with a password, but with actual identity verification? What if I could set rules like "only decrypt this if the user is over 18" or "only if they're not on any sanctions lists"? And most importantly, what if I could do all this without compromising privacy?

Want to follow along? All the code from this article is available on GitHub. Feel free to clone, experiment, and build upon it!

What Are We Building Here?

I created a desktop application that lets you:

1. Encrypt entire folders with military-grade AES-256-GCM encryption

2. Set custom access rules per folder (minimum age, gender, OFAC sanctions clearance)

3. Verify your identity using the Self protocol before decrypting anything

4. Keep everything local and private on your machine

The folders literally disappear from your file system (they get hidden and encrypted), and the only way to access them is through the app after proving you meet the specific requirements you set.

Why Self Protocol?

Traditional identity verification is broken. When you verify your age on a website, you typically upload your entire ID or passport. They see your name, address, date of birth, ID number, everything. You're giving away the farm just to prove you're 21.

Self flips this on its head with zero-knowledge proofs. Here's how it works:

1. You scan your passport with your phone's NFC reader

2. Self generates cryptographic proofs about you

3. When an app needs verification, you share only what's required

4. The app gets a mathematical proof that you're over 18 (for example) without ever seeing your actual birthdate

It's like proving you can unlock a door without showing the key itself. Mind-blowing stuff.

The Architecture

This application is split into three distinct parts that work together seamlessly:

The Electron Main Process

This is where the magic happens. The Electron main process handles all the heavy lifting:

• File system operations

• Encryption/decryption with AES-256-GCM

• Storing folder configurations

• Managing encryption keys

The Next.js Frontend

Built with Next.js and React, this provides a clean, modern interface for:

• Browsing and managing encrypted folders

• Configuring folder access rules

• Displaying Self QR codes for verification

• Showing verification status in real-time

The Express Backend

A lightweight Express server that:

• Integrates with Self protocol's backend verifier

• Manages per-folder verification configurations

• Validates zero-knowledge proofs

• Checks age, gender, and OFAC requirements

Checkout: kartikmehta8/self-secure-folders

How Encryption Actually Works

Let's peek under the hood. When you add a folder to encrypt, here's what happens:

Step 1: Generate a Random Encryption Key

const id = crypto.randomUUID();
const key = crypto.randomBytes(32); // 256-bit key for AES.
const keyBase64 = key.toString("base64");

Each folder gets its own unique 256-bit encryption key. This key never leaves your machine and is stored securely in Electron's user data directory.

Step 2: Recursively Encrypt Every File

The app walks through your entire folder structure and encrypts each file individually:

async function encryptFile(sourcePath, targetPath, key) {
  const iv = crypto.randomBytes(12); // 12-byte initialization vector.
  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);

  const data = await fsPromises.readFile(sourcePath);
  const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
  const authTag = cipher.getAuthTag(); // For integrity verification.

  // Store: IV + Auth Tag + Encrypted Data.
  const payload = Buffer.concat([iv, authTag, encrypted]);
  await fsPromises.writeFile(targetPath, payload);
}

Why AES-256-GCM? Two reasons:

1. AES-256 is the gold standard for symmetric encryption, the same encryption used by governments and militaries worldwide

2. GCM (Galois/Counter Mode) provides authenticated encryption, meaning it prevents tampering. If someone modifies even a single bit of your encrypted file, decryption will fail

Step 3: Hide the Original Folder

On macOS and Linux, the app automatically renames your source folder with a leading dot (like .my-secret-folder), making it hidden from normal view:

if (process.platform !== "win32") {
  const parentDir = path.dirname(input.sourcePath);
  const baseName = path.basename(input.sourcePath);

  if (!baseName.startsWith(".")) {
    const hiddenPath = path.join(parentDir, `.${baseName}`);
    await fsPromises.rename(input.sourcePath, hiddenPath);
  }
}

Your encrypted version lives in Electron's user data directory, completely separate from your normal file system.

The Self Integration

This is where things get really interesting. When you click "Open" on an encrypted folder, you're not just entering a password, you're proving your identity.

Setting Up Verification Rules

First, you configure what requirements must be met to access a specific folder:

const conditions: FolderConditions = {
  minAge: 18,              // Must be at least 18 years old.
  gender: "female",        // Optional: specific gender requirement.
  requireOfacClear: true   // Must not be on OFAC sanctions list.
};

These rules get sent to the Express backend and stored in memory:

app.post("/api/config", async (req, res) => {
  const { configId, minimumAge, excludedCountries, ofac } = req.body;

  const config = {
    minimumAge: minimumAge || 18,
    excludedCountries: excludedCountries || [],
    ofac: Boolean(ofac),
  };

  await configStore.setConfig(configId, config);
});

Generating the QR Code

When you attempt to open a folder, the app generates a Self verification session:

const app = new SelfAppBuilder({
  version: 2,
  appName: "Self Secure Folders",
  scope: process.env.NEXT_PUBLIC_SELF_SCOPE,
  endpoint: process.env.NEXT_PUBLIC_SELF_ENDPOINT,
  userId: ethers.ZeroAddress,
  endpointType: "staging_https",
  userDefinedData: configId, // Links verification to specific folder.
  disclosures: {
    minimumAge: folder.conditions.minAge,
    ofac: folder.conditions.requireOfacClear,
    nationality: true,
    gender: true,
  },
}).build();

setUniversalLink(getUniversalLink(app));

This creates a QR code that encodes all the verification requirements. When you scan it with the Self mobile app, it knows exactly what to prove.

The Verification Flow

Here's what happens when you scan that QR code:

Backend Verification

The Express server receives the proof and validates it:

app.post("/api/verify", async (req, res) => {
  const { attestationId, proof, publicSignals, userContextData } = req.body;

  // Verify the zero-knowledge proof.
  const result = await selfBackendVerifier.verify(
    attestationId,
    proof,
    publicSignals,
    userContextData
  );

  const { isValid, isMinimumAgeValid, isOfacValid } = result.isValidDetails;

  // Check all requirements.
  if (!isValid || !isMinimumAgeValid || isOfacValid) {
    return res.json({
      status: "error",
      result: false,
      reason: "Verification failed"
    });
  }

  return res.json({
    status: "success",
    result: true,
    credentialSubject: result.discloseOutput
  });
});

The backend sees that you're over 18 (or whatever the requirement is), but it never sees your actual birthdate. It sees that you're not on OFAC sanctions lists, but it doesn't need your full identity document.

Frontend Requirement Checking

Once verification succeeds, the frontend does a final check against the folder's specific requirements:

const handleSuccessfulVerification = async () => {
  const response = await fetch(debugEndpoint);
  const data = await response.json();
  const result = data.verificationResult;

  // Check age requirement.
  if (folder.conditions.minAge && !result.isValidDetails.isMinimumAgeValid) {
    setStatus("Minimum age requirement not satisfied");
    return;
  }

  // Check gender requirement (if specified).
  if (folder.conditions.gender) {
    const genderFromProof = result.discloseOutput.gender.toLowerCase();
    const required = folder.conditions.gender.toLowerCase();

    if (!matchesGender(genderFromProof, required)) {
      setStatus("Gender requirement not satisfied");
      return;
    }
  }

  // Check OFAC requirement.
  if (folder.conditions.requireOfacClear && result.isValidDetails.isOfacValid) {
    setStatus("OFAC check failed. Access denied.");
    return;
  }

  // All checks passed - decrypt the folder!
  await window.electronAPI.openFolder(folder.id);
};

The Decryption Process

Once all verification checks pass, it's time to decrypt. The app creates a temporary decrypted copy of your folder:

async function decryptFile(sourcePath, targetPath, key) {
  const payload = await fsPromises.readFile(sourcePath);

  // Extract components from stored payload.
  const iv = payload.subarray(0, 12);
  const authTag = payload.subarray(12, 28);
  const ciphertext = payload.subarray(28);

  // Decrypt.
  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
  decipher.setAuthTag(authTag);

  const decrypted = Buffer.concat([
    decipher.update(ciphertext),
    decipher.final()  // This will throw if the auth tag doesn't match.
  ]);

  await fsPromises.writeFile(targetPath, decrypted);
}

The decrypted folder is placed in a temporary location, and your system's file explorer automatically opens it. You can work with your files normally.

The IPC Bridge

Electron apps have a unique challenge: the frontend (renderer process) and backend (main process) run in separate contexts for security. They communicate through IPC (Inter-Process Communication).

The Preload Script

This secure bridge exposes only specific functionality to the frontend:

// electron/preload.js.
const { contextBridge, ipcRenderer } = require("electron");

contextBridge.exposeInMainWorld("electronAPI", {
  listFolders: () => ipcRenderer.invoke("folders:list"),
  selectSourceFolder: () => ipcRenderer.invoke("folders:selectSource"),
  createFolder: (input) => ipcRenderer.invoke("folders:create", input),
  updateFolder: (id, updates) =>
    ipcRenderer.invoke("folders:update", { id, updates }),
  deleteFolder: (id) => ipcRenderer.invoke("folders:delete", { id }),
  openFolder: (id) => ipcRenderer.invoke("folders:open", { id }),
});

Using It in React

In your React components, you can now call these functions naturally:

const handleCreateFolder = async () => {
  const created = await window.electronAPI.createFolder({
    label: "My Secret Files",
    sourcePath: "/Users/me/Documents/secret",
    conditions: {
      minAge: 21,
      gender: null,
      requireOfacClear: true
    }
  });

  setFolders(prev => [...prev, created]);
};

This pattern keeps your Electron app secure while maintaining a clean, React-friendly API.

Performance Considerations

Handling Large Folders

Encrypting thousands of files can take time. I implemented several optimizations:

1. File Count Limiting

const MAX_ENCRYPTED_FILES = 5000;
let encryptedFileCount = 0;

async function encryptFile(sourcePath, targetPath, key) {
  if (encryptedFileCount >= MAX_ENCRYPTED_FILES) {
    throw new Error("Folder is too large to encrypt");
  }
  encryptedFileCount += 1;
  // ... encryption logic.
}

2. Smart Directory Skipping

Common large directories that don't need encryption are automatically skipped:

if (entry.isDirectory() && (
  entry.name === "node_modules" ||
  entry.name === ".git" ||
  entry.name === ".next" ||
  entry.name === "dist" ||
  entry.name === "build"
)) {
  continue;
}

3. Async File Operations

All file operations use Node's promise-based APIs for better performance:

const fsPromises = fs.promises;

// Instead of synchronous:
// fs.readFileSync(path).

// We use:
await fsPromises.readFile(path)

Real-World Use Cases

Now that we understand how it works, let's talk about where this could actually be useful.

1. Healthcare Records Management

Imagine a medical practice that needs to ensure only adults can access certain medical files:

{
  label: "Adult Patient Records",
  conditions: {
    minAge: 18,
    gender: null,
    requireOfacClear: false
  }
}

2. Financial Compliance

A financial advisor could use this to gate access to client files, ensuring anyone accessing them isn't on sanctions lists:

{
  label: "Client Portfolio Files",
  conditions: {
    minAge: 21,
    gender: null,
    requireOfacClear: true  // Must not be on OFAC list.
  }
}

3. Age-Gated Content

Content creators could distribute files that self-enforce age restrictions:

{
  label: "Age-Restricted Content",
  conditions: {
    minAge: 21,
    gender: null,
    requireOfacClear: false
  }
}

4. Multi-User Shared Workstations

In environments where multiple people share computers, this ensures only authorized individuals can decrypt sensitive folders based on their verified identity attributes.

5. Enterprise NAS and Network Shares

This pattern extends beautifully to enterprise environments with Network-Attached Storage (NAS) devices:

{
  label: "HR Confidential Documents",
  conditions: {
    minAge: 21,
    gender: null,
    requireOfacClear: true
  }
}

Imagine a NAS device where encrypted folders are stored, but decryption only happens after Self verification. Multiple employees can have physical access to the network share, but only those who verify their identity attributes can decrypt specific folders. This works great for:

• HR departments restricting access to employee records based on age verification

• Finance teams ensuring OFAC compliance before accessing client data

• Legal departments gating access to sensitive case files

• Research labs controlling access to confidential study data

The same approach could integrate with Active Directory or LDAP systems, users authenticate with their domain credentials, but decryption requires additional Self verification. It's defense-in-depth with privacy preservation.

Why This Is Different?

Let's look at how this stacks up against traditional solutions:

Building with Self

From a developer perspective, integrating Self was surprisingly straightforward.

Frontend Integration

import { SelfAppBuilder } from "@selfxyz/qrcode";

const app = new SelfAppBuilder({
  version: 2,
  appName: "My App",
  scope: "my-scope",
  endpoint: "https://my-server.com/verify",
  userId: userAddress,
  endpointType: "staging_https",
  disclosures: {
    minimumAge: 18,
    ofac: true,
  },
}).build();

Backend Integration

import { SelfBackendVerifier, InMemoryConfigStore } from "@selfxyz/core";

const configStore = new InMemoryConfigStore();
const verifier = new SelfBackendVerifier(
  scope,
  endpoint,
  true,
  AllIds,
  configStore,
  "hex"
);

app.post("/verify", async (req, res) => {
  const result = await verifier.verify(
    req.body.attestationId,
    req.body.proof,
    req.body.publicSignals,
    req.body.userContextData
  );

  res.json({ success: result.isValidDetails.isValid });
});

That's it. Self handles all the complex cryptography, proof verification, and passport validation.

Development Setup

Here's how to get this running on your machine:

1. Install Dependencies

# Root workspace.
npm install

# Backend.
cd server
npm install

# Frontend.
cd client
npm install

2. Configure Environment Variables

Backend (.env):

PORT=3001
SELF_SCOPE=your-scope-name
SELF_ENDPOINT=https://your-ngrok-url.ngrok-free.app/api/verify

Frontend (.env.local):

NEXT_PUBLIC_SELF_APP_NAME=Self Secure Folders
NEXT_PUBLIC_SELF_SCOPE=your-scope-name
NEXT_PUBLIC_SELF_ENDPOINT=https://your-ngrok-url.ngrok-free.app/api/verify
NEXT_PUBLIC_SELF_DEBUG_ENDPOINT=http://localhost:3001/debug/last-result
NEXT_PUBLIC_SELF_CONFIG_ENDPOINT=http://localhost:3001/api/config

3. Start Everything

# Terminal 1: Backend.
cd server
npm run dev

# Terminal 2: Expose backend via ngrok.
ngrok http 3001

# Terminal 3: Frontend.
cd client
npm run dev

# Terminal 4: Electron.
npm run dev:electron

4. Use the Self Mobile App

Download the Self mobile app, create mock passports, and you're ready to test the verification flow.

The Bigger Picture

This proof of concept demonstrates something important: identity verification doesn't have to compromise privacy.

We live in a world where showing your ID means revealing everything about yourself. Want to prove you're 21? Here's your full name, address, date of birth, ID number, and photo. It's absurd.

Zero-knowledge proofs change this paradigm entirely. You can prove:

• You're over 18 without revealing your birthdate

• You're not on a sanctions list without showing your full identity

• You're a resident of a country without showing your address

• You're unique without revealing who you are

When combined with strong encryption and native apps, this opens up entirely new possibilities:

Compliance Without Surveillance: Companies can meet regulatory requirements (age verification, sanctions screening) without collecting personal data.

Privacy-First Access Control: You can gate access to resources based on verified attributes while respecting user privacy.

Decentralized Identity: Users maintain control of their identity data instead of fragmenting it across dozens of services.

Wrapping Up

Building this project opened my eyes to what's possible when we combine modern cryptography with user-friendly applications. The code is open source, the protocol is transparent, and the possibilities are endless. Whether you're building compliance tools, privacy applications, or just want to experiment with zero-knowledge proofs, I hope this walkthrough inspires you to explore what's possible.

Feel free to fork the repo, build on it, break it, improve it. That's what POCs are for.

This project is a proof of concept demonstrating Self protocol integration with Electron. It is not intended for production use without proper security hardening and auditing.

If you ever need help or just want to chat, DM me on Twitter / X or LinkedIn.

Kartik Mehta

X / LinkedIn

I've always been fascinated by the idea of parental controls, not just for kids, but for... well, ourselves. We all need a little digital discipline sometimes. But here's the thing, most website blockers are either too easy to bypass (just disable the extension, right?) or they're heavy-handed apps that feel like you're grounding yourself.

That's how Self Lock was born.

Want to follow along? Check out the complete source code here:

What Is Self Lock?

Self Lock is a Chrome extension that puts your most distracting websites behind a verification wall powered by Self Protocol. Think of it as a digital safe for your attention, you can lock away sites like Twitter, Instagram, Reddit, or any website that pulls you away from what matters.

But here's where it gets interesting: to unlock these sites, you need to verify your identity using the Self mobile app. Once verified, you get a time-limited session (say, 20 minutes) where all protected sites are accessible. When the timer runs out, everything locks again automatically, even if the tabs are still open.

It's like having a responsible friend who taps you on the shoulder and says, "Hey, time's up."

Why Self Protocol?

Before we dive into the technical implementation, let me explain why Self Protocol was perfect for this project.

Self is a privacy-first identity verification protocol that uses zero-knowledge proofs. In simple terms, it lets you prove you're a real person who meets certain criteria (like being over 18) without revealing your actual passport data.

Here's how it works:

In simple steps:

1. You scan your passport using NFC on your phone

2. Self creates a cryptographic proof about your identity

3. You can selectively share information (like "I'm over 18" or "I'm not on the OFAC sanctions list")

4. Applications verify the proof without ever seeing your raw passport data

The Vision

While I built this as a focus tool, the use cases are much broader:

1. For Parents: Create a safe browsing environment for kids. Lock adult content or time-wasting sites behind your verification. Kids can't bypass it without your phone and passport.

2. For Focus: ADHD warriors and anyone who struggles with digital distractions can set boundaries. During work hours, social media stays locked unless you deliberately choose to break the seal.

3. For Privacy Advocates: Demonstrate how Web3 identity solutions can work in everyday applications, not just crypto trading.

4. For Developers: A complete reference implementation showing how to integrate Self Protocol into a real-world application with a clean UX.

This is just a proof-of-concept, the blocked sites are stored in local storage, not a database. In production, you'd want server-side management, family sharing features, and more. But it demonstrates the core concept beautifully.

How I Built It

Chrome Extension Basics

If you've never built a Chrome extension, the architecture might seem a bit mysterious at first. Chrome extensions have several moving parts:

The key components:

1. Manifest file (manifest.json): The blueprint that tells Chrome what your extension can do

2. Background script: A service worker that runs invisibly, managing state and logic

3. Content scripts: JavaScript injected into web pages to interact with the DOM

4. Popup UI: The interface users see when they click your extension icon

For Self Lock, I went with Manifest V3, the latest standard that Chrome is pushing everyone toward.

Here's what the manifest looks like:

{
  "manifest_version": 3,
  "name": "Self Lock",
  "version": "0.1.0",
  "description": "Lock websites behind Self Protocol verification",
  "permissions": ["storage", "tabs", "scripting"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js",
    "type": "module"
  },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["contentScript.js"],
    "run_at": "document_idle"
  }],
  "action": {
    "default_popup": "index.html",
    "default_icon": "self-icon.png"
  }
}

The permissions are straightforward:

• storage: To save which sites are protected and session data

• tabs: To monitor when you navigate to protected sites

• scripting: To inject the blur overlay on locked pages

Why I Chose Vite

Most Chrome extension tutorials use Webpack, but I went with Vite because it's significantly faster and the config is much cleaner.

Here's the beauty of Vite for Chrome extensions, you can define multiple entry points (background script, content script, popup UI) and it bundles them all correctly:

// vite.config.ts
export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'dist',
    rollupOptions: {
      input: {
        popup: resolve(__dirname, 'index.html'),
        background: resolve(__dirname, 'src/background.ts'),
        contentScript: resolve(__dirname, 'src/contentScript.ts'),
      },
      output: {
        entryFileNames: '[name].js',
        chunkFileNames: 'assets/[name].js',
        assetFileNames: 'assets/[name].[ext]'
      }
    }
  }
});

When you run npm run build, Vite compiles everything to a dist/ folder that's ready to load into Chrome. The whole build takes seconds, not minutes like Webpack.

Part 1: The Background Service Worker

The background script is the brain of the extension. It runs invisibly and manages all the core logic.

Here's what it does:

1. Monitors tab updates to check if you're navigating to a protected site:

// background.ts.
chrome.tabs.onUpdated.addListener(async (tabId, changeInfo, tab) => {
  if (changeInfo.status !== "complete" || !tab.url) return;

  const hostname = hostnameFromUrl(tab.url);
  const { protectedSites, session } = await getStorage();

  const isProtected = protectedSites.includes(hostname);
  const hasValidSession = isSessionValid(session);

  // Decide: should this page be locked?
  if (isProtected && !hasValidSession) {
    chrome.tabs.sendMessage(tabId, { type: "LOCK_SITE" });
  } else {
    chrome.tabs.sendMessage(tabId, { type: "UNLOCK_SITE" });
  }
});

2. Handles messages from the popup and content scripts:

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message?.type === "SESSION_UPDATED") {
    // Session changed, update all open tabs.
    updateAllTabs();
  }

  if (message?.type === "GET_STATUS_FOR_URL") {
    // Popup asking: "Is this site locked?"
    const { hostname } = message;
    const isLocked = /* check logic */;
    sendResponse({ locked: isLocked });
  }
});

3. Stores data using Chrome's storage API:

// storage.ts.
export async function getStorage(): Promise<ExtensionStorage> {
  const data = await chrome.storage.local.get(null);
  return {
    protectedSites: data.protectedSites || [],
    session: data.session || null,
    sessionDurationMinutes: data.sessionDurationMinutes || 20
  };
}

export async function setStorage(updates: Partial<ExtensionStorage>) {
  await chrome.storage.local.set(updates);
}

The storage schema is simple:

type ExtensionStorage = {
  protectedSites: string[];           // ["twitter.com", "instagram.com"]
  session: {
    verified: boolean;
    expiresAt: number;                // Unix timestamp.
    verificationSummary: string;      // "Nationality US · Age ≥ 18".
  } | null;
  sessionDurationMinutes: number;     // Default: 20.
};

Storage Architecture:

Everything lives in chrome.storage.local, which persists across browser restarts. This means if you set up protected sites and close Chrome, they're still protected when you reopen.

Part 2: The Content Script

The content script runs on every page you visit. Its job is simple: show or hide the blur overlay based on messages from the background script.

Here's the overlay creation logic:

// contentScript.ts.
function createOverlay() {
  if (document.getElementById("self-lock-overlay")) return;

  const overlay = document.createElement("div");
  overlay.id = "self-lock-overlay";
  overlay.style.cssText = `
    position: fixed;
    top: 0; left: 0; right: 0; bottom: 0;
    background: linear-gradient(to bottom, rgba(15,23,42,0.95), rgba(30,41,59,0.98));
    backdrop-filter: blur(14px);
    z-index: 2147483647;
    display: flex;
    align-items: center;
    justify-content: center;
  `;

  const card = document.createElement("div");
  card.innerHTML = `
    <div style="background: rgba(30,41,59,0.8); padding: 2rem; border-radius: 1rem; max-width: 500px; text-align: center;">
      <h1 style="font-size: 1.5rem; font-weight: bold; color: white; margin-bottom: 1rem;">
        🔒 Self Lock Enabled
      </h1>
      <p style="color: #94a3b8; margin-bottom: 1.5rem;">
        This website is protected. Open the Self Lock extension and verify your identity to access it.
      </p>
      <span style="background: #1e293b; color: #60a5fa; padding: 0.5rem 1rem; border-radius: 0.5rem; font-size: 0.875rem;">
        Protected Site
      </span>
    </div>
  `;

  overlay.appendChild(card);
  document.body.appendChild(overlay);
}

The beauty of using inline styles is avoiding CSS conflicts with the page you're blocking.

But here's the cool part: When the session expires, the content script automatically re-locks the page without a refresh:

function setupExpiryTimer(session: SelfSession) {
  const remaining = session.expiresAt - Date.now();

  expiryTimeoutId = window.setTimeout(async () => {
    // Time's up! Re-check session validity.
    const { session: latestSession } = await getStorage();

    if (!isSessionValid(latestSession)) {
      createOverlay(); // Lock the page again.
    }
  }, remaining + 500); // 500ms buffer.
}

Imagine you're scrolling Twitter, your 20-minute timer expires, and boom, the page blurs right there. No navigation needed. That's the magic of content scripts with timers.

Part 3: The Popup UI

For the popup interface, I wanted something modern and clean. The popup has three main sections:

1. Current Site Card

Shows the site you're on and lets you quickly protect/unprotect it:

// App.tsx.
const isCurrentSiteProtected = state.protectedSites.includes(state.activeHost || '');

<div className="bg-slate-800 rounded-lg p-4">
  <h3 className="text-sm font-semibold text-slate-400 mb-2">Current site</h3>
  <div className="flex items-center justify-between">
    <span className="text-white font-mono">{state.activeHost || 'Unknown'}</span>
    <button
      onClick={toggleProtectionForCurrent}
      className={isCurrentSiteProtected ? 'bg-blue-500' : 'bg-slate-700'}
    >
      {isCurrentSiteProtected ? 'Protected' : 'Not protected'}
    </button>
  </div>
</div>

2. Session Card

This is where the Self Protocol integration happens:

const app = new SelfAppBuilder({
  version: 2,
  appName: "Self Lock",
  scope: "demo-scope",
  endpoint: "https://your-server.ngrok.io/api/verify",
  userId: ethers.ZeroAddress,
  endpointType: "staging_https",
  disclosures: {
    minimumAge: 18,
    ofac: true,
    nationality: true,
    gender: true
  }
}).build();

<SelfQRcodeWrapper
  selfApp={app}
  onSuccess={handleSuccessfulVerification}
  onError={handleError}
  type="websocket"
  size={140}
/>

The SelfQRcodeWrapper component from @selfxyz/qrcode does all the heavy lifting:

• Generates a QR code with a universal link

• Manages WebSocket connection for real-time verification

• Calls your callback when verification succeeds

When verification succeeds, I fetch the details and create a session:

const handleSuccessfulVerification = async () => {
  // Fetch verification details from backend.
  const res = await fetch('http://localhost:3001/debug/last-result');
  const data = await res.json();

  // Extract nationality and age.
  const nationality = data.result?.nationality || 'Unknown';
  const minimumAge = data.result?.minimumAge || 18;

  // Create session.
  const newSession: SelfSession = {
    verified: true,
    expiresAt: Date.now() + sessionDurationMinutes * 60 * 1000,
    verificationSummary: `Nationality ${nationality} · Age ≥ ${minimumAge}`
  };

  await setStorage({ session: newSession });
  chrome.runtime.sendMessage({ type: "SESSION_UPDATED" });

  setState(prev => ({ ...prev, session: newSession, viewState: 'verified' }));
};