Coder Legion - Recent posts tagged designpatterns

Security by Design in the Age of Artificial Intelligence: Fundamentals, Risks and Resilience Strateg

Mon, 12 Oct 2026 10:17:13 +0000

We live in a time when artificial intelligence has moved from being an emerging technology to a critical infrastructure. Algorithms decide what information we see, what transactions are suspicious, what diagnoses are likely, and increasingly, what decisions are optimal for organizations and governments. Companies like OpenAI, Google DeepMind, and Anthropic have accelerated the development of advanced models, making artificial intelligence a central element of the digital economy. In this context, security can no longer be an afterthought or a reactive mechanism. It must be an integral part of the system architecture from the moment of its conception.

Over the past two decades, digital transformation has been accelerated by cloud, mobility, and big data. In recent years, however, artificial intelligence (AI) has become the main driver of innovation.
But this revolution comes at a cost: the attack surface is growing exponentially.

Security by Design is not just about installing additional controls or enforcing stricter access policies. It means deeply integrating security principles into the technological DNA of a system. In the AI era, this approach becomes vital, because the complexity of models, their dependence on massive data, and the often opaque nature of algorithms create an environment in which vulnerabilities can be subtle but devastating.

The concept of Security by Design (SbD) involves integrating security from the design phase of a system, not as a later stage or a “patch” after vulnerabilities appear. In the AI era, this approach becomes critical because:

AI models are dependent on massive data.
Algorithms can be manipulated.
Automated decisions can have a major impact on users.
AI systems can be exploited in new ways (prompt injection, model inversion, data poisoning).

Security by Design in the AI era means responsible design, technical resilience, and solid governance.

From traditional security to algorithmic security

The concept of Security by Design is not new. It has been promoted since the 1990s in the field of application security and IT infrastructure. It initially appeared in the field of software security and IT infrastructures, being supported and formalized by organizations such as the National Institute of Standards and Technology (NIST) that developed frameworks such as the NIST Cybersecurity Framework, which promotes the integration of security into all stages of the life cycle. The idea was simple: it is more efficient and safer to prevent vulnerabilities by design than to correct them after the system has been compromised.

Classic principles include:

Principle of least privilege
Defense in depth
Fail secure
Zero Trust

In traditional systems, security focused on perimeter protection, authentication, encryption and vulnerability management. In the case of artificial intelligence, however, the object of protection is no longer only the infrastructure, but also the model itself. The algorithm becomes a critical asset. Training data becomes an attack surface. Automated decisions can have major legal and ethical implications.

Thus, security must be extended beyond servers and networks, to the algorithmic and epistemic level of the system, respectively, in the AI context, traditional principles must be extended to cover:

Training data security
Model integrity
Robustness against adversarial attacks
Explicability and auditability

Vulnerabilities specific to the AI era

Data poisoning

An AI system can be compromised not only through unauthorized access, but also through manipulation of the data on which it relies. Data poisoning attacks, in which malicious data is introduced into the training set, can subtly alter the behavior of the model. The result is not an obvious error, but a strategic degradation of performance or an intentional deviation of decisions.

Data poisoning is a type of attack in which the adversary compromises the integrity of an artificial intelligence model by deliberately introducing malicious data into the training set. Unlike attacks that target the system after implementation, data poisoning acts “at the source”, affecting the learning process of the model and influencing its long-term behavior. The injected data can be designed either to degrade the overall performance (unavailability or decreased accuracy) or to create a “backdoor” so that the model reacts erroneously only in the presence of a specific pattern or trigger. For example, a spam detection system could be trained with manipulated messages so that certain malicious expressions are later considered legitimate. The vulnerability is amplified in scenarios where the data comes from open, collaborative or automatically collected sources, without rigorous validation. From a Security by Design perspective, preventing data poisoning involves strict verification of the provenance of the data, auditing of datasets, anomaly detection mechanisms and controlled separation of data streams used for training.

Adversarial Attacks

Adversarial attacks are another sophisticated category of threats in which an adversary subtly manipulates the input data of an artificial intelligence model to cause systematic classification or decision errors, without the changes being obvious to human users. In the case of computer vision models, for example, adding minimal perturbations - invisible to the naked eye - to an image can cause the system to misidentify an object (a traffic sign can be misclassified, with serious implications for autonomous vehicles). Similarly, in natural language processing, the insertion of specially constructed linguistic structures or tokens can skew the interpretation of the model. These attacks exploit the mathematical sensitivity of neural networks to small variations in the multidimensional data space, demonstrating that high performance on standard data does not guarantee robustness under adversarial conditions. From a Security by Design perspective, countermeasures include adversarial training, robust input validation, and monitoring for abnormal model behavior in production.

Model Inversion & Data Extraction

Model Inversion is an attack technique in which an adversary attempts to reconstruct sensitive information about the data used to train a model, using only access to the final (black-box or sometimes white-box) model. The central idea is that machine learning models “retain” to some extent statistical characteristics of the training data. If the model is strategically interrogated, the attacker can approximate individual data or sensitive features associated with a particular user. For example, in a facial recognition system or a medical model trained on clinical data, an attacker could reconstruct facial features or information about a specific patient. The vulnerability arises especially when the model is overfitted or when its responses provide detailed probability scores, which can be exploited for reverse inference.

Data Extraction (or model extraction / training data extraction) goes even further, aiming at directly extracting fragments of data stored by the model during training. In the case of large language models, this can mean regenerating portions of sensitive texts accidentally included in datasets (personal data, API keys, confidential information). Attackers use iterative queries, strategic formulations or optimization techniques to “squeeze” the model of stored information. The risk is amplified when the models are integrated into public applications and provide very detailed answers. From a Security by Design perspective, protection against these attacks involves limiting the granularity of the outputs, using regularization and differential privacy techniques in the training phase, as well as implementing robust mechanisms for monitoring and filtering the generated answers.

Prompt Injection (in LLMs)

Unlike traditional attacks on web applications or infrastructure, prompt injection does not exploit a classic programming bug, but the very probabilistic and contextual nature of the model.

Prompt Injection is a technique by which a user inserts malicious instructions into an apparently legitimate input, with the aim of modifying the behavior of the model and causing it to ignore the rules or restrictions established by the system.

Typically, a system based on LLM works as follows:

There is a system prompt (internal instructions, invisible to the user).
There is a user prompt (user input).
The model generates a response based on the entire context.

The vulnerability arises because the model treats all text as a sequence of tokens, without making a rigid structural distinction between system and user instructions. Thus, a user can try to "overwrite" the initial rules with a specially constructed input.

Security by Design in the AI era involves anticipating these scenarios and designing the system so that it is robust, resilient and able to detect behavioral deviations.

Integrating Security into the AI Lifecycle

An AI system goes through several stages: data collection, model training, validation, deployment, and ongoing operation. Each of these phases should be treated as a critical control point.

In the data collection phase, security means verifying sources, ensuring the integrity of datasets, and protecting sensitive data through anonymization or pseudonymization. Data is the foundation of the model; if this foundation is compromised, the entire system becomes fragile.

In the training phase, the infrastructure must be isolated and monitored. Models must be versioned, and each experiment must be documented to allow for later auditing. The integrity of generated artifacts must be verified through cryptographic mechanisms, and access to computing resources must be limited according to the principle of least privilege.

At the time of deployment, API security becomes essential. Rate limiting, multifactor authentication, and monitoring for abnormal behavior are measures that reduce the risk of system exploitation. In the operational phase, continuous monitoring of model performance and detection of model drift are essential to prevent degradation or manipulation of its behavior.

Security by Design therefore means a continuity of control, not a single event.

Zero Trust and the new paradigm of trust

In the AI era, the concept of trust must be rethought. The Zero Trust model, which assumes that no user or system is implicitly trusted, becomes extremely relevant. Access to AI models and associated data should only be granted based on clear and verifiable policies.

This approach is all the more important as AI systems are integrated into complex ecosystems, distributed in the cloud, and connected to multiple data sources. The lack of segmentation or granular access controls can turn a minor incident into a major breach.

Zero Trust applied to AI is not limited to authentication; it also involves continuous validation of system behavior, verification of model integrity, and permanent analysis of user interactions.

Regulation, governance and accountability

As AI becomes critical infrastructure, regulation becomes inevitable. The European Union has introduced the AI Act, which classifies AI systems according to risk and imposes strict requirements for those considered high-risk. In parallel, the GDPR establishes clear obligations on data protection and the right to explanation.

These legislative frameworks are not obstacles to innovation, but catalysts for the adoption of Security by Design. They force organizations to document processes, implement audit mechanisms and ensure transparency.
AI governance thus becomes a central element of security. It is not enough for a system to perform; it must be accountable, explainable and compliant with legal norms.

The ethical dimension of security

Security in the age of AI is not just a technical issue. It is also an ethical one. A model that discriminates or produces biased results can generate damage as serious as a data breach.

Companies like Microsoft and IBM have developed Responsible AI frameworks that include principles of fairness, transparency, and accountability. These initiatives show that Security by Design must also include protection against social and moral risks.

Ultimately, security is not just about protecting the system, but also protecting the people affected by its decisions.

Red Teaming and Operational Resilience

A secure system is not one that has not been attacked, but one that has been rigorously tested and proven resilient.

Red Teaming in the context of AI systems is a structured process through which specialized teams simulate real-world attacks to identify vulnerabilities before they are exploited in the operational environment, directly contributing to increasing the resilience of the system. Unlike traditional testing, red teaming involves a creative adversarial approach, in which experts try to circumvent model restrictions through prompt injection, adversarial attacks, data exfiltration attempts, or manipulation of algorithmic behavior. The goal is not just to discover specific technical errors, but to assess the ability of the entire architecture - model, infrastructure, access controls, and organizational processes - to withstand real-world pressures. By integrating red teaming into the continuous development and operations (MLOps) cycle, organizations can transform security from a reaction to incidents into a proactive mechanism for strengthening operational resilience, ensuring the safe and stable operation of AI systems in dynamic and potentially hostile conditions.

This practice transforms security from a defensive to a proactive process. Instead of reacting to incidents, organizations anticipate and model risk scenarios.

Future Challenges

As AI evolves towards autonomous systems and agents capable of making complex decisions independently, the attack surface will continue to grow. The integration of AI into critical infrastructure, financial systems, or healthcare systems will amplify the potential impact of vulnerabilities.

Security by Design must evolve with technology. Collaboration between engineers, security experts, lawyers, ethicists, and policymakers will be required. Without this interdisciplinary approach, the complexity of AI systems may outstrip our ability to control them.

Conclusion: Security as the Foundation of Trust

In the age of artificial intelligence, security is no longer a technical detail, but the foundation of digital trust. Without Security by Design, AI systems can become vulnerable, manipulable, and potentially dangerous tools. With Security by Design, they can become catalysts for progress, supporting innovation in a responsible and sustainable way.

Building secure AI is not about slowing down development, but making it sustainable. In a world where algorithms increasingly influence reality, security becomes the invisible architecture that supports the future.

Bibliography

Pearlson, Keri & Novaes Neto, Nelson. „What is Secure-by-Design AI?”
- Definition and framework for integrating security as a basic principle in the design of AI systems.
ETSI EN 304 223 - Securing Artificial Intelligence (SAI)
- Security technical standard for AI systems, which includes "secure design" principles in the different stages of the AI lifecycle.
UK Government - Code of Practice for the Cyber Security of AI
- Best practices guide for designing and operating AI securely, including the principle of secure design.
Prasad, Anand. „A Policy Roadmap for Secure by Design AI: Building Trust Through Security-First Development”
- Article discussing the need to shift the AI security paradigm from reactive to proactive.
Abbas, Rianat et al. „Secure by design - enhancing software products with AI-Driven security measures”
- Study addressing the integration of AI-based security measures within Secure by Design.

Anatomy of a Short Link, When People Actually Want to Click?

Wed, 09 Sep 2026 22:07:23 +0000

Five small details that make a short url feel clearer, safer, and more memorable

A short link is not automatically a good link. Removing characters from a URL solves a length problem, but it does not answer the questions people ask before clicking: Where will this take me? Is it relevant? Can I trust it? Will I remember it later?

For web developers, the best short link is a small piece of interface design. Its domain, slug, surrounding copy, visual treatment, and technical behavior work together to reduce uncertainty. Get those details right and the link feels intentional instead of anonymous.

This guide explains five details that make a short link more useful across websites, email, social posts, documentation, QR codes, and messaging apps. The examples are global by design, so they also account for mobile users, multilingual audiences, and people navigating with keyboards or assistive technology.

1. A recognizable domain comes first

The domain is the first identity signal a person sees. A familiar brand domain tells the reader who is responsible for the destination. An unfamiliar or randomly generated domain makes the same destination feel harder to evaluate.

Compare these examples:

https://xmpl.co/a8K2p
https://docs.example.com/api/authentication

The first is shorter, but the second gives the reader more context. It identifies the organization, the product area, and the subject of the page.

A branded short link can combine the compactness of a short URL with the recognition of a known name:

https://go.example.com/api-auth

This does not prove that a destination is safe. It does, however, give people a useful signal to check. Security still depends on the actual destination, the service that manages the redirect, and the way your application handles abuse reports and compromised links.

Developer checklist

Use HTTPS for the short-link domain.
Keep the domain easy to read aloud and type.
Avoid confusing character combinations, such as lowercase l, uppercase I, and the number 1.
Use a branded domain when the link represents a company, product, or community.
Make the domain match the identity shown in the surrounding copy.

If you do not want to operate the redirect infrastructure yourself, Eslotmain is a link-shortening platform that offers custom slugs and branded domains. That can help keep a short link recognizable in a campaign or product flow. Treat the domain as an identity layer, not as a substitute for security review. A detailed url shortener tutorial post is available

2. The slug should explain the destination

The slug is the part of the short URL after the domain. It is a small space, but it can carry a surprising amount of meaning.

A random slug such as this is difficult to remember:

https://go.example.com/q7N4bP

A descriptive slug is easier to scan and repeat:

https://go.example.com/webinar-replay

The goal is not to put the whole page title into the URL. The goal is to provide the shortest useful description. Use lowercase letters, hyphens between words, and stable words that will still make sense after the campaign ends.

Good slugs are usually:

Specific: node-logging-guide says more than guide.
Compact: remove filler words and unnecessary dates.
Readable: use words instead of an opaque character string.
Stable: avoid changing the slug every time the page copy changes.
Audience-aware: use language your intended readers understand.

Be careful with dates, regional terms, and abbreviations. A slug such as summer-sale-uk may be useful for a time-limited campaign, but product-guide-en and product-guide-fr are clearer when you maintain separate language destinations. For a worldwide audience, decide whether language belongs in the slug, the destination path, or the campaign system. Do not make readers guess.

A descriptive slug is also helpful when someone sees a link without its surrounding page, such as in a screenshot or a copied message. It cannot reveal every redirect detail, but it gives the reader an immediate reason to understand the link.

3. The words around the link must set expectations

A short URL cannot do all the communication by itself. Link context tells people why the destination matters and what will happen after the click.

Weak copy:

Read more: https://go.example.com/r4T9

Clearer copy:

Read the WebAuthn implementation guide for a browser-ready passkey flow: https://go.example.com/webauthn-guide

The second version answers three questions before the click:

What is the destination?
Why should I open it?
What kind of content will I find?

This is also an accessibility requirement, not just a conversion tactic. WCAG guidance says that a link's purpose should be understandable from its text or its immediately associated context. The U.S. Web Design System similarly advises developers to use unique, meaningful link text and avoid generic phrases such as “click here” and “read more”

Use the link itself as the meaningful phrase where possible:

<p>
  Read the
  <a href="https://go.example.com/webauthn-guide">
    WebAuthn implementation guide
  </a>
  before adding passkey support.
</p>

Avoid relying on a title attribute to repair vague link text. The visible words should do most of the work. If the link opens a PDF, starts a download, requires a login, or leaves your site, say so in the visible text or its nearby context.

For international audiences, keep the context direct and easy to translate. Short sentences with concrete nouns are easier to understand than clever calls to action.

4. Visual treatment should make the click obvious

People should not have to move a pointer around the page to discover what is clickable. A link needs a visible affordance, which is a cue that communicates how an element can be used.

A dependable text-link treatment includes:

A consistent color that is distinct from ordinary text.
An underline or another non-color cue in body copy.
A visible hover state.
A visible keyboard focus state.
Sufficient contrast against the background.
A target large enough to tap comfortably on a phone.

Do not style ordinary headings or noninteractive cards to look like links. That creates false signals. Nielsen Norman Group describes consistency, placement, color, borders, and familiar web conventions as important cues for recognizing clickable elements. Its practical lesson is simple: if a design system teaches users one visual pattern for links, use that pattern everywhere.

The HTML should preserve native link behavior:

<a class="text-link" href="https://go.example.com/docs">
  Read the developer documentation
</a>

.text-link {
  color: #075985;
  text-decoration: underline;
  text-underline-offset: 0.15em;
}

.text-link:hover,
.text-link:focus-visible {
  color: #0c4a6e;
  text-decoration-thickness: 0.14em;
}

.text-link:focus-visible {
  outline: 3px solid #f59e0b;
  outline-offset: 3px;
}

Do not remove the outline without replacing it with an equally visible focus style. A keyboard user must be able to find the active link, and pressing Enter should activate it. Use a real <a href="..."> for navigation, not a clickable <div> that forces you to recreate browser behavior with JavaScript.

5. The redirect should feel safe and predictable

A short link is a promise: the destination should match the expectation created by the link. Broken redirects, unexpected login walls, surprise downloads, and unrelated landing pages damage trust quickly.

Before publishing a short link, check the full path from click to destination:

Does the short URL use HTTPS?
Does it redirect quickly on mobile and desktop?
Does it land on the page named in the link text?
Does it preserve the intended language or regional experience?
Does it avoid unnecessary redirect chains?
Does it remain valid after the campaign or product release changes?
Can you disable or update it if the destination becomes unsafe?

Analytics can help you detect problems and improve future links, but measurement should not make the experience opaque. Explain tracking where your privacy rules require it, collect only what you need, and protect link analytics as user data.

A useful short-link dashboard can show patterns such as clicks, locations, devices, and referrers. Eslotmain publicly describes these analytics as part of its platform, along with quick link creation and a free option for personal links with no credit card required. Developers can use those signals to compare distribution channels, spot a broken campaign, or learn whether a mobile audience needs a different landing page. Analytics should answer a product question, not become a reason to add needless tracking.

Putting the five details together

Here is a practical example for a developer newsletter:

<p>
  The new release adds passkey support. See the
  <a href="https://go.example.com/passkeys-node">
    Node.js passkey integration guide
  </a>
  for setup steps and browser notes.
</p>

The link works because each part has a job:

Link detail	What the reader learns
Recognizable domain	Who owns or manages the link
Descriptive slug	The general destination topic
Surrounding copy	Why the destination is relevant
Visible link styling	What can be clicked or tapped
Predictable redirect	What will happen after activation

A short link does not need to be loud. It needs to be legible, specific, and consistent with the experience that follows it.

A quick pre-publish test for web developers

Run this five-minute review before you share a link in production:

Read it without context. Can you infer the topic from the domain and slug?
Read the sentence only. Does the link explain its destination and purpose?
Use the keyboard. Can you reach the link with Tab and activate it with Enter?
Test a phone. Is the target easy to tap, and does the redirect load quickly?
Follow the complete redirect. Does the final page match the promise?
Check a copied version. Does the link remain understandable when pasted into a message?
Review the data plan. Are analytics transparent, necessary, and handled according to your privacy obligations?

Final takeaway

The anatomy of a link people want to click is not complicated. Start with a recognizable domain, add a readable slug, explain the destination in nearby text, make the link visibly interactive, and keep the redirect safe and predictable.

Shortening a URL is only the mechanical step. The real work is reducing doubt. When the link tells people where they are going, why it matters, and what to expect, a click becomes a reasonable decision instead of a gamble.

Frequently Asked Questions

What makes a link more clickable?

A link becomes more clickable when its destination and benefit are clear before activation. Descriptive link text, a recognizable domain, a readable slug, strong visual treatment, and a reliable redirect all reduce uncertainty.

Should developers use descriptive link text instead of “click here”?

Yes. Descriptive text helps sighted readers scan the page and helps screen-reader users understand a list of links out of context. Use words that identify the destination or action, such as “download the API reference PDF” or “view the passkey guide.”

Are short links safe to click?

Short links are not automatically safe because they hide the final destination. Use HTTPS, publish links through a service with abuse controls and management tools, provide useful context, and verify unfamiliar links before opening them.

Do branded short links improve trust?

They can improve recognition because the visible domain is connected to a known organization or product. Branded links do not guarantee that a destination is safe, so they should be combined with secure redirects, honest link context, and regular destination checks.

Do short links help SEO?

A short link can improve sharing and readability, but shortening a URL alone does not guarantee higher search rankings. For SEO, focus on the final page's content, canonical setup, crawlability, internal linking, and a clear user experience.

Demystifying Dependency Injection: Writing Code That Doesn't Break When Things Change

Fri, 04 Sep 2026 06:30:09 +0000

What is Dependency Injection?

Dependency Injection is a software design pattern where a program component receives the external resources or tools it needs to function from the outside, rather than creating them itself. In simpler terms, instead of a program hardcoding its own helpers internally, those helpers are 'injected' or passed into it when it starts up. This simple shift in responsibility makes your code incredibly flexible, highly reusable, and easy to modify without breaking existing features.

The Hybrid Car Battery Analogy

To understand this concept, imagine you are building a modern hybrid car. If you permanently solder a proprietary brand of battery directly to the car's frame and engine, you have a tightly coupled system. If that battery eventually degrades, or if a cheaper, more efficient battery is manufactured next year, you are in trouble. You would have to dismantle the entire car just to swap out the battery.

Instead, car manufacturers design a standardized battery compartment with a universal plug. The car's engine does not care about the internal chemistry or brand of the battery, as long as it fits the plug and delivers the expected voltage. The battery is 'injected' into the car from the outside. If you need to change the battery, you simply unplug the old one and slide in the new one. The car remains untouched.

Why Dependency Injection Matters Every Day

In professional software engineering, tight coupling is a primary cause of technical debt and broken deployments. Without Dependency Injection, developers cannot easily test their code in isolation. For instance, if a checkout system creates its own connection to a payment provider like Stripe inside its code, you cannot run automated tests on the checkout system without accidentally triggering real API calls and charging real credit cards.

By using Dependency Injection, engineers can swap out the real payment service for a fake 'mock' service during testing. This allows test suites to run in milliseconds without relying on external servers or risking financial errors. Furthermore, when business requirements inevitably pivot—such as switching your payment processor from Stripe to PayPal—you only have to write a new adapter and inject it at startup, rather than rewriting the core checkout logic. This prevents bugs from creeping into unrelated parts of your codebase.

Dependency Injection in Action

Let's look at how this looks in JavaScript code. First, we will examine code that does not use Dependency Injection, followed by the improved version that does.

// WITHOUT DEPENDENCY INJECTION (Tightly Coupled)
class CheckoutProcess {
  constructor() {
    // The checkout process is locked into Stripe; we cannot easily change or mock this
    this.paymentService = new StripeProcessor();
  }

  completeOrder(order) {
    this.paymentService.charge(order.amount);
  }
}

// WITH DEPENDENCY INJECTION (Loosely Coupled)
class DecoupledCheckoutProcess {
  constructor(paymentService) {
    // The payment service is injected from the outside
    this.paymentService = paymentService;
  }

  completeOrder(order) {
    this.paymentService.charge(order.amount);
  }
}

// Usage in production:
const stripe = new StripeProcessor();
const productionCheckout = new DecoupledCheckoutProcess(stripe);

// Usage in automated testing (injecting a fake helper instead):
const fakeMockProcessor = {
  charge: (amount) => console.log('Simulated charge of $' + amount)
};
const testCheckout = new DecoupledCheckoutProcess(fakeMockProcessor);

The Takeaway

Ultimately, Dependency Injection changes how you think about software architecture by turning hardcoded, rigid applications into collections of plug-and-play modules. By separating how a tool is configured from how that tool is actually used, you create a codebase that is inherently stable, highly testable, and ready to adapt to whatever changes your users or business stakeholders demand tomorrow.

Resources

GitHub Repository: react-hook-lab
react-hook-lab: npm package
Connect with me on LinkedIn: Saurav Pandey

Originally published on my blog. You can read the alternative breakdown here.

Three Go Concurrency Mistakes I See in Almost Every Worker Pool

Mon, 20 Jul 2026 16:44:53 +0000

Go makes concurrency feel easy. Goroutines are cheap, channels are built into the language, and the standard library gives you everything you need to spin up a worker pool in under 30 lines. That ease is genuinely valuable — but it also means bugs sneak in quietly. The program compiles, the tests pass, and the mistake only surfaces under load or after hours of runtime.

After working on high-throughput backend systems in Go, I keep seeing the same three mistakes. None of them are obscure. All of them are fixable in minutes once you know what to look for.

Mistake 1: Goroutine leaks from channels that never close

Here is a worker pool that looks completely reasonable:

func startWorkers(jobs <-chan Job) {
    for i := 0; i < 10; i++ {
        go func() {
            for job := range jobs {
                process(job)
            }
        }()
    }
}

Each worker ranges over the jobs channel and processes whatever comes in. Clean, idiomatic Go. The problem: if jobs is never closed, every one of those goroutines blocks forever.

for range on a channel blocks until the channel is closed or a value arrives. If the producer stops sending but never calls close(jobs), your 10 workers sit there permanently — holding memory, holding stack space, invisible to your metrics unless you’re explicitly tracking goroutine count.

In a long-running service, this compounds. Every time you restart the worker pool (say, on a config reload or a new batch) without draining the old one, you accumulate leaked goroutines.

The fix: always close the jobs channel when the producer is done, and own that responsibility clearly.

func runBatch(jobList []Job) {
    jobs := make(chan Job, len(jobList))

    // Producer owns the channel and closes it when done
    go func() {
        defer close(jobs) // guaranteed even if we panic
        for _, job := range jobList {
            jobs <- job
        }
    }()

    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                process(job)
            }
        }()
    }

    wg.Wait()
}

Two things worth noting here. First, defer close(jobs) in the producer goroutine means the channel closes even if the producer exits early or panics while sending jobs. Second, the sync.WaitGroup gives us a clean join point — wg.Wait() blocks until every worker has finished draining.

Quick diagnostic: add runtime.NumGoroutine() to your health endpoint. If that number grows over the lifetime of your service and never comes back down, you have a leak.

Mistake 2: WaitGroup counter manipulation in the wrong place

sync.WaitGroup has one sharp edge: wg.Add must be called before the goroutine starts, not inside it.

This version has a race condition:

var wg sync.WaitGroup

for _, job := range jobs {
    go func(j Job) {
        wg.Add(1)        // ❌ too late
        defer wg.Done()
        process(j)
    }(job)
}

wg.Wait()

If the loop spawns goroutines quickly and the scheduler runs slowly, wg.Wait() can be reached before any goroutine has called wg.Add(1). The counter is zero, Wait() returns immediately, and your main function exits while workers are still running — silently dropping work.

This is a classic race condition. It won’t always reproduce, which makes it worse.

The fix is simple: call wg.Add in the loop body, before launching the goroutine.

var wg sync.WaitGroup

for _, job := range jobs {
    wg.Add(1) // ✅ happens-before the goroutine starts
    go func(j Job) {
        defer wg.Done()
        process(j)
    }(job)
}

wg.Wait()

Now the counter increment is guaranteed to happen before wg.Wait() could possibly observe a zero. The goroutine carries the Done() responsibility via defer, so it fires even on panic.

A secondary pattern worth knowing: if you know the count upfront (say, you’re launching exactly N workers), call wg.Add(N) once before the loop. That’s even cleaner and harder to get wrong.

const numWorkers = 10
var wg sync.WaitGroup
wg.Add(numWorkers) // add all at once

for i := 0; i < numWorkers; i++ {
    go func() {
        defer wg.Done()
        for job := range jobs {
            process(job)
        }
    }()
}

wg.Wait()

Mistake 3: Unidirectional channel types ignored on function boundaries

Go lets you declare channels as send-only (chan<- Job) or receive-only (<-chan Job). Most codebases I’ve seen don’t use this consistently — functions just accept chan Job everywhere. This is technically fine, but it loses something real: the compiler can no longer tell you when your data flow is wrong.

Here is a worker pool where the direction confusion causes a real bug:

func spawnWorkers(jobs chan Job, results chan Result) {
    for i := 0; i < 10; i++ {
        go func() {
            for job := range jobs {
                result := process(job)
                jobs <- result.nextJob  // ❌ worker feeding back into the input channel
                results <- result
            }
        }()
    }
}

A worker accidentally wrote back into jobs instead of results. With bidirectional channels, this compiles without complaint. With directional types, it fails at compile time:

func spawnWorkers(jobs <-chan Job, results chan<- Result) {
    for i := 0; i < 10; i++ {
        go func() {
            for job := range jobs {
                result := process(job)
                jobs <- result.nextJob  // ✅ compile error: cannot send to receive-only channel
                results <- result
            }
        }()
    }
}

The directional types act as documentation that’s enforced by the compiler. The producer only sees chan<- Job. The consumer only sees <-chan Job. Neither can accidentally do the wrong thing.

A complete worker pool using this pattern correctly:

func produce(jobs chan<- Job, jobList []Job) {
    defer close(jobs)
    for _, job := range jobList {
        jobs <- job
    }
}

func consume(jobs <-chan Job, results chan<- Result, wg *sync.WaitGroup) {
    defer wg.Done()
    for job := range jobs {
        results <- process(job)
    }
}

func run(jobList []Job) []Result {
    jobs := make(chan Job, 100)
    results := make(chan Result, 100)

    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go consume(jobs, results, &wg)
    }

    go produce(jobs, jobList)

    // Close results once all workers are done
    go func() {
        wg.Wait()
        close(results)
    }()

    var out []Result
    for result := range results {
        out = append(out, result)
    }
    return out
}

Every function now only sees what it’s supposed to see. The compiler enforces the data flow. And the pattern is easy to read: produce feeds in, consume drains, the closer goroutine shuts down results when all workers finish.

Summary

Channel never closed — What goes wrong: goroutines leak, memory grows. Fix: the producer owns close(ch), always via defer.

wg.Add inside the goroutine — What goes wrong: work silently dropped, races at shutdown. Fix: call wg.Add before go func().

Bidirectional channels everywhere — What goes wrong: wrong-direction sends compile silently. Fix: use chan<- and <-chan at function boundaries.

None of these require clever solutions. They require habit. Once you internalize that the producer owns close, that Add precedes launch, and that channel direction is free documentation, they stop appearing.

Go 1.25’s go vet includes a WaitGroup analyzer that flags mistake 2 when Add is called from inside a goroutine. On older Go versions, test the behavior directly by asserting that all launched work completes; go test -race is not reliable for this case because WaitGroup uses internal synchronization. For mistake 1, runtime.NumGoroutine() in a test that runs your pool repeatedly and checks for growth is the simplest approach. Mistake 3 is pure compiler enforcement — no test needed once the types are right.

If this was useful, the next post in this series covers context.Context propagation in worker pools — specifically what happens when you need to cancel in-flight jobs cleanly without leaking the workers themselves.

Go Interfaces: Why Less Is Almost Always More

Mon, 20 Jul 2026 16:44:11 +0000

Go Interfaces: Why Less Is Almost Always More

If you’re coming to Go from Java or C++, interfaces look familiar at first glance. You define a set of methods, types implement them, you write code against the interface. Same idea, right?

Not quite. Go interfaces have one property that changes everything about how you should design them: a type implements an interface implicitly, without declaring it. There’s no implements keyword. If your type has the right methods, it satisfies the interface — whether it knows about the interface or not.

That single property pushes you toward a design philosophy that trips up most engineers coming from other languages: interfaces should be small, and they should be defined by the consumer, not the producer.

What the standard library is trying to tell you

Look at the most-used interfaces in Go’s standard library:

type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

type Closer interface {
    Close() error
}

One method each. That’s not laziness — that’s a deliberate design decision. Because interfaces are satisfied implicitly, a one-method interface can be satisfied by an enormous range of types: files, network connections, buffers, custom types you haven’t written yet. The smaller the interface, the more things satisfy it, the more reusable your code becomes.

io.ReadWriter combines two:

type ReadWriter interface {
    Reader
    Writer
}

And io.ReadWriteCloser combines three. Notice that the standard library builds up complexity by composing small interfaces, not by defining large ones upfront.

This is the pattern worth internalizing.

The fat interface trap

Here is how engineers from Java or C++ backgrounds tend to define interfaces in Go. Say you’re building a job processing system and you want to abstract over different job stores:

// ❌ The fat interface
type JobStore interface {
    AddJob(job Job) error
    GetJob(id string) (Job, error)
    DeleteJob(id string) error
    ListJobs(filter Filter) ([]Job, error)
    UpdateJob(job Job) error
    CountJobs(filter Filter) (int, error)
    MarkComplete(id string) error
    MarkFailed(id string, reason error) error
}

This feels complete. It covers everything the store can do. But now ask: how many types in your codebase will ever implement all 8 methods? Probably one — your real database implementation. And your test mock has to implement all 8 even if the function under test only calls GetJob.

// Every test mock must implement all 8 methods even if irrelevant
type mockStore struct{}

func (m *mockStore) AddJob(job Job) error                         { return nil }
func (m *mockStore) GetJob(id string) (Job, error)               { return Job{}, nil }
func (m *mockStore) DeleteJob(id string) error                   { return nil }
func (m *mockStore) ListJobs(filter Filter) ([]Job, error)       { return nil, nil }
func (m *mockStore) UpdateJob(job Job) error                     { return nil }
func (m *mockStore) CountJobs(filter Filter) (int, error)        { return 0, nil }
func (m *mockStore) MarkComplete(id string) error                { return nil }
func (m *mockStore) MarkFailed(id string, reason error) error    { return nil }

Eight methods of boilerplate for a test that calls one. And if you add a 9th method to the interface, every mock in the entire codebase breaks.

The Go way: consumer-defined, minimal interfaces

Instead of defining one big interface at the store level, define small interfaces at each use site — the function that actually needs the behavior.

// ✅ Each function declares exactly what it needs

type JobGetter interface {
    GetJob(id string) (Job, error)
}

type JobAdder interface {
    AddJob(job Job) error
}

type JobCompleter interface {
    MarkComplete(id string) error
    MarkFailed(id string, reason error) error
}

func processJob(id string, store JobGetter) error {
    job, err := store.GetJob(id)
    if err != nil {
        return err
    }
    // process...
    return nil
}

func submitJob(job Job, store JobAdder) error {
    return store.AddJob(job)
}

Now processJob only depends on JobGetter. Its test mock is one method:

type mockGetter struct {
    job Job
    err error
}

func (m *mockGetter) GetJob(id string) (Job, error) {
    return m.job, m.err
}

Your real PostgresJobStore still implements all 8 methods. It satisfies every one of these small interfaces automatically, without any change, because Go interfaces are implicit. The store doesn’t know or care about JobGetter or JobAdder — it just has the methods, and that’s enough.

Accepting interfaces, returning structs

There’s a corollary rule in Go that follows directly from this: accept interfaces, return concrete types.

// ✅ Accept an interface — flexible, testable
func drainQueue(queue <-chan Job, store JobAdder) error {
    for job := range queue {
        if err := store.AddJob(job); err != nil {
            return err
        }
    }
    return nil
}

// ❌ Return an interface — forces callers to type-assert, hides information
func newJobStore(cfg Config) JobStore {
    return &PostgresJobStore{...}
}

// ✅ Return a concrete type — callers get the full picture
func newJobStore(cfg Config) *PostgresJobStore {
    return &PostgresJobStore{...}
}

When you return a concrete type, callers can always choose to assign it to a narrower interface themselves. When you return a fat interface, you’ve already made that decision for them, and they’re stuck with it.

The one exception: returning error is an interface, and that’s intentional — it lets you return any error type, including custom ones. But error is a one-method interface, so the rule still holds in spirit.

Composing small interfaces when you need more

Sometimes a function genuinely needs multiple behaviors. Rather than reaching for a fat interface, compose:

type JobProcessor interface {
    JobGetter
    JobCompleter
}

func runWorker(id string, store JobProcessor) error {
    job, err := store.GetJob(id)
    if err != nil {
        return err
    }

    if err := doWork(job); err != nil {
        return store.MarkFailed(id, err)
    }

    return store.MarkComplete(id)
}

JobProcessor is defined at the call site, composed from two smaller interfaces, and PostgresJobStore satisfies it without modification. The test mock now only needs three methods.

Summary

Interface size — Avoid: 8-method interfaces defined upfront. Prefer: 1–3 method interfaces defined at the use site.

Where to define — Avoid: the producer side (the package that has the struct). Prefer: the consumer side (the package that calls the function).

What to return — Avoid: interfaces from constructors. Prefer: concrete types from constructors.

Complexity — Avoid: a single large interface. Prefer: composition of small interfaces.

Go’s implicit interface satisfaction is not just a syntactic convenience — it’s the mechanism that makes all of this work without coordination between packages. A type in one package can satisfy an interface defined in a completely different package, written years later, with no coupling between them.

The standard library’s one-method interfaces aren’t minimal because Go is simple. They’re minimal because the designers understood what implicit satisfaction makes possible.

Next in this series: Three Go concurrency mistakes I see in almost every worker pool.

Prototype Design Pattern in C#: Cloning Objects Efficiently

Mon, 22 Jun 2026 08:00:27 +0000

Introduction

The Prototype Design Pattern is a creational design pattern that allows new objects to be created by copying an existing object (called a prototype) instead of creating them from scratch.

This pattern is particularly useful when:

Object creation is expensive or complex.
Many similar objects need to be created.
You want to avoid repeatedly initializing the same data.

Instead of using constructors every time, the application clones an existing object and modifies only the necessary properties.

Understanding the Prototype Pattern

The Prototype pattern works around a simple idea:

"Create new objects by cloning existing objects."

A prototype object acts as a template. When a new object is needed, the application copies the prototype and customizes it.

Structure

The following class diagram illustrates the Prototype Pattern:

Components:

Prototype (BasicCar)
- Declares a cloning method.
- Defines the common interface for cloning.
Concrete Prototypes (Nano, Ford)
- Implement the cloning operation.
- Return copies of themselves.
Client (Program)
- Uses prototypes to create new objects.

Prototype Pattern Example in C

Abstract Prototype

public abstract class BasicCar
{
    public string ModelName { get; set; }
    public int Price { get; set; }

    public static int SetPrice()
    {
        int price = 0;
        Random r = new Random();
        int p = r.Next(200000, 500000);

        price = p;
        return price;
    }

    public abstract BasicCar Clone();
}

Explanation

BasicCar acts as the prototype base class.

It contains:

Common properties (ModelName, Price)
A utility method for generating random prices
An abstract Clone() method that subclasses must implement

Concrete Prototype: Ford

public class Ford : BasicCar
{
    public Ford(string m)
    {
        ModelName = m;
    }

    public override BasicCar Clone()
    {
        return (Ford)this.MemberwiseClone();
    }
}

Explanation

The Ford class inherits from BasicCar and implements the cloning logic.

return (Ford)this.MemberwiseClone();

This creates a copy of the current object using the built-in MemberwiseClone() method.

Client Code

Console.WriteLine("***Prototype Pattern Demo***\n");

// Base or Original Copy
BasicCar nano_base = new Nano("Green Nano")
{
    Price = 100000
};

BasicCar ford_base = new Ford("Ford Yellow")
{
    Price = 500000
};

BasicCar bc1;

// Nano Clone
bc1 = nano_base.Clone();
bc1.Price = nano_base.Price + BasicCar.SetPrice();

Console.WriteLine(
    "Car is: {0}, and it's price is Rs. {1}",
    bc1.ModelName,
    bc1.Price);

// Ford Clone
bc1 = ford_base.Clone();
bc1.Price = ford_base.Price + BasicCar.SetPrice();

Console.WriteLine(
    "Car is: {0}, and it's price is Rs. {1}",
    bc1.ModelName,
    bc1.Price);

Console.ReadLine();

How the Program Works

Step 1: Create Prototype Objects

BasicCar nano_base = new Nano("Green Nano");
BasicCar ford_base = new Ford("Ford Yellow");

These objects become the prototypes.

Step 2: Clone Instead of Creating

bc1 = nano_base.Clone();

Rather than creating a new Nano, we copy the existing one.

Step 3: Customize the Clone

bc1.Price = nano_base.Price + BasicCar.SetPrice();

The cloned object receives a different price while keeping the original model information.

Step 4: Repeat for Other Car Types

bc1 = ford_base.Clone();

The same cloning mechanism works for any prototype implementation.

Understanding `MemberwiseClone()`

The Prototype pattern in C# often relies on:

this.MemberwiseClone();

MemberwiseClone() is a protected method of System.Object.

It creates a shallow copy of the current object.

var copy = this.MemberwiseClone();

What Gets Copied?

Value Types

int
bool
double
struct

These are copied by value.

Original ----> 100
Clone    ----> 100

Changes to one do not affect the other.

Reference Types

List<string>
Address
Customer
Array

Only the reference is copied.

Original ---> Address Object
Clone ------^

Both objects point to the same instance.

Shallow Copy vs Deep Copy

The following comparison summarizes the difference:

Type	Meaning
Shallow Copy	Copies fields, but references stay shared
Deep Copy	Creates completely independent copies of all nested objects

Shallow Copy

public Person Clone()
{
    return (Person)this.MemberwiseClone();
}

Result:

Person A ---> Address
Person B ---^

Both persons share the same address object.

Deep Copy

public Person DeepClone()
{
    var copy = (Person)this.MemberwiseClone();

    copy.Address = new Address
    {
        City = this.Address.City
    };

    return copy;
}

Result:

Person A ---> Address A
Person B ---> Address B

Now each object has its own independent nested objects.

Is `MemberwiseClone()` Safe?

Yes, when:

Objects contain only value types.
Shared references are acceptable.
You manually clone reference-type members afterward.

Be Careful When:

Objects contain collections.
Objects contain nested objects.
Complete independence is required.

In those situations, implement a deep clone.

Benefits of the Prototype Pattern

1. Faster Object Creation

Cloning is often faster than constructing and initializing complex objects.

2. Reduces Repeated Initialization

Objects with many properties can be copied rather than rebuilt.

3. Simplifies Object Creation

Clients don't need to know all construction details.

4. Supports Runtime Object Creation

New objects can be created dynamically from existing prototypes.

Drawbacks

1. Deep Cloning Can Be Complex

Nested object graphs require extra cloning logic.

2. Shared References Can Cause Bugs

Using shallow copies incorrectly may lead to unexpected side effects.

3. Maintenance Overhead

Every new field may require updates to deep-cloning logic.

When Should You Use the Prototype Pattern?

Use Prototype when:

✅ Object creation is expensive

✅ Many similar objects are required

✅ Initialization logic is complex

✅ You need runtime object duplication

Examples include:

Game character templates
Vehicle configurations
Document templates
UI component libraries
Product catalogs

Conclusion

The Prototype Design Pattern is a powerful creational pattern that creates new objects by cloning existing ones. In C#, it is commonly implemented using MemberwiseClone(), which provides a fast and efficient way to perform shallow copies.

For simple objects, shallow cloning is often sufficient. However, when objects contain nested reference types, a deep clone should be implemented to ensure complete independence between the original object and its clone.

In the car example, Nano and Ford act as concrete prototypes, while BasicCar defines the cloning contract. The client can create new car instances efficiently by cloning existing prototypes instead of constructing them from scratch.

Exploring a Practical Billing API Built with Modern .NET Patterns

Wed, 17 Jun 2026 05:58:06 +0000

Exploring a Practical Billing API Built with Modern .NET Patterns

The Billing repository (https://github.com/stevsharp/Billing) is a practical example of how several common .NET architectural patterns can be combined within a billing-focused application.

Built with ASP.NET Core (https://learn.microsoft.com/aspnet/core/) and Entity Framework Core (https://learn.microsoft.com/ef/core/), the project demonstrates approaches that many teams use when building modern backend services.

A Clear Project Structure

The repository follows the principles of Clean Architecture, an approach that encourages clear separation between business logic, infrastructure, and application concerns.

Learn more about Clean Architecture:
https://github.com/jasontaylordev/CleanArchitecture

This separation helps keep responsibilities organized and makes it easier to understand where different pieces of functionality belong.

Focus on Business Rules

The project incorporates concepts from Domain-Driven Design (DDD), placing important business rules within the domain layer rather than spreading them across controllers and infrastructure code.

Learn more about Domain-Driven Design:
https://martinfowler.com/bliki/DomainDrivenDesign.html

This approach helps make business behavior more explicit and encourages a design where domain concepts remain central to the application.

Using CQRS in a Simple Way

The repository demonstrates Command Query Responsibility Segregation (CQRS), separating commands (operations that modify data) from queries (operations that retrieve data).

Learn more about CQRS:
https://martinfowler.com/bliki/CQRS.html

For developers interested in learning CQRS, the project provides a straightforward implementation that is relatively easy to follow.

Reliable Event Handling

The implementation includes the Outbox Pattern, a common technique used to improve reliability when publishing events from business operations.

Learn more about the Transactional Outbox Pattern:
https://microservices.io/patterns/data/transactional-outbox.html

This pattern helps address scenarios where database changes and event publication need to remain consistent.

Multi-Tenant Considerations

Many SaaS applications need to support multiple customers while keeping their data isolated. The project includes tenant-aware functionality using authentication claims and data filtering, providing a useful reference for developers exploring multi-tenant architectures.

Learn more about multitenancy:
https://learn.microsoft.com/azure/architecture/guide/multitenant/overview

Working with Entity Framework Core

The application uses Entity Framework Core for data access and persistence. Developers looking for practical examples of EF Core usage alongside architectural patterns may find the implementation useful to study.

Learn more about EF Core:
https://learn.microsoft.com/ef/core/

Building on ASP.NET Core

The API layer is built with ASP.NET Core, Microsoft's framework for building web APIs and cloud-native applications.

Learn more about ASP.NET Core:
https://learn.microsoft.com/aspnet/core/

Good Learning Resource

One of the strengths of the repository is that it brings together several widely used concepts and patterns:

Clean Architecture
Domain-Driven Design (DDD)
CQRS
Transactional Outbox Pattern
Multi-Tenant Design
JWT Authentication
Automated Testing

Rather than presenting these ideas in isolation, the project shows how they can work together in a cohesive application.

Conclusion

The Billing repository is a helpful reference for developers who want to explore modern .NET application design. It demonstrates several architectural patterns in a practical context while remaining approachable enough to study and adapt for other projects.

Repository:
https://github.com/stevsharp/Billing

Whether you're learning these concepts for the first time or looking for implementation examples, the project offers a useful starting point for further exploration.

Reflection architectural pattern

Mon, 15 Jun 2026 08:55:35 +0000

I published an article diving into the reflection architectural pattern. If you've ever wondered how Spring Boot uses annotations to magically wire your dependencies, or how ORMs map database fields without explicit code, reflection is the answer. I break down how this pattern actually works, show practical examples, and discuss when you should and shouldn't use it.

Read the full article

Refactoring a Simple C# Method Step by Step

Wed, 06 May 2026 08:58:22 +0000

Refactoring a Simple C# Method Step by Step

Refactoring is not about changing what the code does. It is about improving how the code is written.

The goal is to make the code easier to read, easier to test, and easier to maintain.

In this tutorial, we will refactor a simple user registration method step by step.

The Original Code

Imagine we have a method like this:

public void RegisterUser(string username, string password, int age, string email)
{
    if (username == null || username == "")
    {
        throw new Exception("Username is required");
    }

    if (password == null || password == "")
    {
        throw new Exception("Password is required");
    }

    if (password.Length < 8)
    {
        throw new Exception("Password must be at least 8 characters");
    }

    if (age < 18 || age > 120)
    {
        throw new Exception("Invalid age");
    }

    if (email == null || !email.Contains("@") || !email.Contains("."))
    {
        throw new Exception("Invalid email");
    }

    Console.WriteLine("User registered successfully!");
}

The code works, but it has some problems.

What Is Wrong With This Code?

The method has too many responsibilities.

It validates the username, password, age, and email. It also performs the registration logic.

This makes the method harder to read and harder to test.

Some other issues are:

Validation logic is mixed with business logic.
The method is becoming too long.
The same type of checks are repeated.
The validation rules cannot easily be reused.
The method uses primitive values everywhere, like string and int.

This is a common problem called primitive obsession.

It means we are using simple types like string, int, or decimal for values that have business meaning.

For example, an email is not just a string. A password is not just a string. They both have rules.

Step 1: Use Guard Clauses

A guard clause is a validation check placed at the beginning of a method.

If the input is invalid, the method stops immediately.

This is also called Fail Fast.

public void RegisterUser(string username, string password, int age, string email)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(username);
    ArgumentException.ThrowIfNullOrWhiteSpace(password);

    if (password.Length < 8)
        throw new ArgumentException("Password must be at least 8 characters.", nameof(password));

    if (age is < 18 or > 120)
        throw new ArgumentOutOfRangeException(nameof(age), "Age must be between 18 and 120.");

    if (!IsValidEmail(email))
        throw new FormatException("Invalid email format.");

    Console.WriteLine("User registered successfully!");
}

private bool IsValidEmail(string email)
{
    return !string.IsNullOrWhiteSpace(email)
           && email.Contains("@")
           && email.Contains(".");
}

This version is already better.

We improved the code by using:

Guard Clauses
Extract Method
Fail Fast

The IsValidEmail method makes the code easier to read because the email validation is separated from the main method.

Step 2: Use a Request Object

The method currently receives four parameters.

public void RegisterUser(string username, string password, int age, string email)

This is fine for small examples, but in real applications, this can become messy.

A better approach is to group the input into a request object.

public class UserRegistrationRequest
{
    public string Username { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
    public int Age { get; set; }
    public string Email { get; set; } = string.Empty;
}

Now the method becomes cleaner:

public void RegisterUser(UserRegistrationRequest request)
{
    ArgumentNullException.ThrowIfNull(request);

    ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
    ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

    if (request.Password.Length < 8)
        throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

    if (request.Age is < 18 or > 120)
        throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

    if (!IsValidEmail(request.Email))
        throw new FormatException("Invalid email format.");

    Console.WriteLine("User registered successfully!");
}

This uses the DTO pattern, or Data Transfer Object.

A DTO is useful when we want to pass data between layers, for example from the UI to the application layer.

Step 3: Extract Validation Into a Validator

The registration method still contains validation logic.

We can move that logic into a separate class.

public class UserRegistrationValidator
{
    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (request.Age is < 18 or > 120)
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

Now the registration method becomes very small:

public void RegisterUser(UserRegistrationRequest request)
{
    var validator = new UserRegistrationValidator();

    validator.Validate(request);

    Console.WriteLine("User registered successfully!");
}

This is much better.

The service now focuses on the registration process.

The validator focuses on validation.

This follows the Single Responsibility Principle.

Step 4: Inject the Validator

Creating the validator inside the method works, but it is not ideal for testing.

This line creates a direct dependency:

var validator = new UserRegistrationValidator();

A better approach is to inject the validator through the constructor.

First, create an interface:

public interface IUserRegistrationValidator
{
    void Validate(UserRegistrationRequest request);
}

Then update the validator:

public class UserRegistrationValidator : IUserRegistrationValidator
{
    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (request.Age is < 18 or > 120)
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

Now the service can receive the validator from dependency injection:

public class UserRegistrationService
{
    private readonly IUserRegistrationValidator _validator;

    public UserRegistrationService(IUserRegistrationValidator validator)
    {
        _validator = validator;
    }

    public void RegisterUser(UserRegistrationRequest request)
    {
        _validator.Validate(request);

        Console.WriteLine("User registered successfully!");
    }
}

This improves testability because we can mock the validator in unit tests.

Step 5: Use Value Objects for Stronger Domain Rules

In a more domain-driven design approach, we can create value objects.

For example, instead of passing email as a plain string, we create an Email type.

public sealed record Email
{
    public string Value { get; }

    public Email(string value)
    {
        if (string.IsNullOrWhiteSpace(value) ||
            !value.Contains("@") ||
            !value.Contains("."))
        {
            throw new FormatException("Invalid email format.");
        }

        Value = value;
    }

    public override string ToString() => Value;
}

We can do the same for password.

public sealed record Password
{
    public string Value { get; }

    public Password(string value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new ArgumentException("Password is required.", nameof(value));

        if (value.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(value));

        Value = value;
    }
}

Now the method can receive stronger types:

public void RegisterUser(string username, Password password, int age, Email email)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(username);

    if (age is < 18 or > 120)
        throw new ArgumentOutOfRangeException(nameof(age), "Age must be between 18 and 120.");

    Console.WriteLine("User registered successfully!");
}

This is powerful because invalid email or password values cannot exist in the system.

The validation happens when the object is created.

Step 6: Use the Specification Pattern for Complex Rules

Sometimes validation rules become more complex.

For example, age validation may start simple:

if (age is < 18 or > 120)
    throw new ArgumentOutOfRangeException(nameof(age));

But later, the rule may change depending on the country, user type, subscription, product, or business scenario.

In that case, we can move the rule into a separate specification class.

The Specification Pattern allows us to define business rules as reusable objects.

public interface ISpecification<T>
{
    bool IsSatisfiedBy(T entity);
}

Now we can create a specific rule for age validation:

public class AgeSpecification : ISpecification<int>
{
    public bool IsSatisfiedBy(int age)
    {
        return age is >= 18 and <= 120;
    }
}

Then we can use it inside our validator:

public class UserRegistrationValidator
{
    private readonly ISpecification<int> _ageSpecification;

    public UserRegistrationValidator(ISpecification<int> ageSpecification)
    {
        _ageSpecification = ageSpecification;
    }

    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (!_ageSpecification.IsSatisfiedBy(request.Age))
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

This gives us a cleaner and more flexible design.

If the age rule changes later, we do not need to modify the validator directly. We can create a new specification.

For example:

public class AdultUserSpecification : ISpecification<UserRegistrationRequest>
{
    public bool IsSatisfiedBy(UserRegistrationRequest request)
    {
        return request.Age >= 18;
    }
}

Or we can create a more complete business rule:

public class ValidUserRegistrationSpecification : ISpecification<UserRegistrationRequest>
{
    public bool IsSatisfiedBy(UserRegistrationRequest request)
    {
        return !string.IsNullOrWhiteSpace(request.Username)
               && !string.IsNullOrWhiteSpace(request.Password)
               && request.Password.Length >= 8
               && request.Age is >= 18 and <= 120
               && !string.IsNullOrWhiteSpace(request.Email)
               && request.Email.Contains("@")
               && request.Email.Contains(".");
    }
}

The Specification Pattern is useful when:

Business rules are complex.
Rules change often.
Rules must be reused in different places.
Rules need to be combined.
You want to avoid large if statements inside services.

For simple validation, a validator is usually enough.

For complex domain rules, the Specification Pattern gives you more flexibility.

Patterns used here:

Specification Pattern
Open/Closed Principle
Single Responsibility Principle

Step 7: Use Result Instead of Exceptions

Exceptions are fine for unexpected errors.

But in APIs, UI forms, and validation-heavy workflows, returning a result can sometimes be cleaner.

public record Result(bool Success, string Error)
{
    public static Result Ok() => new(true, string.Empty);

    public static Result Fail(string error) => new(false, error);
}

Now the registration method can return a result:

public Result RegisterUser(UserRegistrationRequest request)
{
    if (string.IsNullOrWhiteSpace(request.Username))
        return Result.Fail("Username is required.");

    if (string.IsNullOrWhiteSpace(request.Password))
        return Result.Fail("Password is required.");

    if (request.Password.Length < 8)
        return Result.Fail("Password must be at least 8 characters.");

    if (request.Age is < 18 or > 120)
        return Result.Fail("Age must be between 18 and 120.");

    if (!IsValidEmail(request.Email))
        return Result.Fail("Invalid email format.");

    return Result.Ok();
}

private static bool IsValidEmail(string email)
{
    return !string.IsNullOrWhiteSpace(email)
           && email.Contains("@")
           && email.Contains(".");
}

This is useful when you do not want validation failures to throw exceptions.

It is especially useful in:

APIs
Blazor forms
MVC forms
CQRS command handlers
UI validation flows

Final Recommended Version

For a real application, a clean structure would look like this:

public class UserRegistrationService
{
    private readonly IUserRegistrationValidator _validator;

    public UserRegistrationService(IUserRegistrationValidator validator)
    {
        _validator = validator;
    }

    public void RegisterUser(UserRegistrationRequest request)
    {
        _validator.Validate(request);

        Console.WriteLine("User registered successfully!");
    }
}

public interface IUserRegistrationValidator
{
    void Validate(UserRegistrationRequest request);
}

public class UserRegistrationValidator : IUserRegistrationValidator
{
    private readonly ISpecification<int> _ageSpecification;

    public UserRegistrationValidator(ISpecification<int> ageSpecification)
    {
        _ageSpecification = ageSpecification;
    }

    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (!_ageSpecification.IsSatisfiedBy(request.Age))
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

public interface ISpecification<T>
{
    bool IsSatisfiedBy(T entity);
}

public class AgeSpecification : ISpecification<int>
{
    public bool IsSatisfiedBy(int age)
    {
        return age is >= 18 and <= 120;
    }
}

public class UserRegistrationRequest
{
    public string Username { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
    public int Age { get; set; }
    public string Email { get; set; } = string.Empty;
}

Summary

Refactoring Technique	What It Improves
Guard Clauses	Makes validation clearer
Extract Method	Makes code easier to read
DTO	Groups related input data
Validator Pattern	Separates validation from business logic
Dependency Injection	Improves testability
Value Objects	Protects domain integrity
Specification Pattern	Makes complex rules reusable
Open/Closed Principle	Allows adding new rules without changing existing code
Result Pattern	Works well for APIs and UI flows
Single Responsibility Principle	Keeps classes focused

Conclusion

The best refactoring is not always the most advanced one.

Start simple.

First, use guard clauses.

Then extract repeated logic into methods.

After that, move validation into its own class.

When the domain becomes more important, consider value objects.

When business rules become more complex, consider the Specification Pattern.

And when working with APIs or UI forms, consider returning a result instead of throwing exceptions for expected validation failures.

A good refactor should make the code easier to understand without making it unnecessarily complicated.

Understanding the Producer-Consumer Pattern in C#

Tue, 28 Apr 2026 09:15:07 +0000

Understanding the Producer-Consumer Pattern in C Sharp

The Producer-Consumer pattern is one of the most common patterns in concurrent programming.

In simple English, it means this:

One part of the program creates work.
Another part of the program processes that work.

The part that creates work is called the Producer.
The part that processes work is called the Consumer.

Between them, there is usually a shared queue.

private static readonly Queue<int> _queue = new();

The producer adds items into the queue, and the consumer removes items from the queue.

A real-life example

Imagine a kitchen.

The chef prepares meals and places them on the counter.
The waiter takes meals from the counter and serves them to customers.

The chef is the Producer.
The waiter is the Consumer.
The counter is the Queue.

But there is one problem.

The counter has limited space.

If the counter is full, the chef must wait before placing more meals.
If the counter is empty, the waiter must wait before taking anything.

That is exactly what the Producer-Consumer pattern solves.

It helps two parts of a system work together safely, even when they work at different speeds.

The code example

public sealed class ProducerConsumer
{
    private static readonly Queue<int> _queue = new();

    private const int MaxSize = 5;

    private static readonly SemaphoreSlim _itemsAvailable = new(0);

    private static readonly SemaphoreSlim _spaceAvailable = new(MaxSize);

    private static readonly object _lock = new();

    public async Task Producer(int id, int count)
    {
        for (int i = 0; i < count; i++)
        {
            await _spaceAvailable.WaitAsync();

            lock (_lock)
            {
                _queue.Enqueue(i);

                Console.BackgroundColor = ConsoleColor.Green;
                Console.WriteLine($"Producer {id} produced {i}");
                Console.ResetColor();
            }

            _itemsAvailable.Release();

            Console.WriteLine($"Producer {id} waiting for space...");

            await Task.Delay(300);
        }
    }

    public async Task Consumer(int id)
    {
        while (true)
        {
            await _itemsAvailable.WaitAsync();

            int item;

            lock (_lock)
            {
                item = _queue.Dequeue();

                Console.BackgroundColor = ConsoleColor.Red;
                Console.WriteLine($"Consumer {id} consumed {item}");
                Console.ResetColor();
            }

            _spaceAvailable.Release();

            Console.WriteLine($"Consumer {id} waiting for items...");

            await Task.Delay(500);
        }
    }

    public async Task Run()
    {
        var producer = Producer(1, 10);

        var consumer = Consumer(1);

        await producer;

        await Task.Delay(3000);
    }
}

What this code does

This example creates a small queue that can hold up to 5 items.

private const int MaxSize = 5;

The producer creates numbers and adds them into the queue.

_queue.Enqueue(i);

The consumer takes numbers from the queue.

item = _queue.Dequeue();

So the flow is:

Producer -> Queue -> Consumer

The producer does not directly give the item to the consumer.

Instead, it places the item into the queue.

The consumer then takes the item from the queue when it is ready.

This is useful because the producer and consumer do not need to work at the exact same speed.

Why the queue has a maximum size

The queue has a maximum size of 5.

private const int MaxSize = 5;

That means the producer is not allowed to keep adding items forever.

If the queue becomes full, the producer must wait.

This is important because, in real applications, unlimited queues can become dangerous. If a producer creates work faster than consumers can process it, memory usage can grow too much.

A bounded queue helps apply back pressure.

Back pressure means:

The producer is slowed down when the system cannot process work fast enough.

This keeps the system more stable.

What is `SemaphoreSlim`?

SemaphoreSlim is a lightweight synchronization tool in .NET.

In simple English, it is like a counter that controls how many operations are allowed to continue.

In this example, we use two semaphores:

private static readonly SemaphoreSlim _itemsAvailable = new(0);

private static readonly SemaphoreSlim _spaceAvailable = new(MaxSize);

The first one is _itemsAvailable.

private static readonly SemaphoreSlim _itemsAvailable = new(0);

It starts at 0 because, at the beginning, the queue is empty.

So the consumer must wait here:

await _itemsAvailable.WaitAsync();

This means:

Wait until at least one item is available.

The second one is _spaceAvailable.

private static readonly SemaphoreSlim _spaceAvailable = new(MaxSize);

It starts at MaxSize, which is 5.

That means, at the beginning, the queue has 5 free spaces.

So the producer waits here:

await _spaceAvailable.WaitAsync();

This means:

Wait until there is free space in the queue.

Microsoft’s documentation explains that Wait or WaitAsync enters the semaphore and decreases its count, while Release increases the count again. When the count reaches zero, new waiters must wait until something releases the semaphore. (Microsoft Learn)

How the producer works

The producer first waits for free space:

await _spaceAvailable.WaitAsync();

If there is space, it enters the lock block and adds an item to the queue:

lock (_lock)
{
    _queue.Enqueue(i);
}

Then it releases _itemsAvailable:

_itemsAvailable.Release();

This tells the consumer:

One item is now available.

So the producer flow is:

Wait for space
Add item to queue
Signal that an item is available

How the consumer works

The consumer first waits for an item:

await _itemsAvailable.WaitAsync();

If an item is available, it enters the lock block and removes the item from the queue:

lock (_lock)
{
    item = _queue.Dequeue();
}

Then it releases _spaceAvailable:

_spaceAvailable.Release();

This tells the producer:

One space is now free.

So the consumer flow is:

Wait for item
Remove item from queue
Signal that space is available

Why do we still need `lock`?

The semaphores control when the producer and consumer can continue.

But they do not protect the queue itself.

The queue is shared between the producer and the consumer:

private static readonly Queue<int> _queue = new();

Queue<T> is not thread-safe by itself. If two threads try to access it at the same time, we can get incorrect behavior.

That is why we use a lock:

private static readonly object _lock = new();

The lock statement makes sure that only one thread enters the protected block at a time. Microsoft’s C# documentation describes lock as a way to ensure that only a single thread exclusively reads or writes a shared resource. (Microsoft Learn)

So this code is protected:

lock (_lock)
{
    _queue.Enqueue(i);
}

And this code is also protected:

lock (_lock)
{
    item = _queue.Dequeue();
}

One important rule is that we should not use await inside a lock block. The C# documentation explicitly says that await cannot be used inside the body of a lock statement. (Microsoft Learn)

That is why this code is correct:

await _spaceAvailable.WaitAsync();

lock (_lock)
{
    _queue.Enqueue(i);
}

The async waiting happens before the lock, not inside it.

Other options instead of `lock`

In this example, lock is the best simple option.

But there are other synchronization tools we can use.

Option 1: `Monitor`

In C#, lock is actually a cleaner syntax over Monitor.

This:

lock (_lock)
{
    _queue.Enqueue(i);
}

is similar to this:

Monitor.Enter(_lock);

try
{
    _queue.Enqueue(i);
}
finally
{
    Monitor.Exit(_lock);
}

Microsoft’s documentation explains that Monitor.Enter and Monitor.Exit provide functionality equivalent to the C# lock statement, but the language syntax wraps the logic in a try/finally block so the monitor is released safely. (Microsoft Learn)

Monitor gives you more manual control.

For example, you can use Monitor.TryEnter if you do not want to wait forever:

if (Monitor.TryEnter(_lock))
{
    try
    {
        _queue.Enqueue(i);
    }
    finally
    {
        Monitor.Exit(_lock);
    }
}

Use Monitor when you need extra control, for example:

Try to enter without waiting forever
Use timeout logic
Manually control entering and exiting

For normal code, lock is usually better because it is shorter, cleaner, and less error-prone.

Option 2: `Mutex`

A Mutex also gives exclusive access to one thread at a time.

Example:

private static readonly Mutex _mutex = new();

_mutex.WaitOne();

try
{
    _queue.Enqueue(i);
}
finally
{
    _mutex.ReleaseMutex();
}

The important difference is that a Mutex can also be used across processes.

For example, if two different applications on the same machine need to access the same file, a named Mutex can help coordinate them.

private static readonly Mutex _mutex = new(false, "Global\\MyProducerConsumerMutex");

Microsoft’s documentation says that Mutex can provide exclusive access to a resource, uses more system resources than Monitor, and can synchronize threads in different processes. It also explains that named system mutexes are visible throughout the operating system and can be used to synchronize process activity. (Microsoft Learn)

Use Mutex when different processes need to coordinate access to the same resource.

For normal synchronization inside one application, prefer lock or Monitor.

Why this pattern is useful

The Producer-Consumer pattern is useful when one part of the system produces work and another part processes it.

Some real-world examples are:

Background job processing
Logging systems
File processing
Message queues
Image processing
Email sending
Report generation
Data pipelines
Server request handling

For example, imagine an application that receives uploaded files.

One part of the application accepts the files.
Another part processes them in the background.

Instead of processing everything immediately, the application can place each file into a queue.

Then one or more consumers can process the files one by one.

This keeps the application responsive.

One issue with the current code

The current consumer runs forever:

while (true)

That is okay for a learning example, but in real production code, we usually want a clean way to stop the consumer.

For example, we could use:

CancellationToken
A special final message
Channel completion
BlockingCollection.CompleteAdding()

Without a stopping mechanism, the consumer keeps waiting forever, even after the producer has finished.

Alternatives to this approach

The manual version is great for learning because it shows what happens behind the scenes.

But in real applications, .NET gives us higher-level tools.

Alternative 1: `Channel<T>`

For modern async code, Channel<T> is usually the best alternative.

System.Threading.Channels provides synchronization structures for passing data between producers and consumers asynchronously. Microsoft’s documentation describes channels as an implementation of the producer-consumer model, where producers asynchronously produce data and consumers asynchronously consume it through a FIFO queue. (Microsoft Learn)

Example:

var channel = Channel.CreateBounded<int>(5);

Producer:

await channel.Writer.WriteAsync(item);

Consumer:

var item = await channel.Reader.ReadAsync();

With Channel<T>, we do not need to manually combine:

Queue<T> + lock + SemaphoreSlim

The channel already handles much of that logic for us.

A bounded channel can also apply back pressure. When the channel reaches its capacity, the default behavior is that WriteAsync waits until space becomes available. (Microsoft Learn)

Use Channel<T> when you are building:

Async background workers
Job queues
Pipelines
Producer-consumer services
High-throughput async processing

For modern .NET applications, this is usually the cleanest option.

Alternative 2: `BlockingCollection<T>`

BlockingCollection<T> is another producer-consumer tool in .NET.

Microsoft describes BlockingCollection<T> as a thread-safe collection that implements the Producer-Consumer pattern, supports concurrent adding and taking from multiple threads, supports optional maximum capacity, and can block when the collection is empty or full. (Microsoft Learn)

Example:

var collection = new BlockingCollection<int>(boundedCapacity: 5);

Producer:

collection.Add(item);

Consumer:

var item = collection.Take();

This is simpler than manually writing semaphore logic.

However, BlockingCollection<T> is mainly blocking-based. That makes it useful for classic threaded code, but less ideal for modern async workflows.

For async code, Channel<T> is usually a better fit.

Alternative 3: `ConcurrentQueue<T>`

ConcurrentQueue<T> is a thread-safe FIFO queue.

It allows multiple threads to safely enqueue and dequeue items without manually using lock. Microsoft’s documentation describes it as a thread-safe first in, first out collection and states that its public and protected members are thread-safe and can be used concurrently from multiple threads. (Microsoft Learn)

Example:

private static readonly ConcurrentQueue<int> _queue = new();

Producer:

_queue.Enqueue(item);

Consumer:

if (_queue.TryDequeue(out var item))
{
    Console.WriteLine(item);
}

This removes the need for a manual lock.

However, ConcurrentQueue<T> does not automatically wait when the queue is empty. It also does not automatically block producers when the queue is full.

So if you need waiting behavior, you still need another signal mechanism, or you can use Channel<T> instead.

Alternative 4: `Semaphore`

Semaphore is the older and heavier version compared with SemaphoreSlim.

Both are counting synchronization primitives, but Semaphore can be useful when system-wide synchronization is needed. Microsoft’s documentation explains that a Semaphore uses WaitOne, while SemaphoreSlim uses Wait or WaitAsync. (Microsoft Learn)

Use Semaphore when you need cross-process counting synchronization.

For normal async code inside one application, prefer SemaphoreSlim.

Which option should you use?

Option	Best use case
`lock`	Simple in-process protection of shared data
`Monitor`	Same idea as `lock`, but with more manual control
`Mutex`	Cross-process exclusive locking
`SemaphoreSlim`	Async-friendly in-process counting synchronization
`Semaphore`	Cross-process counting synchronization
`Queue<T>` + `lock` + `SemaphoreSlim`	Learning how the pattern works internally
`Channel<T>`	Modern async producer-consumer workflows
`BlockingCollection<T>`	Classic blocking producer-consumer workflows
`ConcurrentQueue<T>`	Thread-safe queue operations without waiting logic

For this specific article, the manual approach is perfect because it teaches the mechanics.

For production code, especially in modern .NET, I would usually prefer Channel<T>.

Final summary

The Producer-Consumer pattern helps two parts of an application work together safely.

The producer creates work.
The consumer processes work.
The queue stores work temporarily.
The semaphores control when each side is allowed to continue.
The lock protects the shared queue from unsafe access.

In this example:

Producer -> Queue -> Consumer

_spaceAvailable protects the queue from becoming too full.

await _spaceAvailable.WaitAsync();

_itemsAvailable protects the consumer from reading an empty queue.

await _itemsAvailable.WaitAsync();

lock protects the queue itself.

lock (_lock)
{
    _queue.Enqueue(i);
}

Monitor can be used when we need more manual control.

Monitor.Enter(_lock);

try
{
    _queue.Enqueue(i);
}
finally
{
    Monitor.Exit(_lock);
}

Mutex can be used when different processes need to coordinate access to the same resource.

private static readonly Mutex _mutex = new(false, "Global\\MyProducerConsumerMutex");

This is a simple but powerful pattern.

Once you understand it, tools like Channel<T>, BlockingCollection<T>, ConcurrentQueue<T>, Monitor, and Mutex become much easier to understand.

References

Microsoft documentation for SemaphoreSlim, Semaphore, lock, Monitor, Mutex, Channel<T>, BlockingCollection<T>, and ConcurrentQueue<T> was used as the technical reference for this article. (Microsoft Learn)

Don’t Pass Array or Variables to Laravel Blade Views Instead Do This

Wed, 08 Apr 2026 10:20:36 +0000

Are you a Laravel developer. Do you love Blade. It’s simple, expressive, and fits naturally with the framework. But let’s be honest, most projects eventually turn their Blade files into dumping grounds for random variables. The Controllers pass loose data, views end up receiving unstructured data, partials rely on implicit assumptions, and the whole setup becomes fragile and error-prone.

The Result?

No autocomplete.
Runtime errors from typos.
Partial views with zero contracts.
A mess that only grows as the app scales.

It doesn’t have to be this way. Blade files deserve the same contracts and structure we give to APIs, database models, or services. With a few clear practices, you can bring discipline, contracts, and structure to Blade.

This article will show you the complete approach.

The problem of passing data as arrays or variables in views — solved by introducing ViewModels as contracts.
Enable Autocomplete in Blade so your IDE actually helps.
Annotation to views and partials bound to their own ViewModels.
Lock down data structures with DTO classes for strict typing.
Establish Principles for sustainable Blade development.

Remember, we are only targeting blade for now. Not Twig or Antlr.

Grab a coffee — this is a long read. But by the end, you’ll never look at Blade the same way again.

The Crime Scene: What’s Wrong With “Array Soup” in Blade

Here’s the standard Laravel approach we’ve all seen in controllers.

class ProductController extends Controller
{
    public function index()
    {
		$products = Product::all();
		$categories = Category::all();
		$brand = Brand::all();
        $title = 'Products';
		
		return view('products.index', compact('products','categories','brands','title') );
    }
}

// Or may be

class ProductController extends Controller
{
    public function index()
    {
        return view('products.index', [
            'title' => 'Products',
            'products' => Product::all(),
            'categories' => Category::all(),
            'brand' => Brand::all(),	
        ]);
    }
}

// Or a little cleaner approach

class ProductController extends Controller
{
    public function index()
    {
		$data = [
            'title' => 'Products',
            'products' => Product::all(),
            'categories' => Category::all(),
            'brand' => Brand::all(),	
		];
		
		return view('products.index', $data);
    }
}

And here is how we do it for partials.

// pass no data, access product from current blade context inside partials/product.blade.php
@foreach ($products as $product)
    @include('products.partials.product')
@endforeach

// or pass some additional data
@foreach ($products as $product)
    @include('products.partials.product', ['editable' => $editable])
@endforeach

And finally for components.

@foreach ($products as $product)
    <x-product-row :name="$product->name" :price ="$product->price" />
@endforeach

The Old Lovely Blade

Here is how it works well.

<h1>{{ $title }}</h1>

<ul>
    @foreach ($products as $product)
        <li>{{ $product->name }} ({{ $product->price }})</li>
        {{-- or partial --}}
        @include('products.partials.product')        
        {{-- or component --}}
        <x-product-row :name="$product->name" :price ="$product->price" />
    @endforeach
</ul>

This works but ask yourself:

Do you actually remember all the variables passed to your views?
Do you get autocomplete in Blade to help you catch typos?
What about partials and includes — are you sure the data they rely on is really there?
If a teammate edits the controller, how do you even know the view won’t silently break?
How many times have you opened a Blade file and had no clue what’s in scope?

1. Introducing ViewModels: Contracts for Your Views

Instead of throwing arrays around, define a ViewModel, a simple DTO class. It declares exactly what data is expected.

<?php

namespace App\ViewModels;


class ProductsViewModel
{
    public string $title;
    public array $products;
    public array $categories;
    public array $brand;    
}

And controller.

class ProductController extends Controller
{
    public function index()
    {
        $viewModel = new ProductsViewModel();

        $viewModel->title = 'Products';
        $viewModel->products = Product::all();
        $viewModel->categories = Category::all();
        $viewModel->brands = Brand::all();        

        return view('products.index', ['model' => $viewModel]);
    }
}

Suggestion: Always pass view-model with name model for consistancy. This will help in autocomplete.

Now blade file will look like this.

<h1>{{ $model->title }}</h1>

<ul>
    @foreach ($model->products as $product)
        <li>{{ $product->name }} ({{ $product->price }})</li>
        {{-- or partial  --}}
        @include('products.partials.product',['model' => $product])  
        {{-- or component --}}
        <x-product-row :model="$product" />
    @endforeach
</ul>

@include('partials.brands', ['model' => $model->brands])
@include('partials.categories', ['model' => $model->categories])

Suggestion**: For partials and components, always pass data with name model** for consistancy. This will help in autocomplete._

Benefits:

The contract is explicit.
Adding or removing data requires updating the ViewModel.
Each view, partial or component has a single data access point $model to start with.

2. Installing Extension for Autocomplete

This step does not require any code setup but requires installing plugin/extension in your IDE. I use VS Code for Laravel development. I found an excellent extension PHP Tools by DevSense for VS Code which I used to use in Visual Studio when working with .Net framework. This extension is available for Cursor, Zed ,Visual Studio and VS Code. But if you are using a different editor you need to find similar extension.

Once installed we need to move to next step. Take a look at the feature list to find what's available.

Note: When installing PHP Tools I had to ditch Intellisense and Intelliphence but I still get all what they provide with PHP Tools.

3. Enabling Autocomplete in Blade

Even with ViewModels, Blade doesn’t automatically know the type of `$model`. The trick is to annotate it in blade views, partials and components:

// views/products/index.blade.php
@php
    /** @var \App\ViewModels\ProductsViewModel $model */
@endphp

<ul>
    @foreach ($model->products as $product)
        <li>{{ $product->name }} ({{ $product->price }})</li>
        {{-- or partial  --}}
        @include('products.partials.product')  
        {{-- or component --}}
        <x-product-row :name="$product->name" :price ="$product->price" />
    @endforeach
</ul>

You need to do same in partial or component. Here is partial.

// views/products/partials/product.blade.php
@php
    /** @var \App\Models\Product $model */
@endphp

<span>
    {{ $model->name }}
</span>

Finally, a component.

// views/components/product.blade.php
@php
    /** @var \App\View\Components\Product $model */
@endphp

<span>
    {{ $model->name }}
</span>

Now, in VS Code, typing `$model->` will bring up real autocomplete suggestions.

This is a game-changer:

No more guessing property names.
Mistyped variables get caught instantly.
New developers know exactly what’s available in the view.

4. Enforce Types at Runtime

Since now we are passing ViewModels into views, partials or components and defining annonations in each blade file, lets enforce blade to accept specific type of class. To do this i added two files.

TypedViewFactory – A custom view factory that parses `@var` declarations at the top of Blade files and enforces them.
TypedViewServiceProvider – Wires everything into Laravel automatically.

Checkout the code here.

The Result: if you declare a type in a Blade file, Laravel must pass the correct class, array, or collection. Otherwise, it throws an exception.

Declaring Types in Blade makes views predictable and strict.

Main View

{{-- products/index.blade.php --}}
@php /** @var App\ViewModels\ProductsViewModel $model */ @endphp
<h1>{{ $model->title }}</h1>

Only `ProductsViewModel` works — anything else throws an exception.

Partial

{{-- products/partials/product.blade.php --}}
@php 
    /** @var App\Models\Product $model */ 
@endphp
<div>{{ $model->title }}</div>

The partial now demands a `Post` instance, not random data.

Component

// views/components/product.blade.php
@php
    /** @var \App\View\Components\Product $model */
@endphp

<span>
    {{ $model->name }}
</span>

The component demands Product class instance now.

You can do the same with arrays and collection or other primitive types.

// example of array
@php 
    /** @var App\Models\Product[] $model*/ 
@endphp

// Or collection
@php 
    /** @var \Illuminate\Support\Collection<App\Models\Product> $model */ 
@endphp

Now if wrong type data is passed it will throw the error.

View [products] expects $model of type App\ViewModels\ProductsViewModel, 
but got string.

Similiarly, partials and components will throw the error if passed wrong type of data.

5. Going Fully Typed With DTO Classes

So far, we’ve wrapped data in ViewModels, but what about the data itself? Passing raw Eloquent models to views can be risky — they carry too much baggage and autocomplete will present you a jungle of eloquent methods along with model properties and we will have to stuggle finding properties again . To counter this issue, let's create DTO Classes to describe exactly what's needed.

Note: Since component itself can act as DTO class and carry specific properties, it does not need additional DTO class.

Lets create a BaseDTO class to define some common methods.

<?php

namespace App\DTO;

use InvalidArgumentException;

abstract class BaseDTO
{
    public function __construct(array $data = [])
    {
        foreach ($data as $key => $value) {
            if (!property_exists($this, $key)) {
                throw new InvalidArgumentException(
                    "Property '{$key}' is not defined in " . static::class
                );
            }
            $this->$key = $value;
        }
    }

    public function __get($name)
    {
        throw new InvalidArgumentException(
            "Tried to access undefined property '{$name}' on " . static::class
        );
    }

    public function __set($name, $value)
    {
        throw new InvalidArgumentException(
            "Tried to set undefined property '{$name}' on " . static::class
        );
    }

    public static function columns(): array
    {
        return array_map(
            fn($prop) => $prop->getName(),
            (new \ReflectionClass(static::class))->getProperties()
        );
    }
}

Now our actual SimpleProduct.php class to define only specific properties required for blade view or partial.

<?php

namespace App\DTO\Product;

use App\DTO\BaseDTO;

class SimpleProduct extends BaseDTO
{
    public string $name;
    public string $image;
    public float $price;
    public int $stock;
}

And here's our controller now.

class ProductController extends Controller
{
    public function index()
    {
        $viewModel = new ProductsViewModel();

        $viewModel->products = Product::select(SimpleProduct::columns())->get();
        // other code      

        return view('products.index', ['model' => $viewModel]);
    }
}

And in partial instead of defining Eloquent model as annotation define DTO class as annotation.

// views/products/partials/product.blade.php
@php
    /** @var \App\DTO\Product\SimpleProduct $model */
@endphp

<span>
    {{ $model->name }}
</span>

Now autcomplete will present you only DTO properties.

But wait. There's some issue. We passed Eloquent model but annotating DTO class. How's that supposed to work?

Pay attention on what we selected. Only sepecific columns right. So even though we passed eloquent, due to annotation we will be able to see only DTO properties. But we have to follow one condition.

Suggestion: DTO class properties must be same as Eloquent model columns.

Now here are some points to consider when working this approach.

Strict Enforcement

If you only select `DTO::columns()` in your query and pass raw models to Blade, IDE autocomplete will still work (thanks to the DTO annotation). But at runtime, Blade can still access any hidden column, relation, or accessor. To enforce discipline beyond autocomplete, wrap results into DTOs.

Schema Drift Protection

If a DTO includes a property that doesn’t exist in the table, MySQL will fail loudly with “Unknown column error”. This is actually a feature — it ensures your DTOs always stay in sync with the schema instead of drifting silently.

Losing Eloquent Helpers

DTOs are deliberately "dumb" carriers. Any accessors, relations, or helpers from your Eloquent models are gone. Prepare and transform data in the controller or service layer before converting to DTOs. Views should only see the minimal contract they need.

Mapping Overhead

Mapping into DTOs isn’t as heavy as it sounds. With a `BaseDTO` base and a mapper helper, it’s just one extra line in the query pipeline. Think of it as casting: you do it once, and the rest of your view logic becomes predictable and safe.

A Generic DTO mapper

class DTOMapper
{
    public static function map(object $source, string $dtoClass): object
    {
        $dtoReflection = new ReflectionClass($dtoClass);
        $properties = $dtoReflection->getProperties();

        $args = [];

        foreach ($properties as $property) {
            $name = $property->getName();

            if (isset($source->$name)) {
                $args[$name] = $source->$name;
            }
        }

        return new $dtoClass(...$args);
    }
}

Example implementation.

// For models
$dto = DTOMapper::map($product, SimpleProduct::class);

// for arrays or collection
$dtos = $products->map(fn($p) => DTOMapper::map($p, ProductDTO::class));

Principles of Structured Blade

This approach only holds up if you enforce some ground rules:

No untyped arrays in views Passing raw arrays to Blade is outlawed. Every view should receive a single, typed contract.
One ViewModel per Blade file Keep the mental load low. A view gets exactly one entry point: its ViewModel.
Partials and components need contracts too Even the tiniest include deserves its own ViewModel. Contracts everywhere, no freeloaders.
Always annotate with @var Autocomplete is non-negotiable. Every Blade file starts with a `@var` docblock.
Always pass data as model for consistancy Every view, partial or component must be passed viewmodel as $model so that all blade views has single entry point to start with.
Business logic stays out of Blade Views format and render. Data shaping, conditions, and prep all belong in the ViewModel.
Use DTOs to avoid Eloquent jungle Keep Eloquent in the backend. Views should only see pure, predictable DTOs.
Strict access, fail loudly If a property isn’t defined in the ViewModel, the view should throw—no guessing, no silent nulls.

Final Word

Blade isn’t broken. The way most developers use it is.

Treating Blade files as unstructured trash bins creates brittle, unmaintainable code. Adding ViewModels, autocomplete, partial contracts, and DTOs gives your views the same level of professionalism as the rest of your codebase.

This isn’t overkill. It’s discipline. And discipline is what separates fragile projects from sustainable ones.

So stop passing arrays. Start passing contracts. Give your Blade files the structure they deserve.

If you found this post helpful, consider supporting my work — it means a lot.

Support my work

Introducing The Atomic Query Construction (AQC) Design Pattern

Wed, 08 Apr 2026 10:17:35 +0000

When I started my career as a developer, one of my senior team members used to construct queries in core PHP using concatenation based on different parameters. Once the construction was complete, he would echo it for different use cases and run it in PHPMyAdmin or SQLyog. Once satisfied, he’d move on. I always liked the way he built those queries.

Later, when I moved on to CodeIgniter and eventually Laravel, I noticed something: Developers often write SQL or ORM-based queries buried deep inside controllers, services, views, event listeners — even helpers. This scattered approach leads to redundancy and painful maintenance. We’ve all seen this.

This always bugged me. Why repeat the same logic scattered across the application when it can be centralized?

Being an OOP geek, I finally settled on a pattern that works cleanly and elegantly. To counter this problem, I am introducing a new design principle: Atomic Query Construction — or AQC. It’s a design approach where each query lives in its own class. You write it once and use it everywhere. It’s structured, predictable, and aligned with better software design principles.

What is AQC?

AQC stands for Atomic Query Construction. At its core, it’s a principle of isolating each query into its own class. Each of these classes:

Accepts Parameters
Constructs Query based on those parameters for different use cases
Returns Results

You only call this class whenever that specific query is needed — nothing else. It becomes the single source of truth for that operation.

Rules of the Pattern

1. One Class, One Responsibility

Every class should focus on a single, well-defined query. Stick to the Single Responsibility Principle (SRP).

2. Accept Parameters

Each class should accept parameters — filters, identifiers, flags — whatever’s needed to shape the query dynamically.

3. Construct the Query Internally

Based on the parameters, the class should build and return a query.

4. Single Source of Truth

Anywhere in the app where you need this data — whether in a controller, event, or service — call this class. Do NOT rewrite the query logic elsewhere.

5. Handle Method

Each class should expose a single public method, handle(). It can have private helpers internally, but the interface stays clean.

6. Consistent Naming

Class names must be clear and consistent. For a resource like Product, your AQC classes might be:

GetAllProducts
GetProduct
StoreProduct
UpdateProduct
DeleteProduct

Benefits

Modular: Every query is isolated and self-contained. You know exactly where to look when changes are needed.
Reusable: Once written, the query class can be reused across the app with different params or use cases.
Flexible: It supports multiple scenarios (admin view, frontend listing, etc.) using dynamic input.
Clean Separation: Keeps your controllers, services, and views clean. No query logic there — just calls to your AQC classes.
Testable: Because logic is in isolated classes, it’s easy to write unit tests without involving controllers or database state.

Implementation Example

Let’s say we’re working with a Product model in a typical eCommerce app. First, create a folder:

app/AQC/Product/

GetAllProducts.php
GetProduct.php
StoreProduct.php
UpdateProduct.php
DeleteProduct.php

“While I’ll use Laravel in the code examples, this pattern is framework-agnostic and can be adapted to any OOP-based backend environment — Node.js, PHP, Python, etc.”

GetAllProducts.php

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetAllProducts
{
    public static function handle($params = [], $paginate = true, $scenario = 'default')
    {
        $productObj = Product::latest('id');

        if (isset($params['category_id']) && $params['category_id'] > 0) {
            $productObj->where('category_id', $params['category_id']);
        }

        if (isset($params['brand_id']) && $params['brand_id'] > 0) {
            $productObj->where('brand_id', $params['brand_id']);
        }

        // add more conditions for different use cases

        switch ($scenario) {
            case 'minimal':
                $productObj->select(['id', 'name']);
                break;
            case 'compact':
                $productObj->select(['id', 'name', 'price', 'image']);
                break;
            case 'admin':
                $productObj->select(['id', 'name', 'price', 'sku', 'image', 'stock', 'cost']);
                break;
            default:
                $productObj->select('*');
        }

        return $paginate
            ? $productObj->paginate(Product::PAGINATE)
            : $productObj->get();
    }
}

Usage:

// Admin listing
$products = GetAllProducts::handle(); 
// return paginated product order id latest 

// Frontend product listing
$products = GetAllProducts::handle($request->all(), true, 'compact');

GetProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class GetProduct
{
    public static function handle($id, $params = [], $scenario = 'default')
    {
        $productObj = Product::where('id', $id);

        if (isset($params['active']) && $params['active']) {
            $productObj->where('active', $params['active']);
        }

        // add more conditions for different use cases

        switch ($scenario) {
            case 'minimal':
                $productObj->select(['id', 'name']);
                break;
            case 'compact':
                $productObj->select(['id', 'name', 'price', 'image']);
                break;
            case 'admin':
                $productObj->select(['id', 'name', 'price', 'sku', 'image', 'stock', 'cost']);
                break;
            default:
                $productObj->select('*');
        }

        return $productObj->first();
    }
}

Usage:

// Admin edit screen
$product = GetProduct::handle($productID, [], 'admin');

// Frontend product detail
$product = GetProduct::handle($productID, [], 'compact');

StoreProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class StoreProduct
{
    public static function handle($params)
    {
        $product = new Product();
        $product->fill($params);

        if (isset($params['type']) && $params['type'] === 'combo') {
            $product->is_combo = true;
        }

        if (!isset($params['sku'])) {
            $product->sku = self::generateSku($params);
        }

        $product->save();
        return $product;
    }

    private static function generateSku($params)
    {
        // SKU generation logic
        return 'SKU-' . rand(1000, 9999);
    }
}

UpdateProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class UpdateProduct
{
    public static function handle($id, $params)
    {
        $product = Product::find($id);

        if (!$product) return null;

        if (isset($params['cost'])) $product->cost = $params['cost'];
        if (isset($params['price'])) $product->price = $params['price'];
        if (isset($params['stock'])) $product->stock = $params['stock'];

        // add more fields as needed

        $product->save();
        return $product;
    }
}

DeleteProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class DeleteProduct
{
    public static function handle($params = [])
    {
        $productsObj = Product::query();

        if (!empty($params['category_id'])) {
            $productsObj->where('category_id', $params['category_id']);
        }

        if (!empty($params['brand_id'])) {
            $productsObj->where('brand_id', $params['brand_id']);
        }

        if (!empty($params['product_id'])) {
            $productsObj->where('id', $params['product_id']);
        }

        if (!$product) return false;

        $productObj->delete();

        return true;
    }
}

Final Thoughts

Each class builds the query, covers various scenarios, and cleanly separates logic. You can now reuse queries across your entire app — controllers, API endpoints, and admin panels — without rewriting anything.

When a new requirement comes in, you know exactly where to go. No more chasing query logic across 20 files.

“With AQC, every query has a home. No more hunting across layers of your app to find and fix logic. Write it once. Use it everywhere. Welcome to clean, atomic thinking.”

If you try AQC in your projects, I’d love to hear how it works for you — or what you’d improve.

I’ll be sharing more Laravel architecture patterns soon. Follow along if you’re into clean, scalable code.

If you’d like personal mentorship or 1-on-1 help with AQC Design Pattern, I’m available on Topmate.io here.

Schedule a booking

If you found this post helpful, consider supporting my work — it means a lot.

Support My Work

Chain of Responsibility for LLM Response Handling

Mon, 16 Mar 2026 15:09:55 +0000

While building a vibe coding platform, I started building Mozaik, a library for working with LLMs. Very soon, a need emerged to handle multiple LLM providers - and with that, different request and response formats. To avoid messy code, I applied the Chain of Responsibility design pattern to handle the different responses coming back from an LLM.

Instead of branching logic, each response flows through a chain of small handlers. Each handler checks one thing (structured output, tool call, plain text, empty response) and either handles it or forwards it.

This keeps response handling explicit and composable:

each handler has a single responsibility
handlers are easy to test in isolation
new response types can be added without touching existing logic

Structured output validation is just another handler in the chain, not a special case.

Reporting and Production Make Terrible Roommates

Wed, 11 Mar 2026 14:01:18 +0000

I tend to think of reporting and production as incompatible roommates. They need the same space, they optimize for completely different things, and every accommodation one makes for the other is a debt that gets called in later. The production schema is usually what accumulates the most debt and gets hit the hardest.

Consider what happens when the analytics team asks for a denormalized order_summary view on the production database so their dashboards load faster. The DBA obliges, adds a materialized view, and now every schema migration has to account for it. Six months later the application team wants to split the orders table into orders and order_line_items. But the view is embedded in 10 dashboard queries and a nightly export job, and most of those queries also join it back to columns on orders directly. Redefining the view over the new tables is the easy part. Rewriting and revalidating a dozen queries the application team doesn't own is not, so the refactor stalls, and the production schema fossilizes around a reporting concern.

Reporting Tends to Win Every Schema Negotiation

The cause is structural. A transactional schema optimizes for write consistency, referential integrity, and the access patterns of the application that owns it. A reporting schema optimizes for read throughput, aggregation, and the access patterns of analysts and dashboards. When both share a schema, every design decision becomes a negotiation.

Once dashboards reach executives or exports reach outside consumers, reporting tends to win that negotiation, because saying no gets more expensive with every dashboard that already depends on a yes. Its requests arrive one at a time as small additions (a column, an index, a view), each cheap to accept and expensive to remove. A refactor's payoff is deferred, while a broken dashboard is visible to leadership the same morning.

Not every system needs a separation on day one. A small team with a single database, low reporting complexity, and a schema that's still fluid can query production directly without meaningful friction. But this fossilization is predictable. It emerges when reporting consumers multiply, when dashboards become load-bearing, and when schema changes require cross-team coordination.

Architects who recognize this trajectory can keep the door open for separation without building the full pipeline prematurely. That means resisting the urge to denormalize production schemas for reporting convenience, and keeping reporting access patterns from becoming implicit contracts on the production schema. When the separation does happen, it can be reactive, tapping into what the database already captures, or intentional, making the application responsible for producing reporting-quality records in the write path.

Reactive Separation Reuses What the Database Already Captures

A Dedicated Reporting Replica Isolates Load, Not Schema

The simplest place to start is to point reporting tools at a read replica of the production DB. Many teams already have replicas for distributing query load, and so dedicating one to reporting keeps analytical queries from competing with production traffic. No new infrastructure, no async pipeline, no application code changes.

  ┌─────────────┐         ┌─────────────────┐
  │ Application │────────>│  Production DB   │
  └─────────────┘  writes │  (Primary)       │
                          └────────┬─────────┘
                                   │ replication
                                   v
                          ┌─────────────────┐
                          │  Read Replica    │
                          │  (Same Schema)   │
                          └────────┬─────────┘
                                   │ direct queries
                          ┌────────┴─────────┐
                          │  BI / Dashboards  │
                          └──────────────────┘

This is a feasible fit when reporting needs are straightforward and the production schema is close enough to what reporting consumers need. It also assumes data that's a few seconds stale is acceptable. "A few seconds stale" is the optimistic case, though. Heavy analytical queries on the replica can cause replication lag to spike well beyond that, especially during peak reporting windows.

The isolation is partial, too. On a PostgreSQL standby, a long report can block the replica from applying changes. The replica then either cancels the report or, with hot_standby_feedback on, stops the primary from cleaning up dead rows. Reporting indexes land on production too, because a replica can't hold indexes of its own.

The replica breaks down when reporting needs diverge far enough from the production schema's shape. Reporting consumers write increasingly complex queries with multiple joins, or they start requesting schema changes to production to make their queries simpler, which is exactly the distortion this post is about.

The replica can't capture intermediate transitions either. Reporting queries see whatever state the database holds when they run, so if a record changes twice between one query and the next, the intermediate state is invisible.

Change Data Capture: State History Without Intent

CDC tools like Debezium tap the database's transaction log and emit changes as events. The application writes normally to whatever schema makes sense, and CDC streams those changes to a separate store. Unlike the replica approach, CDC captures every intermediate state change because it reads from the transaction log rather than querying current state.

  ┌─────────────┐         ┌─────────────────┐
  │ Application │────────>│  Production DB   │
  └─────────────┘  writes └────────┬─────────┘
                                   │ transaction log
                                   v
                          ┌─────────────────┐
                          │  CDC Connector   │
                          │  (e.g. Debezium) │
                          └────────┬─────────┘
                                   │ change events
                                   v
                          ┌─────────────────┐
                          │  Stream / Queue  │
                          │  (Kafka, Kinesis)│
                          └────────┬─────────┘
                                   │
                     ┌─────────────┴─────────────┐
                     v                           v
            ┌────────────────┐          ┌────────────────┐
            │  Transform (T) │          │  Schema        │
            │  Reshape/Join  │          │  Registry      │
            └───────┬────────┘          └────────────────┘
                    v
            ┌────────────────┐
            │ Reporting Store│
            │ (Warehouse/DL) │
            └────────────────┘

CDC's greatest strength is that it requires no application code changes and no new abstractions in the write path. That makes it often the only viable option for legacy systems where changing the write path is too risky, or for teams that need separation now and can't modify every service that writes data. It also tends to deliver complete payloads, because the log usually carries the full new row even when the application updated a single field.

The first limitation is semantic. CDC events originate from the database layer, so they capture what changed but not why it changed. A row update that represents a customer canceling an order looks identical to a row update that represents a system correcting a data entry error.

The obvious workaround is to add columns like cancelled_by and cancel_reason. They record the why only when the application itself needs them, because then they're domain state and CDC carries them. Adding them only for reporting is the distortion this post started with. And some intent has no natural row to live on at all, such as a correction or a change spanning several entities. For financial ledgers or audit-critical workflows, where intent is as important as state, the write path has to record the intent itself, which is what the outbox and event sourcing below do.

The second limitation is the absence of a contract boundary. The table structure is the contract, implicitly. When that schema changes, nothing fails at build time. The CDC pipeline either silently emits differently shaped events or breaks at runtime, and reporting consumers discover the problem in production rather than in development.

Two mitigations narrow that gap without closing it. A transformation layer that maps raw tables onto a stable reporting model, such as warehouse staging models, shrinks the repair after a schema change to one place. But the reporting side owns that layer, so it learns of production changes only after they ship. A schema registry can partially close this gap by rejecting incompatible schema versions when the pipeline tries to register them, but that's added infrastructure catching incompatibility at runtime rather than at build time.

The third limitation is database dependency. CDC is only as good as the log the database exposes. PostgreSQL's logical decoding, MySQL's binlog, and DynamoDB Streams are mature options. But a managed service that restricts log access, or a stream that retains changes only briefly (DynamoDB Streams keeps 24 hours), can push teams toward application-layer alternatives earlier than expected.

Reading the log also loads the primary. Logical decoding adds write-ahead log volume to every write. A PostgreSQL replication slot also holds that log on the primary until the connector consumes it, so a stalled CDC pipeline can fill the production database's disk.

Intentional Separation Captures Intent in the Write Path

Reactive approaches separate the workload but not the context. They capture what changed, not who changed it or why. That context exists at the application layer when the write happens, and it's lost the moment the data hits the database unless someone deliberately captures it.

The Outbox Pattern Makes the Contract Explicit

The outbox pattern makes the application responsible for producing reporting-quality records. Instead of letting the database schema define the downstream contract implicitly, the application writes a versioned record to an outbox table within the same database transaction as the domain state change. Either both commit or neither does. A separate process reads from the outbox and projects into whatever reporting store analytics needs. That relay can crash after publishing and before marking a record published, so delivery is at least once, and consumers deduplicate on the event ID. The application controls the payload shape, the versioning, and the context included in each record.

  ┌─────────────┐
  │ Application │
  └──────┬──────┘
         │ single transaction
         v
  ┌──────────────────────────────────────┐
  │          Production DB               │
  │                                      │
  │  ┌──────────────┐  ┌──────────────┐  │
  │  │ Domain Table  │  │ Outbox Table │  │
  │  │ (orders,      │  │ (versioned   │  │
  │  │  customers)   │  │  records)    │  │
  │  └──────────────┘  └──────┬───────┘  │
  └───────────────────────────┼──────────┘
                              │ poll / stream
                              v
                     ┌─────────────────┐
                     │ Relay Process   │
                     │ (reads outbox)  │
                     └────────┬────────┘
                              │ publish
                              v
                     ┌─────────────────┐
                     │ Reporting Store │
                     └─────────────────┘

Outbox table via a relational database:

CREATE TABLE outbox (
    id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    event_id        UUID          NOT NULL DEFAULT gen_random_uuid(),  -- globally unique, used downstream
    aggregate_type  VARCHAR(100)  NOT NULL,  -- e.g. 'Order', 'Customer'
    aggregate_id    VARCHAR(100)  NOT NULL,  -- e.g. order ID
    event_type      VARCHAR(100)  NOT NULL,  -- e.g. 'OrderCancelled'
    schema_version  INT           NOT NULL,  -- contract versioning
    occurred_at     TIMESTAMPTZ   NOT NULL DEFAULT now(),
    initiated_by    VARCHAR(200),            -- who: user ID, system name
    reason          VARCHAR(500),            -- why: 'customer_request', 'admin_override'
    payload         JSONB         NOT NULL,  -- full state snapshot + context
    published       BOOLEAN       NOT NULL DEFAULT FALSE
);

Outbox record via a Kinesis/Kafka stream (JSON envelope):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "aggregateType": "Order",
  "aggregateId": "ORD-20260218-4417",
  "eventType": "OrderCancelled",
  "schemaVersion": 2,
  "occurredAt": "2026-02-18T14:32:08.771Z",
  "initiatedBy": "user:jsmith",
  "reason": "customer_request",
  "payload": {
    "orderId": "ORD-20260218-4417",
    "customerId": "CUST-8821",
    "previousStatus": "Confirmed",
    "newStatus": "Cancelled",
    "lineItems": 3,
    "totalAmount": 284.50,
    "currency": "USD"
  }
}

The outbox has an explicit, versionable contract boundary. A breaking change to the outbox record is a deliberate code change that goes through review. If a developer renames a column in the production schema, the outbox record doesn't change unless someone deliberately updates it. A contract test in CI fails the build when the record's shape changes, before any dashboard breaks. Unlike a test on CDC tables, it lives in code its owners already test. The outbox table itself is a reporting concern in the production database, but domain tables never read or join it. Changing a domain table changes only the code that maps it into the record.

Because a polling relay doesn't rely on transaction log capabilities or vendor-specific change feed APIs, any database that supports transactions supports the pattern. A relay built on CDC, such as Debezium's outbox event router, inherits CDC's operational risks but not its implicit contract.

The outbox does not require a record for every database write. It only fires when a specific entity type has a meaningful state change, and only for the types that reporting cares about. Background jobs updating internal timestamps produce nothing. A deletion does produce a record, because knowing that an entity was removed and who removed it is itself meaningful. This keeps the coupling concentrated in write paths that produce meaningful state transitions, not spread across every query and update in the codebase.

That selectivity is also the outbox's main risk. A bulk admin script or hand-written SQL fix that changes an order's status without writing to the outbox leaves reporting silently incomplete. CDC can't miss a change that way, because it reads every committed change. Emitting the record from the domain model's state transition closes most of that gap, and out-of-band SQL against tracked tables has to write its own outbox record.

The outbox is my recommendation for teams that have outgrown a read replica, need reporting to know who acted and why, and don't need full event sourcing.

CQRS and Event Sourcing Keep Every Transition at the Highest Cost

CQRS (Command Query Responsibility Segregation) formally separates the write model from the read model. The write side accepts commands and persists state. The read side maintains whatever views consumers need. The two sides don't have to share a schema, or even storage. What CQRS adds is the explicit acknowledgment that changing state and reading it are different jobs that can deserve different models. CQRS does not require event sourcing. Its write side can persist state normally in a traditional database.

Event sourcing takes this further by changing what the write side stores. Instead of persisting current state and producing reporting records alongside it, every state mutation is recorded as an immutable event, and current state is derived by replaying those events. The event log becomes the source of truth, not the current snapshot. Every transition is preserved in the order it occurred. Production state is a projection of the event stream, and so is reporting state, and so is any other view you need. If the analytics team changes their requirements six months from now, you replay the same events through a new projection and the full history is there.

                          Commands
                              │
                              v
                     ┌─────────────────┐
                     │   Write Side    │
                     │ (Command Handler│
                     │  + Aggregates)  │
                     └────────┬────────┘
                              │ append events
                              v
                     ┌─────────────────┐
                     │  Event Store    │
                     │  (append-only)  │
                     └────────┬────────┘
                              │ project
                              v
                     ┌─────────────────┐
                     │  Projected      │
                     │  State Tables   │
                     │  (per entity)   │
                     └────────┬────────┘
                              │ query (read side)
              ┌───────────────┼───────────────┐
              v               v               v
     ┌────────────┐  ┌─────────────┐  ┌────────────────┐
     │  Prod API  │  │  Reporting  │  │  Audit /       │
     │  Queries   │  │  Store      │  │  Compliance    │
     └────────────┘  └─────────────┘  └────────────────┘

Event store document (append-only, NoSQL):

{
  "streamId": "Order-ORD-4417",
  "position": 4,
  "eventType": "OrderCancelled",
  "occurredAt": "2026-02-18T14:32:07Z",
  "payload": {
    "initiatedBy": "user:jsmith",
    "reason": "customer_request",
    "previousStatus": "Confirmed",
    "newStatus": "Cancelled",
    "lineItems": 3,
    "totalAmount": 284.50,
    "currency": "USD"
  },
  "metadata": {
    "correlationId": "req-88a1c",
    "causationId": "cmd-cancel-4417",
    "userId": "user:jsmith"
  }
}

Projected state table (derived from events, used by reporting/ETL):

CREATE TABLE order_projections (
    order_id         VARCHAR(100) PRIMARY KEY,
    customer_id      VARCHAR(100) NOT NULL,
    current_status   VARCHAR(50)  NOT NULL,
    item_count       INT          NOT NULL,
    total_amount     DECIMAL(12,2) NOT NULL,
    currency         VARCHAR(3)   NOT NULL,
    placed_at        TIMESTAMPTZ,
    shipped_at       TIMESTAMPTZ,
    cancelled_at     TIMESTAMPTZ,
    cancelled_by     VARCHAR(200),
    cancel_reason    VARCHAR(500),
    last_event_pos   INT          NOT NULL,  -- tracks replay position
    projected_at     TIMESTAMPTZ  NOT NULL DEFAULT now()
);

The projected table above is what reporting reads in practice. Reporting consumers rarely subscribe to the event stream directly, which keeps the stream internal to the domain. A current-state projection like order_projections keeps only the latest cancellation. When reporting needs history, the domain team that owns the projections builds a history-shaped one, such as a status-transition table.

This is a good fit for domains where the complete history of state transitions is genuinely valuable, like financial ledgers, audit-critical workflows, or systems where "undo" and "replay" are first-class requirements.

Most teams should not reach for this combination. Martin Fowler's CQRS article warns that most of the CQRS cases he has run into have not gone well. Many systems fit a CRUD mental model and should stay that way. CQRS should only apply to specific bounded contexts where the read and write access patterns are genuinely different, not across entire applications. Event sourcing compounds the cost. Events are immutable and permanent, so schema design requires careful thought. Aggregate replay gets expensive without snapshotting, and debugging production issues means reasoning about event sequences rather than inspecting current state.

Choosing an Approach by What Reporting Needs to Know

Approach	Use when	Key limitation	Complexity
Read replica	Schema shape is close to what reporting needs; slight staleness is acceptable	Replication lag under analytical load; no intermediate state history	Low
CDC (e.g. Debezium)	Write path can't be modified; full row history is needed	Captures state, not business intent; table structure is an implicit contract	Medium
Outbox pattern	Business context (who/why) matters; write path can be modified	A write path that skips the outbox silently drops data; relay process and versioning discipline needed	Medium
CQRS + Event Sourcing	Audit-critical domain; "undo" and "replay" are first-class requirements	Events are permanent; aggregate replay is expensive without snapshotting	High

Separate Early or Pay Later

Separating early means separating the access path before dashboards depend on base tables, not building a pipeline. The first request for a reporting-only column or view on production is the cue. Every shortcut that ties these workloads together makes the eventual separation harder. The analytics team and the application team end up negotiating every schema change, and the production schema accumulates the concerns of whoever complained most recently.

A read replica is enough to start, but only if dashboards query plain views rather than base tables. Those views live in a reporting schema the application team owns and can redefine, with grants that reach nothing else. Migrations still update the views, but now the team running the migrations owns them. When those views get too slow or too costly to redefine, move past the replica, to CDC if reporting needs only what changed and to an outbox if it needs why.

Whichever step comes next, reporting reads an owned surface rather than raw tables, whether that's views on the replica, a transformation layer on CDC, or an outbox record. That owned surface keeps the schema from freezing, and the separate store keeps reporting load off production.

Separation doesn't remove the coupling, but it gives the coupling an owner. With an outbox, the application team owns the record and its versions, and the analytics team owns the projection built from it. New questions about who or why still reach the application team, but as a reviewed change to a versioned record, and older records won't carry the new context. A production schema change that leaves the record's version intact ships without asking the analytics team.

Observability Is Authored, Not Installed

Mon, 16 Feb 2026 19:01:55 +0000

I have been a part of a dev team where poor observability constantly brought us to a standstill. Not because the tooling was missing, but because the data it collected never carried meaningful context. Alerts fired constantly, so operations teams ignored them. Dashboards existed for every service, but none of them answered the questions that mattered during incidents. Investigations that should have taken minutes took hours. It got bad enough that slow diagnosis alone stretched incidents into significant SLA violations.

We questioned the choice of platforms, dashboards, and alerting rules. Yet none of those could help, because no tool could report a distinction our code never recorded. The problem was upstream, since our code didn't know the difference between "I handled this correctly" and "something is actually broken."

The Classification Problem: Handled Outcomes Logged as Errors

Consider a payment processing system. A customer's card gets declined for insufficient funds. The payment gateway returns a rejection, and the system logs it as an ERROR.

But this is the system working correctly. Insufficient funds is a handled business case, not an exception. Because it's logged as an error, though, it shows up in error dashboards, triggers error-rate alerts, and adds to the ambient noise that operators learn to tune out.

Over time, "payment errors" become background radiation. The team knows most of them are just declined cards, so they stop investigating. Then the gateway starts timing out, or a partner pushes a breaking change, and the actual problem gets buried. Nobody notices because "payment errors are always high."

The usual response is to blame the team for ignoring alerts. It is a discipline problem, yes, but the discipline that's missing is upstream, in the code that treats expected outcomes as errors.

The fix belongs in that code, which should sort each outcome by what it means:

Expected success: The happy path. Logged at DEBUG if at all.
Expected failure: Business logic correctly rejecting something, like declined payments, validation failures on input from outside callers, or rejecting a caller over its quota. This is INFO, not ERROR.
Degraded but functional: The system recovered, but something is wearing thin. Retries running past their usual count, or a dependency throttling your calls. This is WARN. It isn't broken yet, but it needs attention before it becomes broken.
Unexpected failure: Something genuinely went wrong that demands investigation. This is the only category that should be ERROR. A call that fails past its retries belongs here even against a dependency known to be flaky, because no code path handled it. If that becomes routine, the fix is a handled path like a circuit breaker or fallback, which moves it to degraded.

Typed results make this distinction structural instead of incidental. When expected failures are returned as typed results rather than thrown as exceptions, the classification is baked into the code's structure. A declined payment returns a result; a gateway timeout that exhausts its retries throws an exception. A logging boundary still has to map each result type to a log level, but typed results put that decision in one visible, testable place instead of leaving it to guesswork at every call site.

The log level is only one way to carry that decision. A structured outcome field or a counter works as well, as long as the code sets it. For conditions that only show in aggregate, like routine retry counts, response times approaching SLA thresholds, or connection pools running hot, a metric carries the decision better than a WARN line per request.

When classification is right, every downstream tool benefits. Dashboards that track error rates become genuine health indicators because errors represent actual unexpected failures, not business logic working as designed. Log queries become surgical because structured errors with proper context let you filter to a specific tenant or operation in minutes. Once thresholds and routing are set well, alerts become actionable, because every error they count demands investigation.

When classification is wrong, the opposite happens. Alerts fire for expected outcomes, so operators learn to ignore them. Dashboards become decoration because nobody trusts what the numbers represent. Every investigation becomes archaeology because the data that should answer your questions is buried under noise.

Only the Code Can Make the Call

The usual alternative is to classify downstream, but no downstream tool can classify outcomes the code didn't make distinguishable. Each option runs into that limit in its own way.

A collector rule can change the level of decline lines in one central place. But it matches message text, so it breaks silently when the message changes, and it never sees lines that sampling already dropped.
Filters by logger category or exception type quiet framework and library noise without matching text. But they can't split a decline from a breakage inside the same operation.
An SLO holds the classification rule in one shared place. But it can only count a field the code emits.

Status codes look like a field the code emits, and auto-instrumentation can tell a 402 decline from a 504 timeout. But a status code carries the meaning only when the code puts it there. A decline wrapped in a 200 response body reaches the platform with the wrong label. A partner's breaking schema change gets the wrong label too, because it arrives as a 400 that looks just like a validation failure.

Only the code knows the difference, and it knows because someone designed it to. A partner integration shows what that design looks like. If the code validates each request against its own rules before sending, any schema or contract 400 the partner returns afterward is unexpected by definition. Sometimes the 400 reveals a rule your validator missed rather than a partner change. ERROR is still right, because the gap is a bug in your code, and fixing it removes that noise. Rejections based on the partner's own state, like a closed account, are different. They're expected outcomes, so map the partner's error codes for them explicitly.

Business Judgment Belongs in Counters, Not Log Levels

When the system correctly declines a card for insufficient funds, it's tempting to log that as WARN because you want the metric reviewed often. But a correctly handled decline is the system working as designed, not degrading. Whether the decline rate is "concerning" is a business question that changes with strategy and context, so log levels shouldn't encode that judgment. Leave business interpretation to reports and dashboards where it can evolve, not to code where it gets baked in and forgotten.

Declines still deserve watching, just not through the log level. Feed those reports from a decline counter rather than from INFO lines, because many teams sample INFO logs and a counter keeps every decline. The counter also catches breakage that looks like declines. A sudden spike in correctly handled declines can mean a bug sending wrong amounts or a card-testing attack, so the same counter can carry an anomaly alert routed to engineering, separate from the error rate.

Context Is Authored, Not Accumulated

The instinct is to compensate with volume: write verbose logs everywhere so you'll have context when you need it. But a trace-level log is not a dump file. Nearly every bug I've seen diagnosed from trace logs involved information the code already had at the point of failure and could have put in the error or warning itself. In those cases the problem wasn't insufficient logging volume; it was that nobody authored the context where it mattered.

A stronger version of the volume argument comes from Observability Engineering, by Charity Majors, Liz Fong-Jones, and George Miranda. It records one wide structured event per request with dozens of attributes, so you can ask questions afterward that nobody predicted. That approach handles unknowns far better than trace dumps, but it doesn't escape authoring. The event still needs an outcome field that says whether a decline was expected or broken, and domain fields like the tenant and the gateway's response code only exist if the code puts them there. Without them, a high-cardinality store is a faster way to search through the same unclassified noise.

Failures should carry their own context. When an operation fails, the error log should include what was being attempted, what went wrong, and enough identifying information to correlate it. Consider a checkout failure. Instead of logging "payment processing failed," a properly authored error captures the operation ("charge_payment"), the correlation ID, the gateway's response code, and the amount. That's structured enough to query and specific enough to reproduce the failure without re-running production traffic.

What solves most domain-logic bugs is understanding what the user did and what they sent, not tracing the code's internal flow. Connecting what they did across services takes a correlation key, and carrying that key is a solved problem. The W3C Trace Context standard defines how it travels between services, and most structured logging libraries can stamp it on every entry. With that key and errors authored like the checkout one, you have what you need to reproduce the problem.

Reproducing a failure from its input, rather than tracing it, borrows the idea behind event sourcing, where a state can be rebuilt by replaying the events that produced it. For deterministic domain logic, you don't need to trace every intermediate step if you can reconstruct the scenario from the input, the outcome, and the state the operation read.

The state the operation read is the part the request can't supply. A race, or a record that changed after the failure, can't be replayed from the input alone. So the error should carry the versions of the records it loaded. A version only helps while the old record still exists. If the store overwrites records in place, carry the field values the decision used instead.

Most of the context a failure needs can be chosen in advance, because the facts that decide an outcome are ones the code already handles. They are the operation, its input, the response from whatever it called, and the versions of the records it read. Environment facts like the build version, config, feature flags, and host belong there too, and the logging setup can attach those to every entry without per-call code. Some deciding facts won't be predictable. Those show up as incidents where someone had to add logging to find the cause.

What gets logged must be intentional. You know the domain, so you know the potential inputs, what's valid, and what's sensitive. That knowledge lets you author a safe context, enough to reproduce the problem without exposing data that shouldn't be in a log. An allowlist of input fields, hashed identifiers, or a reference to a stored payload can carry the input safely. If you don't understand the domain well enough to make that distinction, that's the source of the problem, not the logging infrastructure.

The difference between a useful error and a useless one is whether someone authored the context intentionally or hoped that raw volume would cover it.

Installed Tooling Reports Mechanics, Not Meaning

Classification and context both come from the code, but some observability really is installed. A platform catches transport failures on its own, like a timeout on an outbound call, and span timings and profilers expose creeping latency without any per-call code. Trace logging, toggled on temporarily for one flow, still diagnoses ordering bugs where the sequence itself is the evidence.

What they can't supply is meaning. They see that a call failed or slowed down, but not whether a rejection was the system working as designed, which fields an error needs, or whether an answer was wrong. Wrong output that never raises an error only surfaces in business-outcome metrics, and those are authored too, because someone has to decide which outcome to count. That's the sense in which observability is authored. The installed part tells you something failed, and only the authored part tells you whether it matters and why.

The Black Box Test: Diagnose From Outputs Alone

The word observability comes from control theory, where Rudolf Kálmán defined it in 1960. A system is observable when its internal state can be inferred from its external outputs. The practical test applies that definition. When something breaks, can you diagnose it from the system's outputs alone? Or do you need to add logging, redeploy, and wait for it to happen again? If the answer is the latter, your code doesn't explain itself yet.

Software never passes completely, so run the test as a rate. For each recent incident, ask whether the first responder could identify the failing operation, its input, and the cause from existing telemetry. Score it from the timeline rather than memory. An incident fails if anyone added logging before the cause was found, whether by redeploy, a live logpoint, or a trace toggle. That holds even when toggling trace logging was the right move for an ordering bug. The failing share should fall over several quarters. With only a few incidents a quarter, read the trend over a year.

Attaching a Debugger Hides the Gaps

Classification and context are design decisions, but many developers never test whether their logging actually answers the questions it needs to. One habit that contributes is the debugger. Stepping through code is the right tool for a logic bug in development, but the habit hurts when it becomes the only way surprises get explained. A developer who resolves every local surprise by stepping through code can get little practice diagnosing from outputs, so gaps in those outputs are easy to miss until production.

Some organizations extend this habit into production with remote debugging, but that's a security liability. A debugger attached to a running container, or to any production process, can read its memory, including secrets and customer data. It can also change what it executes, so every open debug port is another way into production.

Snapshot debuggers capture variables without pausing, so they're gentler, and redaction and audit can contain their exposure. But they still keep the habit of reaching into the process instead of fixing what it outputs. You should be observing system outputs, not reading a live process's memory.

Production should be a black box. If your default instinct when something breaks in production is to attach to it rather than read the outputs, you'll rarely feel the pressure to make those outputs useful. The classification stays sloppy, the context stays thin, and the errors stay vague. Not because you don't know better, but because you've never needed better.

Developers who diagnose from observable behavior, whether testing locally against containerized dependencies or against remote systems, tend to build the discipline. They feel the pain of vague errors and missing context firsthand, and they fix it at the source because they have no easier option.

Owners Who Get Paged Close the Gaps

That discipline holds best when builders own what they operate. You don't log payment declines as errors when you're the one who gets paged for "high error rate on payment service." You don't dump verbose logs instead of authoring context when you're the one parsing them at 3 AM.

Paging pressure only fixes code when it reaches the code. A paged team can just as easily raise thresholds or mute alerts. What can turn the pain into a source fix is bringing the authors into incident diagnosis and filing every misclassified outcome or context-free error found there as a bug against the owning team.

Tracking open telemetry bugs per owning team, beside the black box test's failing share, gives each team a number that backlog triage can see. Filing against the owning team matters most when the author sits on another team, because that author would otherwise never feel what their classification and context choices cause downstream.

Better tooling alone won't make your code explain itself. Running the black box test against it, and filing what it finds against the code that caused it, is how it starts to.

How Shared Libraries Become Shared Shackles

Tue, 03 Feb 2026 16:35:47 +0000

This is a highly opinionated take on shared libraries and the damage they do to team autonomy and development tempo. Teams deliver value faster and more consistently when they can make decisions, ship changes, and evolve their domains without coordinating across organizational boundaries. Shared libraries erode exactly that independence.

After seeing costs explode for trivial tasks and critical production updates failing to deliver on time in nearly every organization I have witnessed, I am willing to take a rather "extreme" stance on the subject.

This post focuses on distributed architectures, where the consequences are most severe.

Shared Libraries Violate Core Principles

Distributing components isn't just about distributing work. It's about the Single Responsibility Principle applied at the system level: clear ownership, implementation isolation, and infrastructural independence. The share-nothing principle makes this explicit. Services should be autonomous, independently deployable, and free from implementation coupling. DORA's research on loosely coupled teams links that independence to delivery performance, finding that teams who can change and deploy without depending on other teams deploy more often and recover faster.

Shared libraries violate these principles. They couple teams through shared implementation despite being distributed in name, creating little monoliths that bind development tempo across teams that were meant to operate independently.

Yet the pitch keeps coming: "We have this code in five places. Let's consolidate it into a shared library. We'll save time, ensure consistency, and make everyone's life easier." It sounds reasonable, it really does, yet the decision only calculates the cost of duplication while ignoring the cost of sharing across teams, domains, and technical boundaries.

The Costs the Pitch Doesn't Count

Version conflicts and upgrade pain

Five teams now depend on your library. They release on different cadences and at some point one or more teams require a breaking change. Now you're either maintaining multiple versions indefinitely or forcing upgrades on teams that have other priorities. The "one place to maintain" becomes "one place that blocks everyone."

Teams blocked waiting for changes

A team needs functionality the library doesn't have, and a wrapper in their own code can't supply it. They can't just add it. They need to coordinate with the library owners, get the change approved, wait for a release, and then upgrade. An afternoon's change in a team's own code can stretch into weeks of waiting.

Debugging across boundaries

When something breaks, the investigation now spans your code and the library code. Your team doesn't own the library, yet it runs inside your service, so the investigation is still yours. The abstraction that was supposed to simplify your team's work has added a layer to dig through.

Bloat or fragmentation, pick your poison

The library starts focused. Then another team needs something slightly different. Then another. The library accumulates features to serve multiple masters, becoming a grab-bag of loosely related functionality coupled together because they share a package, not because they belong together. The disciplined alternative is to split it into many small, focused packages, but that creates its own problem: an entourage of dependencies that each consuming team must track, version, and coordinate with whenever they change.

Obscured accountability

Shared libraries don't reduce your quality burden; they move it somewhere less visible. If the library has a bug, your service has a bug. The library just adds a dependency you don't own and can't fix on your own schedule.

Polyglot stacks multiply the library

The shared library pitch assumes a homogeneous technology landscape that many organizations don't have. If your organization has services in C#, Java, Python, and Go, do you keep four versions of every shared library in sync? In polyglot environments, the "shared" library becomes a second-class citizen in every language except the one the authoring team uses. Whatever consistency the library buys stops at the language boundary, so you need another way to stay consistent anyway.

Release discipline softens these costs without removing them

The usual escapes each leave part of the cost in place:

Pinning an old version only delays the choice until a fix a team needs ships past a breaking change, and backporting that fix is the multiple-version maintenance again.
Automated update tools raise pull requests for breaking upgrades as well, but each consuming team still changes its own code to take one.
Outside contributions shorten the owners' queue, but the change still needs their review and a release.
Forking or patching locally puts the team back to copying the code.

The Cohesion and Coupling Diagnosis

If two services genuinely need the same function, you have three possibilities:

It's a cohesion problem. That function belongs in one place and should be called, not duplicated. Extract it into a service with an API. Now there's a clear owner, a clear contract, and no shared implementation coupling consumers together.

It's a coupling problem. You've drawn your boundaries wrong. The services that "need" the same code are more related than you thought. Reconsider where the boundary belongs rather than papering over the boundary violation with a shared dependency.

It's genuinely independent. The similarity is coincidental. Both services need to format dates, parse JSON, or validate email addresses, each a few lines of glue around the runtime. Copy the code. Move on. Each copy can evolve with its service.

Every answer has a price

A service adds a network hop, an availability dependency, and an API to version, and new features still wait on its owner. In exchange, the owner changes the internals without any consumer moving, and only a breaking contract change asks callers to act.

Copying has limits too. The copies can drift, and a copied bug gets fixed once per copy. For small code that rarely changes, that's still cheaper than the coordination. Copies also don't show up in a dependency scanner, so what you copy should be the glue around the runtime or a mature library, not a hand-rolled parser or validator.

Some code can't be copied at all. A rule that must produce the same answer everywhere, like a tax calculation, would let two copies disagree in a way a user or the data could see. That's the cohesion case, and it needs one running implementation. A shared library deployed at different versions in different services disagrees just as two copies would.

Fixing a bug once is a boundary signal

The common rebuttal is "but if there's a bug, I fix it once and it propagates everywhere." The answer depends on where the bug lives. Bugs in third-party libraries get fixed upstream on the vendor's cycle, and you take the fix by upgrading. Logging is another common candidate for sharing, but what a service logs and traces has no single fix to propagate. Each service authors its logs and telemetry out of its own domain knowledge, aligned to shared values about how behavior gets classified and what context gets captured.

What remains is mostly business logic. If your business logic is so coupled across services that a single bug requires simultaneous fixes everywhere, you don't have a sharing problem, you have a boundary problem. So the default is no, and the burden of proof sits with the library to show it will stay narrow and stable.

Using mature, well-tested libraries for universal problems makes sense. Logging frameworks, HTTP clients, serialization libraries, and authentication middleware exist because these problems are universal and well-understood. Someone else solved them better than you would, and the cost of depending on their solution is low because the solution is stable.

Sharing your internal CustomerDto across services is different. Sharing your "standard" repository pattern is different. Sharing your domain models between bounded contexts is different. These aren't universal problems with stable solutions. They're your internal abstractions, and forcing them on other teams assumes those teams should think the same way you do.

The dividing line is stability, not who wrote the code. An internal library kept narrow, versioned, and slow to break behaves like an external one. Internal libraries that carry domain or team-specific abstractions tend not to stay that way, because those abstractions change whenever your domain does.

SDKs Are Different

An SDK abstracts what you expose: the public contract of a service or platform. A good SDK earns its existence by encoding integration complexity that would be expensive and error-prone for every consumer to reimplement: orchestrating multi-step workflows, managing state across API calls, handling idempotency, and abstracting version differences.

A shared library abstracts how you think internally, like your domain models, patterns, and "standard way" of doing things. The shared library serves a governance impulse, not the consumer. And unlike an SDK, it tries to couple internal teams to the same release cycle and the same implementation decisions.

The SDK says: "Here's how to use our thing."
The shared library says: "Here's how you should build your thing."

One is a service to consumers. The other is an imposition on autonomous teams disguised as help.

Your Runtime Already Solved This

The shared library pitch often targets "utility code" that your runtime already provides. If you're using .NET, the framework gives you HTTP clients, JSON serialization, logging abstractions, dependency injection, and configuration management. Why would you need an internal shared library wrapping HttpClient when HttpClient exists and is battle-tested by millions of applications?

Your wrapper just adds coordination overhead on top of something that didn't need wrapping.

The Principle Is Broader Than Distribution

The same problem exists in a modular monolith wherever different teams own different domains. There, shared packages between domains still couple teams to the same change cycles. The blast radius is contained, though, because teams share a deployable and version conflicts surface as build errors.

In a distributed system, a change that would have been a merge conflict becomes a multi-team coordination effort with blocked releases and stale dependencies. Topology changes the severity, not the coupling. If Domain A and Domain B in separate services share domain code, they're a distributed monolith with extra steps.

Two practices look like exceptions to this coupling, but each accepts the cost rather than escaping it. The first is the monorepo that enforces a single version of every dependency, which Google's Software Engineering at Google calls the One-Version Rule. Version skew can't happen, but a breaking change to the library has to update every consumer before it lands. The coordination moves to whoever changes the library. Google absorbs it with large-scale-change tooling most organizations lack.

The second is domain-driven design's Shared Kernel. Eric Evans conditions it on neither team changing it without consulting the other, which accepts the coordination cost on purpose.

The API Client Library Obsession

The most common incarnation of shared library dysfunction is the API client package: a library of hand-written contracts, DTOs, and client code that consumers are expected to import when calling your service. I have never seen this pattern result in anything short of chaos.

The pitch sounds reasonable: "We'll publish a client library so consumers don't have to write their own HTTP calls or define their own contracts." But this solves a problem that doesn't exist while creating several that do.

Every API should have documentation describing its contracts. If your API is well-documented with clear schemas, consumers can generate or write their own clients. The documentation is the contract, and a schema check in each consumer's CI catches drift from it. A machine-readable schema such as an OpenAPI document or a .proto file is that documentation in another form. A stubs package generated from the schema, with no hand-written code, is too. The trouble starts when the package carries hand-written DTOs and runtime behavior, binding every consumer to the producer's model and policies.

Every consumer has different needs. Service A might need three fields from one endpoint. Service B might need ten fields from a different endpoint. Service C might need to call the same endpoint but transform the response differently. When you force everyone to use your client library, you're imposing your view of how your API should be consumed.

Client libraries impose one team's operational policy on every consumer. Teams building client libraries inevitably add caching strategies, retry policies, circuit breakers, and connection pooling configurations. Those decisions belong to the calling service, which is the only one that knows its own latency budget, its failure tolerance, and how much damage a stale read does in its domain. The producer knows none of that. A client library freezes those choices upstream, where changing them requires a coordinated release across every consumer.

The producer still has a part to play, but on its own side of the boundary. It protects itself server-side with rate limits and publishes which operations are safe to retry, its backoff contract, and how its idempotency keys and pagination tokens work. The caller honors that contract through its own resilience library.

The absurdity becomes obvious with frontend consumers. The iOS app doesn't need a backend team's Swift package to call its API. The iOS team reads the documentation, or generates a client from the published schema itself, and maps responses to whatever structures suit the application.

This reflexive reach for client libraries has been conditioned by years of cargo-culting. Patterns that made sense in public cloud SDKs with complex auth flows got carried into internal services with straightforward REST endpoints, where they don't. When an internal API needs multi-step orchestration to call correctly, that logic belongs behind the API, where the producer controls it, not in a package every consumer has to upgrade.

The Governance Theater Problem

Shared libraries often emerge from a governance impulse: "Teams are doing things inconsistently. We need to standardize."

The instinct isn't wrong, and consistency matters. But a mandated shared library is governance theater.

If teams are building things inconsistently, ask why. Usually it's because they don't share the same understanding of what matters, what the tradeoffs are, and what "good" looks like. That's an alignment problem. It requires conversation, documentation, and shared values.

Forcing everyone to use the same library doesn't create alignment. It creates compliance.

Governance through values: "Here's why we authenticate this way, here are the tradeoffs, here's what we're optimizing for. Align your implementation to these principles."

Governance through code: "Use this library or you're non-compliant."

The first preserves autonomy. Teams understand the principles and can make good decisions in novel situations. The second creates coupling while providing the illusion of alignment. Teams can comply without understanding, and when they hit a situation the library doesn't cover, they have no principle to fall back on.

Governing through values doesn't mean leaving them unenforced. Conformance tests, linters, and reviews against the stated principles keep alignment from decaying. They gate builds rather than ship inside services, so when a rule tightens, each team fixes its own code without waiting on another team's release, and the rule can start as a warning.

An optional "paved road" library that teams can leave still fits, because the values come first and the library is one documented way to follow them. It turns into theater when using the library becomes the compliance check.

The Exception: Thin, Stable Code Like Security Protocols

There's one domain where shared libraries routinely make sense: security protocols like ingress handling, service-to-service authentication, and encryption standards.

Why security is different:

The domain is stable and well-understood. Authentication patterns don't change week to week.
The cost of getting it wrong is catastrophic. Security isn't a place for teams to make independent decisions and learn from mistakes.
The surface area is thin and focused. A good security library does one thing.
Autonomy isn't the goal. You actually want teams to do security the same way. The coupling is a feature, not a bug.

The four conditions earn the exception, not the fact that it's security. They are the burden of proof the default puts on any shared library. In-process code that meets them earns it too, such as redacting personal data before logs leave a service, or a thin package that configures OpenTelemetry identically everywhere without deciding what a service logs.

Uniformity alone doesn't earn the exception. Code that must behave identically everywhere but fails the conditions belongs in an external library or a service instead. Trace-context propagation must match across every service, yet it needs no internal library, because OpenTelemetry's libraries already implement the W3C Trace Context standard.

Even here, mature external libraries or a service mesh should do the protocol work, and the internal library should be the thinnest layer that applies your organization's policy. Thinness keeps its forced upgrades rare. When a vulnerability does force one, uniform and immediate rollout is the point. The moment it starts accumulating "helpful" utilities beyond its core purpose, it's sliding toward the problems that plague other shared libraries.

What to Do Instead

When you feel the urge to create a shared library, pause and diagnose the problem:

If it's a capability multiple services need: Build a service and expose an API, unless the logic is stable enough to version like an external library.
If the services need the same logic because they share a domain: Redraw the boundary. The shared code is a symptom of a split in the wrong place.
If it's a pattern you want to standardize: Write documentation. Explain the principles, the tradeoffs, and the reasoning. Let teams implement the pattern in their own codebases. They'll understand it better than if they'd just imported your abstraction.
If it's truly just duplicated code: Let it be duplicated. For small code that rarely changes, the coordination cost of sharing exceeds the maintenance cost of duplication.
If it's a security primitive, or code that meets the same four conditions: Fine. Build the library. Keep it minimal, stable, and focused. Recognize it's a necessary evil, not a model to emulate.

The shared library is a solution to a problem that rarely exists in the form people imagine. Duplicating small, stable code isn't what slows teams down. Coordination overhead is.

Share values, and the shared library more often becomes unnecessary.

Chain of Responsibility pattern

Mon, 19 Jan 2026 09:25:06 +0000

About 8 years ago I came across the Chain of Responsibility pattern. I remember I was genuinely happy when I understood it, because all those long if / else if / else blocks suddenly felt unnecessary. Instead of one method trying to decide everything, you build a small chain of handlers. Each handler either handles the request, or passes it to the next one.

Wikipedia describes it as a source of requests and a series of processing objects. Each processing object contains logic that decides what it can handle, and forwards the rest to the next one. The nice part is that the chain can be rearranged and extended without rewriting one big method. (Wikipedia)

The classic example (your repo)

In your repo, the idea is very clear:

You have a base Handler with a successor
Employee, Supervisor, GeneralManager try to approve a PurchaseOrder
Each handler checks rules (your Specification<T>), and if it cannot approve, it forwards to the next handler

This is the object-oriented alternative to the “if ladder”, but with better structure and easier extension. (GitHub)

The base building blocks

This is the base handler that wires the chain:

public abstract class Handler
{
    protected Handler successor;

    public void SetSuccessor(Handler purchaseOrder)
    {
        this.successor = purchaseOrder;
    }

    public abstract void HandleRequest(PurchaseOrder purchase);
}

And this is the small Specification<T> concept used to keep rules readable:

public interface ISpecification<T>
{
    bool IsSatisfiedBy(T o);
}

public class Specification<T> : ISpecification<T>
{
    private Func<T, bool> expression;

    public Specification(Func<T, bool> expression)
    {
        if (expression == null)
            throw new ArgumentNullException();
        else
            this.expression = expression;
    }

    public bool IsSatisfiedBy(T o)
    {
        return this.expression(o);
    }
}

Example handler, Employee approves only small purchase orders. If it cannot approve, it forwards to the next handler:

public class Employee : Handler
{
    public override void HandleRequest(PurchaseOrder purchase)
    {
        ISpecification<PurchaseOrder> specification =
            new Specification<PurchaseOrder>(x => x.Price < 100);

        specification.And(new Specification<PurchaseOrder>(x => x.Amount == 1));

        if (specification.IsSatisfiedBy(purchase))
            Console.WriteLine("{0} approved purchase request #{1}",
                this.GetType().Name, purchase.RequestNumber);
        else if (successor != null)
            successor.HandleRequest(purchase);
    }
}

A quick example, building the chain

This is the part that made the pattern “click” for me. You create the handlers, link them together, and then you send requests to the first handler:

var emp = new Employee();
var superVisor = new Supervisor();
var generalManager = new GeneralManager();

emp.SetSuccessor(superVisor);
superVisor.SetSuccessor(generalManager);

List<PurchaseOrder> purchaseOrders = new List<PurchaseOrder>
{
    new PurchaseOrder { RequestNumber = 1, Amount = 1, Price = 50, Name = "Test Room 1" },
    new PurchaseOrder { RequestNumber = 1, Amount = 1, Price = 150, Name = "Test Room 2" },
    new PurchaseOrder { RequestNumber = 1, Amount = 1, Price = 200, Name = "Test Room 3" },
};

purchaseOrders.ForEach(x => emp.HandleRequest(x));

The caller doesn’t need to know who will approve. It only knows the start of the chain. Adding a new role later is just inserting one more handler, without rewriting the calling code.

How this shows up today with MediatR behaviors

What I like is that this pattern is not old school. You see the same idea a lot in MediatR pipeline behaviors.

A MediatR request goes through a chain of behaviors (validation, logging, performance, transaction, etc.). Each behavior can run logic before and after calling the next step in the pipeline, very similar to middleware. In practice, this is a Chain of Responsibility around your handler, used in a modern CQRS way.

In my projects, the most common example is TransactionBehavior. I run a database transaction only for commands (write operations). Queries skip it. That keeps reads lightweight, while writes stay consistent. The chain idea is the same, each step has one job, and the next step continues the flow.

Typical chain steps in CQRS are:

Validation (FluentValidation), stop early if invalid
Logging (request, response, timing)
Authorization (permissions, policies)
Caching (usually queries only)
Transactions (usually commands only, begin, commit, rollback)
Retries / idempotency (depending on the system)

So the “chain” is not only about deciding who approves a purchase order. It’s also about running a request through cross-cutting concerns, without bloating controllers or handlers.

Why I still like it

You can add a new rule without editing a giant method
You can reorder behavior, or swap parts, without rewriting everything
It fits naturally with CQRS, because commands and queries are already separated by intent

References

Wikipedia, Chain-of-responsibility pattern (Wikipedia)
Repo example, ChainOfResponsibility- (GitHub)

If you want, in the next part we can break it down with a concrete CQRS flow, like CreatePurchaseOrderCommand with ValidationBehavior, TransactionBehavior, and an approval chain implemented as a pipeline (or inside the command handler, depending on what you prefer).

Carter in a CQRS API, advantages and alternatives.

Wed, 07 Jan 2026 11:35:52 +0000

Carter in a CQRS API, advantages and alternatives.

In this project I wanted the API layer to stay small and structured. I like minimal APIs, but I don’t like having 200 endpoints inside Program.cs. That’s why I used Carter, it keeps the minimal API style and gives you a module system to organize endpoints by feature.

Repo used in this article:

https://github.com/stevsharp/ChainOfResponsibilityWithMediatR

Advantages of Carter

1) Feature-based organization without controllers

Carter pushes you to group endpoints in modules, for example PurchaseOrdersModule. This fits well with CQRS because you already think in features (Create, Approve, Reject, Get, List).

2) Minimal API feeling, but more maintainable

You still write endpoints in a minimal way (no heavy controller attributes), but you don’t end up with a giant Program.cs. Microsoft itself suggests structuring and organizing minimal APIs once they grow, Carter just gives a ready approach for it.

3) Cleaner API layer when using MediatR

When you combine Carter + MediatR, the endpoint usually becomes:

map route
bind request
call Send
return result

So your API layer stays thin and does not become “business logic + validation + database code”.

4) Testing and readability

Modules are easy to scan. If you want to see all Purchase Orders endpoints, you open one file. That’s a small thing, but in real teams it saves time.

5) Works nicely with Swagger and standard middleware

Carter is still based on ASP.NET Core endpoints, so you can keep standard middleware, and Swagger still works (with the normal setup).

Alternatives

Alternative 1, Controllers

Controllers (heavier):

Good when:

you want strong conventions and attributes everywhere
you already have a big MVC style codebase
your team prefers the familiar controller structure

Less good when:

you want very thin endpoints and feature modules
you end up with “controller bloat” and many attributes

Alternative 2, Pure Minimal APIs (no Carter)

Minimal APIs are great, and they are official. If your API is small, this is the simplest approach.

Good when:

small service with few endpoints
you want the simplest possible setup

Less good when:

endpoints grow and you need structure
Program.cs becomes huge

Microsoft has guidance on organizing minimal APIs because this is a real pain point once the API gets bigger.

Alternative 3, FastEndpoints (another popular option)

FastEndpoints is another library with a very feature oriented style, it also keeps endpoints separated and organized.

Good when:

you want a strong endpoint-per-class structure
you like conventions for validation, mapping, and request/response patterns

Less good when:

you want the thinnest layer possible over native ASP.NET Core endpoints

Alternative 4, Minimal APIs with Endpoint Groups (manual modules)

You can also do your own “module system” without extra libraries:

extension methods like app.MapPurchaseOrderEndpoints()
group routes with MapGroup("/api/purchase-orders")

This is a valid approach and stays 100% framework-only.

Good when:

you want no external dependency
you like simple grouping patterns

Less good when:

you still need to enforce structure across a team
endpoint definitions become scattered if not disciplined

Why I still chose Carter here

For this project size, Carter gave me the best balance:

minimal code style
good organization
no heavy framework feeling

And with CQRS + MediatR, it keeps the flow very clean: endpoint → mediator → handler.

References

Adaptability Over Cleverness: What Makes Code Actually Good

Mon, 05 Jan 2026 15:54:14 +0000

Systems that stay cheap to change for years aren't the ones built to fit today's requirements perfectly. They're the ones that bend without breaking when requirements shift, technologies evolve, and teams discover what they didn't know upfront. Building for change beats chasing premature perfection.

You will rarely get it right the first time. That's not a failure; it's how software development works. Requirements clarify through building, edge cases emerge through usage, and performance issues surface under real load. Teams that treat first attempts as gospel can spend months polishing solutions to the wrong problem.

Instead, build systems that can evolve. Give yourself room to deliver, learn, and adapt as reality proves what matters and what doesn't. Adaptable code is code where a likely change touches few places, can be made safely by someone other than its author, and shows quickly when it breaks something. Readability and simplicity matter for the same reason, since a change starts with someone understanding the code.

Correctness and speed aren't the only requirements code has to meet. Security, operability, and run cost are requirements too. Adaptability decides how much it costs to keep meeting all of them as the system changes, and that cost includes reading the code to diagnose an incident or pass an audit.

The exception is code that will never change or be read again, like a one-off migration script. That code only has to be correct.

Cleverness and Speed Make Change Expensive

Brian Kernighan and P. J. Plauger's The Elements of Programming Style put this in two maxims: "Write clearly – don't be too clever" and "Write clearly – don't sacrifice clarity for efficiency." Both describe the same cost. Clever code packs several decisions into one construct, like one cached value that quietly serves both a pricing rule and a fraud check. To change one of those policies, the next developer has to unpack both and work out which behavior the author intended and which is incidental.

Optimized code carries the same cost in a different form. An optimization usually rests on an assumption about today's workload, such as the data fitting in memory, records arriving sorted, or one query pattern dominating. The code around it comes to depend on that assumption too, so when the workload changes, the change has to reach every place that relied on it. Donald Knuth's 1974 paper "Structured Programming with go to Statements" argued that programmers' attempts at efficiency in noncritical code "have a strong negative impact when debugging and maintenance are considered." It's the same paper that calls premature optimization the root of all evil.

None of this argues against performance. When speed is a requirement, measure where it's needed and put the optimization behind a boundary, so the rest of the system doesn't depend on how it works. The fast path then becomes one more thing that can change in one place. Some optimizations can't hide, because they shape the contract itself, like a bulk API in place of per-item calls, a streaming response in place of a full list, or a denormalized table every report reads. Those are decided deliberately up front.

Adaptability Comes From Keeping Change Local

Adaptable code isn't magic. It follows principles that reduce coupling, isolate change, and make breakage obvious.

Boundaries Keep Each Change in One Place

Single Responsibility Principle is about change, not tasks. Robert C. Martin states it as "Each software module should have one and only one reason to change." Whether that module is a microservice owning a bounded context or a class handling a single concern, a shifted requirement lands in the piece responsible for it without cascading edits across the system. At service scale, a wrongly drawn boundary turns into a contract change between teams. That's why service boundaries deserve more care up front than class boundaries do.

Clean interfaces and separation of concerns apply at both macro and micro levels. Services communicate through contracts, not implementation details. Business logic doesn't know about HTTP; database layers don't make authorization decisions. Abstractions placed where implementations are likely to change let you pivot as understanding evolves without rewriting everything upstream.

Externalize what changes by making variable behavior configurable. Environment-specific settings keep the same code deployable to dev, staging, and production. Tunable timeouts, batch sizes, and retry policies let operations adjust the system's behavior without a code change.

Externalize only what is likely to vary, because each setting is flexibility with a carrying cost. It adds combinations to test and can drift between environments, so it needs the same likely-to-change test. A bad value can also take a system down, so validate configuration at startup like any other input.

Fast Failures and Tests Make Breakage Visible

Fail fast and loud surfaces problems immediately. Silent failures cascade into confusing bugs far from their source. Explicit validation at system boundaries, defensive assertions in critical paths, and structured logging create clear signals when something breaks.

Tests that give you confidence let you refactor without guessing what you broke. Unit tests verify component behavior. Integration tests catch interface mismatches. End-to-end tests confirm critical workflows still work. Tests help most when they check behavior through a component's public boundary, because a test coupled to internal details becomes one more place every change has to touch.

Consistency Shows Where a Change Belongs

Consistent naming and structure reduce cognitive load. Developers understand the codebase faster when patterns repeat. Services follow the same lifecycle. Features share the same folder layout and the same error-handling convention. When the structure is predictable, a developer can tell where a change belongs and what else it touches before opening a file, which is what lets someone other than the original author make it safely.

Trace one requirement through these habits. Suppose refunds above a threshold now need a manager's approval. If one module owns refunds, the rule lands there and nowhere else. If the same approval rule also governs discounts and credits, it changes for reasons refunds don't share. By the same one-reason-to-change test, it belongs in an approvals module that refunds call. A developer who didn't write that module finds it because every feature follows the same layout, and a test that issues a refund through the module's public interface fails if the approval check is missing.

If refund logic were instead copied into three controllers, the same rule means three edits, and a fourth copy nobody remembered keeps approving refunds without a word.

Flexibility Belongs Where Change Is Likely

The goal isn't maximum flexibility; it's appropriate flexibility. Rarely getting the design right the first time doesn't rule out appropriate flexibility. You can't predict what a requirement will become, but you can often predict where requirements will move. David Parnas made this the criterion for drawing module boundaries in his 1972 paper "On the Criteria To Be Used in Decomposing Systems into Modules." The designer starts from the design decisions that are difficult or likely to change and gives each module one of them to hide from the others.

Domain Knowledge and Change History Locate the Seams

Domain knowledge tells you where those decisions are, and version control history checks the guess. Files with high commit churn show where change has actually landed so far. Churn comes in two patterns that mean different things. A file that changes for many different tickets marks a place where requirements move, so an interface belongs there. A class and its tests changing together is expected, but files in separate modules that always change together for the same reason mark the opposite problem, a boundary drawn in the wrong place. Before the first release there is no history, and domain knowledge alone decides.

A payments system will need to support new payment providers, so the provider belongs behind an interface from the first release. Shape that interface around the domain's operations, like authorize, capture, and refund, rather than around the first vendor's API. That domain-shaped interface is a seam. It will still change when the second provider arrives with redirects, asynchronous confirmations, or a single charge step. But callers already depend on payment operations the domain owns rather than on one vendor's types, so the reshape is one contract change instead of a hunt for vendor types across the codebase.

Domain knowledge also shows where change is unlikely. An internal admin tool probably won't need a plugin architecture.

Decisions that other systems or stored data depend on follow a different rule. A published API contract, a persisted data format, or an event schema can't be fixed with a refactor later, because changing it means migrating data and coordinating every consumer. These deserve the same up-front care as the payment provider even without a change history. Service boundaries and the optimizations that shape a contract, like the bulk API earlier, belong in this group.

Contain a Dependency Until Its Shape Is Clear

Inside the codebase, a seam isn't the only option. When change is likely but its shape isn't clear, or when change arrives somewhere you kept simple, contain the dependency and add the abstraction later. Tests and consistent structure, the habits from the first half of this post, let you add the boundary when the second case actually shows up. That costs one refactor, instead of years maintaining an abstraction that nothing used.

That price stays low only if the concrete dependency is used from one place. Containing it takes no abstraction layer, just a rule that every call goes through one module or wrapper you own, and that callers never see vendor types or vendor error codes. Make the rule mechanical, such as keeping the vendor package a dependency of that one project, so a hurried direct call fails the build.

The wrapper differs from a seam in what it promises, not in whether it uses an interface. The wrapper offers only the operations today's callers use. A seam commits to the operations the domain needs from every implementation, and that commitment is the part that goes wrong when you guess. Either way, the later change replaces one file rather than forty call sites.

The tiebreaker follows from this. Add the seam up front when change is likely and you know the operations it must support, the way authorize, capture, and refund are known for payments even when each provider's mechanics differ. When the shape isn't clear yet, contain the dependency and wait for the second case to show it. Before adding a layer of flexibility, check:

Has this part of the system changed before, or does the domain make change routine, the way new providers are routine for payments?
If you wait, what would the change cost? When tests cover the code and the change would stay inside one module, adding the boundary later is cheap.
Who pays for the abstraction in the meantime? Every developer who reads the code pays for each layer of indirection, whether or not the change ever comes.

Perfect code written for yesterday's requirements fails when reality shifts. Over-engineered code taxes every change with layers nobody needed. Adaptable code finds the balance: flexible where change is likely, simple where it isn't.

How I Built a CQRS Approval Flow with MediatR, Carter, FluentValidation, and SQLite

Tue, 30 Dec 2025 10:40:18 +0000

The tech stack I used and why (updated, with Repository and Unit of Work)

This project is small, but I wanted it to feel like a real API you can extend. The repository is here:

https://github.com/stevsharp/ChainOfResponsibilityWithMediatR

Carter for endpoints

I used Carter because I like minimal APIs, but I still want structure. Carter lets you group endpoints by feature (modules) without big controllers, so the API layer stays clean. (Microsoft Learn)

CQRS with MediatR

CQRS is the separation of:

Commands (write, change state)
Queries (read, return data)

With MediatR, the endpoint just does mediator.Send(...) and the logic lives in a handler. This keeps endpoints thin and makes features easy to follow.

ICommand and IQuery marker interfaces

I added ICommand and IQuery as simple marker interfaces on top of MediatR requests. This is not a “framework”, it is only a clean way to tag what is a write and what is a read.

The reason is pipeline behaviors. With these markers, I can run transactions only for commands, and avoid wrapping queries.

MediatR pipeline behaviors

Pipeline behaviors are like middleware around every handler (IPipelineBehavior<TRequest, TResponse>). (

In this project I use:

LoggingBehavior, so I see execution time and request names
ValidationBehavior, so invalid requests never reach business logic
TransactionBehavior, so commands run inside a transaction

This keeps handlers focused, no repeated boilerplate.

FluentValidation

I used FluentValidation because it keeps validation clean and testable. It also supports assembly scanning registration, so validators are discovered automatically.

Repository pattern (why it exists here)

The Repository is used as a boundary between the application and persistence. In simple words, the application talks to an interface like IPurchaseOrderRepository, and Infrastructure decides how the data is stored (EF Core, SQLite, later maybe something else).

Conceptually, a repository “looks like” an in-memory collection for your domain objects, but it hides the database mapping details.

This is the classic definition from Fowler. (martinfowler.com)

In this project, repositories help me keep handlers free from EF Core code, so handlers read more like business use cases.

Unit of Work (and how it connects to DbContext)

A Unit of Work groups changes and commits them together. Fowler describes it as tracking everything you do in a business transaction and coordinating writing changes to the database. (martinfowler.com)

Important detail: in EF Core, DbContext is already designed to be used as a unit of work. Microsoft docs even explain that a DbContext instance is typically used for a single unit of work, then you call SaveChanges and dispose it. (Microsoft Learn)

So why still have IUnitOfWork in the Application layer?

Because it is not only about “needing” it, it is about controlling dependencies. Sometimes you want:

handlers to never call EF directly
one SaveChangesAsync per command (enforced in one place)
the possibility to swap persistence later without touching application code

So IUnitOfWork is an Application abstraction, Infrastructure implements it by calling DbContext.SaveChangesAsync. (Microsoft Learn)

EF Core + SQLite

EF Core is the persistence technology, SQLite is the lightweight database so the project runs locally with minimal setup. For a demo project, it is perfect.

Also, EF Core saving is straightforward: you change tracked entities, then call SaveChanges or SaveChangesAsync to persist. (Microsoft Learn)

Swagger (Swashbuckle)

Swagger is here so you can test endpoints fast without Postman. It gives visibility to request and response contracts, which is very useful in demos and early development.

Domain patterns, Chain of Responsibility and Specification

The business part is the approval flow. I used Chain of Responsibility to avoid one big if/else if method, and I used Specification style rules so conditions stay readable and composable. This makes it easy to add new approval levels without rewriting old logic. (Coder Legion)

References

GitHub repository:

https://github.com/stevsharp/ChainOfResponsibilityWithMediatR

Original article on CoderLegion:

https://coderlegion.com/8906/chain-of-responsibility-inside-cqrs-with-mediatr-a-small-practical-example

How to use Carter in a CQRS API, advantages and alternatives :

https://coderlegion.com/9342/carter-in-a-cqrs-api-advantages-and-alternatives

MediatR pipeline behaviors (IPipelineBehavior):
FluentValidation DI scanning:
Repository pattern (Fowler): (martinfowler.com)
Unit of Work pattern (Fowler): (martinfowler.com)
EF Core: DbContext as unit of work + SaveChanges lifecycle: (Microsoft Learn)

Chain of Responsibility inside CQRS (with MediatR), a small practical example

Thu, 25 Dec 2025 18:12:11 +0000

Chain of Responsibility inside CQRS (with MediatR), a small practical example

When we talk about “clean architecture” in ASP.NET Core, it is easy to end up with too many layers and too many rules, and the simple business logic becomes hard to read. This is exactly where Chain of Responsibility can help, especially when the business flow is something like approvals.

The chain-of-responsibility pattern is basically a smarter version of the classic if / else if / else tree. Instead of one method that knows everything, you pass the request through a list of handlers. Each handler decides, “can I handle this?”, if yes, it stops, if not, it forwards to the next one. The pattern is described as a chain of processing objects where each one handles certain commands and passes the rest forward. (Wikipedia)

In this repo, the “request” is a Purchase Order and the “handlers” are approvers (Employee, Supervisor, General Manager). (GitHub)

Why CQRS + MediatR is a good match

With CQRS, we already separate the world into:

Commands: change state (Create, Approve, Reject)
Queries: read state (GetById, List)

MediatR fits nicely because each command/query becomes a single request with a handler. What I like here is that the approval chain stays a domain concern, not something mixed inside controllers or endpoints.

Also, MediatR supports “pipeline behaviors”, which are like middleware around handlers (logging, validation, transactions). The base interface is IPipelineBehavior<,>. (GitHub)
So you get two “chains” in the project, but for different responsibilities:

Pipeline behaviors: cross-cutting technical concerns
ApprovalChain: business decision flow

What the project does (in simple words)

This project shows:

Carter endpoints (instead of controllers) for a clean API surface (GitHub)
CQRS with MediatR handlers (one handler per feature) (GitHub)
Behaviors for logging, validation, transactions (GitHub)
A domain ApprovalChain using specifications to keep rules readable (GitHub)
Swagger/OpenAPI so you can test fast from the browser (Microsoft Learn)

Repo:

https://github.com/stevsharp/ChainOfResponsibilityWithMediatR

(GitHub)

The approval chain idea (how to think about it)

Instead of writing something like:

if price < 100 and amount == 1, employee approves
else if price < 200 and amount <= 2, supervisor approves
else GM approves

You create small classes:

EmployeeApprover
SupervisorApprover
GeneralManagerApprover

And put them in an ordered list inside ApprovalChain.

Each approver checks rules using a Specification, so the rule becomes easy to reuse and test. (GitHub)

The big win for me is that later, when the company says “we need 2 more approval levels”, you add 2 new approvers, you do not rewrite one huge method and risk breaking everything.

Validation, Swagger, and why they are here

Validation is done with FluentValidation, and validators are auto-registered from an assembly (so you do not manually register 10 validators one by one). (docs.fluentvalidation.net)

Swagger is there for a simple reason, you can test your endpoints instantly and see the contracts. Swashbuckle is the most common way to do that in ASP.NET Core. (Microsoft Learn)

In this article I focused on the idea and why this pattern fits very well with CQRS.
In the next article, I will go deeper and show the actual implementation step by step, how the Carter endpoints connect to MediatR, how the commands and queries are structured, how the pipeline behaviors are added (logging, validation, transaction), and finally how the ApprovalChain and Specifications work together in the domain.

The goal is to make it a real “breakthrough” article where you can copy the structure and apply it to your own projects with minimal changes.

How I Built a CQRS Approval Flow with MediatR, Carter, FluentValidation, and SQLite:

https://coderlegion.com/8906/chain-of-responsibility-inside-cqrs-with-mediatr-a-small-practical-example

How to use Carter in a CQRS API, advantages and alternatives :

https://coderlegion.com/9342/carter-in-a-cqrs-api-advantages-and-alternatives

References

GitHub repo: ChainOfResponsibilityWithMediatR (GitHub)
Chain-of-Responsibility pattern definition and overview (Wikipedia)
MediatR IPipelineBehavior<,> interface (pipeline behaviors concept) (GitHub)
Carter framework (modular endpoints on top of ASP.NET Core) (GitHub)
FluentValidation DI registration (AddValidatorsFromAssembly...) (docs.fluentvalidation.net)
Microsoft docs, Swashbuckle and Swagger/OpenAPI setup (Microsoft Learn)

Why Configuration Files Don't Belong With Your Code

Tue, 16 Dec 2025 17:25:52 +0000

When you first create that new shiny code project, your configuration requirements seem so obvious and straightforward. You think: "I have a single behavior or feature that just needs this one setting or I am just calling this one external resource which just needs this one API URL". Often, your needs are indeed simple, but simple does not translate directly to easy. And even before the future flood of settings and complex use cases arrive, that setting beside the code is already a problem. The local approach feels intuitive because config stays close to the code that uses it, but real business use cases, daily team dynamics, production deployment pipelines, and distributed architectures are just not that simple.

This localized intuition leads to predictable problems: secrets leak into Git history and persist indefinitely, environment-specific values multiply into templating systems that nobody fully understands, and configuration changes require full application redeployments. These aren't edge cases or signs of poor discipline. They follow from where the config lives. A secret in a file beside the code is one mistaken commit away from Git history, and a value shipped with the code changes only when the code ships.

The Hidden Costs of Config-in-Code

Secrets leak despite good intentions. Teams start with .gitignore files and environment variables, but secrets find their way into version control anyway. A developer copies a working config to test something, a merge conflict gets resolved wrong, or someone commits from a branch that predates the .gitignore update. GitGuardian's State of Secrets Sprawl 2025 report counted 23.8 million secrets leaked in public GitHub commits in 2024, a count that covers hardcoded source as well as config files. Once a secret hits Git history, every clone and fork carries it. GitHub's own guidance on removing sensitive data says to revoke or rotate the secret first, because rewriting history can't reach copies already pulled. Rotating means tracking down every service that uses it.

Environment parity erodes. Each environment needs different database hosts, API endpoints, feature flags, and connection pool sizes. Teams respond with templating systems that substitute values at build time, or multiple config files with naming conventions like config.dev.json and config.prod.json, or environment variables that multiply until nobody remembers what SERVICE_ENDPOINT_OVERRIDE_V2 was supposed to do. When values are substituted at build time, staging and production don't even run the same image. Debugging then requires understanding not just the code but the entire config transformation pipeline.

Runtime selection, like ASP.NET Core's appsettings.{Environment}.json with environment-variable overrides, fixes the image problem but not the tie to releases. It keeps one image, but production values still ship in every build and change only with a release. With several override layers, the running value depends on which layer applied last.

Deployments couple to configuration. When config lives with code, changing a timeout value means rebuilding and redeploying the application. When five services share a database connection string, each holds its own copy in its own repository. Changing it means five pull requests and five deployments, ordered so no service still uses the old credential when it's revoked.

Configuration fragments across components instead of cohering around domains. In a multi-tenant system, a tenant's feature flags, rate limits, and credentials end up copied into every service that handles its requests, so one change for that tenant means editing each copy.

Config drift becomes invisible. A value gets changed manually in production to fix an urgent issue and never makes it back to staging, or a developer updates the dev config but not the template. Over time, debugging requires archaeology rather than analysis.

Homegrown Config Stores Recreate the Bootstrap Problem

The natural engineering instinct is to solve this problem yourself by storing configs in a database or building a config API.

Config kept in the application's own database creates a circular dependency: your service needs the database connection string to start, but the connection string is in the database. You end up hardcoding bootstrap credentials anyway, which defeats the purpose.

A custom config API sounds cleaner until you realize the config service itself needs configuration, deployment sequencing, and high availability. If the config API validates values against schemas in its own code, a new payment setting means deploying the config API first, then the payment service. You've traded one problem for a more complex one.

The fundamental issue is bootstrapping: how does the application know where to find its configuration before it has any configuration? Cloud-native config stores solve this by using identity that's already present in the runtime environment, such as IAM roles in AWS, managed identities in Azure, or service accounts in GCP. The application authenticates using credentials the platform provides automatically, which means no bootstrap secrets to manage. A homegrown store can authenticate the same way, but at that point you're rebuilding, operating, and keeping highly available what the managed store already provides.

What External Config Stores Provide

AWS has Parameter Store and Secrets Manager, Azure has Key Vault and App Configuration, GCP has Secret Manager, and HashiCorp Vault works across all of them.

Sensitive data never touches the codebase because it never needs to. Credentials live in the config store, encrypted at rest, with access controlled through the same IAM policies that govern your other cloud resources. When someone leaves the team, you revoke their access in one place rather than hoping they don't have local copies of config files. Audit trails show who accessed what and when, which proves invaluable when security asks "who has seen the production database password in the last 90 days?"

Applications become portable because the same artifact runs everywhere. The application asks "what environment am I in?" at startup and fetches the appropriate config, eliminating templating systems and environment-specific builds.

Organize Config Around Domains, Not Components

When configuration lives with code, it naturally organizes around components: the payment API has its config, the notification service has its config, and the reporting batch job has its config. This feels logical until you realize that configuration often cuts across components. A domain like "payments" might span three APIs, two background processors, and a gateway configuration.

With 50 APIs and 100 tenants, changing one tenant's settings starts with working out which services handle that tenant. When the payment domain gets restructured into separate authorization and settlement services, all the tenant configs need redistribution.

Domain-oriented config inverts this relationship. The same tenant configuration applies to whichever services handle that tenant's requests. When the payment domain splits, the new authorization and settlement services both read the same /production/tenants/<tenant>/payments path, so no tenant config moves and only their read permissions change.

The tradeoff is that shared domain keys become a contract across their consumers, so like a shared schema they evolve additively. Before changing a key, check the IAM read grants on its path, which list those consumers. Sharing a domain doesn't mean sharing every secret, though, because credentials can still sit in per-consumer sub-paths.

Component-specific configuration still exists, but only for component-specific concerns: performance tuning, networking behavior, resource limits, internal timeouts. Domain config answers "what does this tenant need?" while component config answers "how does this service behave?"

Hierarchical Config in Practice

External config stores enable domain-oriented organization through hierarchy. AWS Parameter Store shows the pattern, and other platforms work similarly.

Parameters follow a path structure like /production/tenants/acme-corp/feature-flags or /production/domains/payments/integration-credentials. The hierarchy carries access and ownership. Developers can read /dev/* while /production/* stays restricted to deployment pipelines. A change to /production/shared/* reaches every service in an environment on its next refresh or restart. Domain teams own their domain's subtree while platform teams manage cross-cutting infrastructure config.

The cost is small in practice. According to AWS Systems Manager's pricing page, standard-tier Parameter Store parameters (up to 10,000 per account and region) carry no storage charge and no API charge at default throughput. Secrets Manager costs more, at $0.40 per secret per month plus API calls, so a few hundred secrets run about $100 a month.

Integration with compute services removes friction. ECS task definitions can reference parameters directly, and the platform injects the values at startup. Lambda functions can read them through AWS's Parameters and Secrets Lambda Extension. Kubernetes pods can receive them as native secrets through the External Secrets Operator.

Config Changes Get Heavier, and They Should

A distributed config store removes the friction that adds nothing, like rebuilding artifacts and redeploying every consumer of a shared value. It keeps the friction that protects production. Configuration updates feel heavier because they are heavier, more like database migrations than editing a text file. You'll write change requests, get approvals, coordinate timing with deployments, and verify rollback procedures work.

Configuration changes in production systems should be intentional and controlled because a misconfigured timeout can cascade into an outage and a wrong feature flag can expose unfinished functionality to customers. Google's SRE book reports that roughly 70% of outages are due to changes in a live system, and a config change is exactly that kind of change. The ceremony forces you to think about backwards compatibility (will existing instances handle this new format?), rollback procedures (how do we revert if this breaks something?), and dependency ordering (which services need to restart first?).

Backwards compatibility matters more than it did, because config and code now roll back independently. A new key has to be additive, and the code has to tolerate its absence. It's the same expand-then-contract discipline a schema migration uses.

Approval alone isn't enough, because a change to /production/shared/* reaches every service. Changes with that blast radius should roll out in stages the way code does. AWS AppConfig, for example, first checks a change with validators against a JSON schema or a Lambda function. Its deployment strategies then release the change to a growing percentage of targets over a bake time and roll it back automatically when a CloudWatch alarm fires.

The one exception is the kill switch, because an incident can't wait for a change request. One can live under its own path, writable by on-call through a narrow IAM role.

What Still Belongs in Local Config

The goal isn't to externalize everything since that would create unnecessary dependencies and slow down development.

Application defaults like log formats, default retry counts, or internal timeout values that don't change between environments MIGHT belong in code. These define how the application behaves, not how it connects to external systems. I would still hesitate before coupling these to your code, however, because a constant default can become the value someone must change during an incident.

Framework configuration for HTTP server settings, thread pool sizes, or middleware ordering rarely varies by environment. When it does, you can override specific values from the external store while keeping sensible defaults local.

Development shortcuts that let engineers run the application locally without network dependencies make sense for rapid iteration. The key is ensuring the code path to fetch external config exists and works.

The decision rule is straightforward:

Externalize it if it's sensitive, varies by environment, or is shared across services.
Keep it local if it describes internal application behavior that stays constant everywhere.

This rule sits close to the line The Twelve-Factor App draws, where config is "everything that is likely to vary between deploys" and internal config that doesn't vary "is best done in the code." The difference is where the values come from. Environment variables can stay the interface, as when ECS injects parameters into them. But a flat set of variables managed per deployment has no hierarchy to assign ownership by path and no version history, so a versioned store makes the better source.

For prototypes and throwaway code, do whatever gets you moving fastest, but establish the external config discipline before real users or sensitive data enter the picture.

Where a Store Beats a Config Repository

An external store versions the values themselves, per environment, and its audit trail records who changed each one.

A separate config repository is the other way to keep config out of the code, and it versions config too. A GitOps pipeline injects it at deploy time as mounted files or a ConfigMap. That also keeps one image, and it adds reviewed diffs and atomic multi-key commits. For non-secret values that one service owns and changes only on release, it is a sound home. The store wins where the repository can't follow:

Secrets, where even encrypted-in-repo tools like SOPS leave old ciphertext in history for anyone who once held the key, while the store audits every read and rotates without a commit
Shared values, where one write replaces a config deploy to every consumer
Incident-time changes like a kill switch, which can't wait for a deploy
Per-path permissions, where a repository exposes everything in it to anyone who can read it

Versioning in the store also changes rollback. Parameter Store versions each parameter separately, so you roll back one value at a time. When several values must revert together, AWS AppConfig versions them as one configuration profile. Bad deploy? Roll back the config without touching application code. Services that poll for changes pick up the old value within their refresh interval, and services that read config at startup need a restart, not a rebuild and redeploy.

A writable store moves drift risk rather than removing it. The drift described earlier becomes detectable, because parallel paths like /staging/... and /production/... can be compared for missing or extra keys. It becomes preventable once write access to /production/* is limited to the deployment pipeline. Where a path must stay writable, like the kill switch, drift becomes attributable, because every write lands in the audit trail with the caller's identity.

Preventing Configs from Creeping Back into Code

Moving to external config stores doesn't automatically stop developers from committing secrets. Without active governance, you'll find credentials in code reviews months after "completing" the migration.

Code review culture matters more than tooling once the store exists. With no config file left for a secret to slip into, what remains takes judgment. Team values over process! Scanners catch values that look like secrets, while a reviewer catches the hardcoded endpoint or tenant flag no pattern recognizes. After the migration the rule is simple: any credential or environment-specific value in the repository is wrong. Make it part of your definition of done: "configuration fetched from external store, no hardcoded environment-specific values."

Pre-commit hooks can run secret scanners that check each commit for patterns that look like secrets, including API keys, connection strings, and private keys. Teams should be able to govern themselves, but for high risk products this might be needed.

Repository templates ensure new projects start with proper .gitignore files excluding .env, config.local.*, and secrets.*.

CI/CD validation catches anything that slips past local checks. Pipelines can scan for hardcoded values, verify that config references resolve to external stores, and fail builds that contain suspicious patterns. GitHub's push protection goes further, rejecting a recognized secret before it reaches the remote.

Practical Concerns and How to Handle Them

"What happens when the config store is unavailable?" A managed config store is still a dependency, and the more likely problem is throttling, not an outage. AWS documents Parameter Store's default throughput as 40 reads per second shared across an account and region, so a fleet scaling out or an ECS deployment replacing many tasks at once can hit ThrottlingException at startup. Cache config after the first fetch, spread reads across startup, enable the paid higher-throughput setting when the fleet needs it, and serve stale cached values during brief outages.

A new instance has no cache, though, so a throttle or outage during scale-out blocks exactly the instances you need. A local fallback copy could cover that gap, but a copy holding secrets must be encrypted, and getting its key to the instance is the bootstrap problem again. So most services should accept the startup dependency and size throughput for scale-out.

"Startup is slower now." True. Each fetch is a network round trip, usually small next to connection pool and dependency injection setup. Fetch at startup and cache with a refresh interval rather than forever, so a rotated credential still reaches running services.

"Local development gets harder." It gets different, not harder. SDKs and credential chains make fetching config from external stores transparent once each developer (and CI) has a scoped cloud role. The default is reading from a dev path, with each developer's writes confined to a personal sub-path. Local overrides are the shortcut for offline or isolated work. The one-time setup pays for itself in fewer "works locally, fails in production" bugs.

"We can't work offline." How often do you actually develop offline? Pulling dependencies, accessing Jira, talking to teammates, running CI/CD, and pushing code all require connectivity. When it does matter, keep a local-only setup that needs no store, such as a .NET Aspire app host that defines local resources and configuration in source control.

The Daily Experience Changes

Testing becomes more realistic because engineers can run local code against the non-secret values in remote staging or dev configs, with read access scoped to those paths, rather than maintaining local approximations that drift from reality.

Committed config files stop being a path for leaked credentials, and when developers never get read access to /production, production secrets stop passing through people at all. When you need to rotate a credential, you update one place. With a dual-credential scheme like Secrets Manager's alternating-users rotation, the old credential stays valid while every service picks up the new one on its next fetch or restart. The question "did we rotate that key in all environments?" finally has a definitive answer.

Making the Shift

Local config files feel simple and convenient right up until they aren't. External config stores trade familiar convenience for operational discipline, and that trade-off is sound.

Start with secrets by moving credentials out of the codebase and into a config store. Once that discipline is established, expand to environment-specific values, and eventually the pattern becomes natural: config comes from the environment, not from files.

Avoid Forcing REST onto Domain-Driven Architectures

Mon, 08 Dec 2025 17:33:24 +0000

For years I have seen teams wrestle with REST in domain-driven systems. They start with clean REST endpoints then gradually compromise as business operations don't map to resource CRUD. After years or just months, they've abandoned most of what made REST attractive anyway. They invent phantom resources, hide operations in request bodies, and add gateway routing layers, all while gaining few of the architectural benefits REST was supposed to provide.

Nested, navigable resource URLs assume one shared model of each entity. Domain-driven design deliberately rejects that assumption.

The mismatch isn't accidental. When you build systems around bounded contexts and business capabilities, RPC-style APIs provide better alignment without the architectural contortions. By REST I mean REST as most teams practice it, where resources with standard methods are the write path.

Bounded Contexts Break the Shared Resource Graph

Domain-driven design creates different models of the same entity within different contexts. In the Orders context, a "Customer" might be {id, shippingAddress, paymentMethod}. In the Identity context, that same person is a "User" with {id, email, authProvider, preferences}. Each context owns its own model because each serves different business capabilities.

Resource-centric API design, as most teams practice it, assumes you can navigate a graph of shared resources. The /users/{userId}/orders pattern looks clean until you ask: which service owns "users"? The Orders service needs customer information, but it doesn't own the canonical user representation. The Identity service owns users but knows nothing about orders. Serving /users/123/orders as a step in one graph, where a user resource leads to its orders, means either the Identity service learns about orders or a gateway stitches two contexts' models behind one URL. Either way you've coupled services that should remain independent.

Teams resolve this tension by giving up the shared graph while keeping REST-like syntax:

Add context prefixes like /orders/api/customers/{customerId}/orders, acknowledging that "customers" in the Orders context aren't the same as "users" in Identity
Map external-facing /users/{id}/orders to internal /orders-service/customers/{id}/orders through gateway routing
Flatten to search-style endpoints like /orders?customerId={id}, dropping the navigational hierarchy entirely

Each approach acknowledges the same reality: there is no single "user" resource to navigate from. What all three give up is the navigable graph of shared entities, which is the part of resource design that made /users/{userId}/orders look clean in the first place. Each context ends up publishing its own resources in its own vocabulary.

None of this is a case against REST's actual constraints. Roy Fielding wrote in "REST APIs must be hypertext-driven" that a REST API must not define fixed resource hierarchies at all, and a filtered collection is a perfectly good resource. Nor does RPC solve ownership, since an RPC call that lists a customer's orders has to live in one context too. What splitting into contexts removes is the graph that made a resource model look like the whole design. Each context is left with its own small set of resources. Whether those resources can also carry the context's writes depends on what those writes are.

Business Operations Don't Map to Resource CRUD

REST works well when business operations map cleanly to create, read, update, and delete. Even simple operations can break down when they carry business meaning beyond field changes. Domain-driven design makes those operations the norm. An aggregate changes only through its root, and the root enforces the aggregate's invariants. Its write path is already a set of commands like cancel or ship.

Consider "cancel an order." In REST terms, this looks like updating the order's status field: PATCH /orders/{id} with {"status": "cancelled"}. But cancellation isn't just a field update. It triggers refund processing, releases reserved inventory, sends customer notifications, and updates analytics. The operation has validation rules (can't cancel shipped orders) and side effects that don't belong in a generic resource update.

Forcing Operations into Resources Hides Them

Teams force this into REST through increasingly awkward patterns:

Hiding operations in PATCH bodies: A PATCH /orders/{id} request with {"status": "cancelled"} technically updates the resource, but the server must detect this specific status change and trigger business logic. The handler becomes a switch statement checking what changed. Status changed to "cancelled"? Run the cancellation workflow. Status changed to "shipped"? Run the shipping workflow. Only the address changed? Just update the field. Clients can't tell from the API which field changes are simple updates and which trigger complex workflows. Error handling becomes inconsistent because a failed refund during cancellation behaves nothing like a failed field validation during an address update.

Breaking transitions into sub-resources: A POST /orders/{id}/cancellations creates a "cancellation" resource, but cancellations aren't independent entities. They're events that happen to orders. Now you have /orders/{id}/cancellations/{cancellationId} for something that has no meaningful lifecycle of its own.

Inventing workflow resources: A POST /orders/{id}/cancel-requests creates a "request" resource that models a workflow state. The order itself is the real entity; the request is a phantom abstraction invented to maintain REST's resource-centric appearance.

Each of the three patterns either hides the operation behind a standard verb or invents a resource to hang it on, while preserving REST-like URL structures. If even "cancel an order" doesn't fit the standard verbs cleanly, more complex operations like splitting a shipment fit them worse.

Sub-Resources Fit Identities, Not Transitions

The sub-resource itself isn't what fails in the last two patterns. A sub-resource earns its URL when the element has its own identity and its own lifecycle, like a label on an issue, a collaborator on a repository, or an item on a subscription. Each of those can be created, addressed, and removed on its own, and giving it an address takes an entire category of ambiguity out of the parent's update body.

A transition earns no such URL. A cancellation or an email verification is something the order or the customer goes through, not something that lives beside it. Turning it into a stored collection to satisfy a URL convention invents an entity the domain doesn't have. Independent identity gets a sub-resource. A transition gets a named operation.

A singular PUT /orders/{id}/cancellation looks like a way around this rule. It avoids the stored collection, and PUT tells clients and proxies that a retry is safe. But a retried cancel must still refund only once, so the promise holds only if the server deduplicates the refund and the inventory release, the same deduplication a named operation needs. The URL still presents a transition as a resource, and DELETE on it reads as un-cancel, which the domain may not allow.

A few cases look like exceptions to the rule, but none of them turns the transition itself into a resource:

The order's history or an audit log can expose cancellations for support and finance to query, while the write stays a named cancel operation.
A cancellation earns its own sub-resource only when clients create and manage it as a thing in its own right, like an approval request that someone else accepts or rejects.
A transition that runs long enough to have a status of its own, like a refund that can fail partway, does need something clients can check. That is a handle to the running operation, which the named operation can return, not a new entity stored beside the order.

An API Made of Custom Methods Is RPC

REST itself allows named operations, up to a point. Roy Fielding's "It is okay to use POST" says REST never required PUT for every state change, and Google's AIP-136 defines custom methods such as POST /v1/{book}:archive for operations the standard verbs don't cover. But when every meaningful business operation becomes a POST to a named verb, the API is RPC with resource-shaped URLs. Google's guidance makes resources the default and custom methods the exception. That default pays off when most of an API is standard methods, because uniform create, update, and delete conventions cover most of what clients change.

Count the State Changes That Carry Rules

To tell which kind of API a context needs, apply this test:

List its state changes.
Mark each one that has preconditions or side effects beyond saving the field. Editing a shipping address before fulfillment passes as an update, while cancel, ship, and refund don't.
Move every marked change out of the generic update and into a named operation.
If the marked changes are most of the list, the exceptions become the context's write API, with resource reads beside it.

The count in step 4 doesn't change how any single endpoint is designed. It decides whether the context can lean on a resource API's conventions for naming, errors, and retries, or has to set its own. A few custom methods can follow the conventions their resources set, but an API made mostly of them has to define its own.

Designing for that on purpose means each operation gets its own request type, its own preconditions, and its own error contract. A client calling cancel then sees "already shipped" and "refund failed" as distinct, documented outcomes rather than generic update errors. It also means the team owns conventions that a resource model would have supplied, because an operations-first API without them sprawls into bespoke verbs that each behave differently. The minimum is:

A verb naming rule
One error envelope with per-operation codes
Idempotency keys on every write, like the Idempotency-Key header Stripe's API accepts on every POST
One shape for the handle a long-running operation returns

REST's Technical Benefits Rarely Apply

REST's architectural constraints provide real benefits in certain contexts. HTTP caching through intermediary proxies can reduce server load, hypermedia enables clients to discover capabilities dynamically, and the uniform interface allows generic tooling to work across different APIs. Operation-heavy contexts rarely benefit from any of these.

Caching assumes stable representations. Neither style can share-cache order reads, and staleness is why. A CDN caching /orders/12345 doesn't know that an order was just cancelled, shipped, or had items refunded. You can set Cache-Control: max-age=60, but that means clients might see stale data for up to a minute after significant business events. For an order status page, showing "Processing" when the order already shipped erodes user trust. So these reads end up private, short-lived, or uncached.

Conditional requests with ETags avoid serving stale data, but every read still reaches the origin to revalidate. They save bandwidth, and they save server work only where the server can check a version without loading the whole order. REST caching works well for static content or slowly-changing reference data, not for entities whose state changes through business operations. Reads can stay on GET, but caching gives no reason to model transitions as resources.

Hypermedia assumes discoverable, stable relationships. The idea is that clients navigate links in responses rather than hardcoding URLs. But in domain-driven systems, what operations are available depends on business rules, not just resource state. Can this order be cancelled? That depends on payment status, shipping status, time since placement, and customer tier. Encoding all that context in hypermedia links means the server must evaluate business rules on every response just to populate the _links section.

Hypermedia still rarely pays off here, but not because of that cost. The same rule evaluation is also hypermedia's strongest case in a domain system. The server is the one place that knows the rules, and a client that follows a cancel link never duplicates them. A UI that shows a Cancel button on every order view pays for the same rule evaluation in either style. What decides it is whether clients follow links instead of hardcoding URLs. Internal service-to-service clients rarely do, and most teams never implement hypermedia controls for them because the complexity isn't worth it. Wherever clients hardcode URLs, in any kind of context, hypermedia is a weak reason to choose REST.

Uniform interface assumes generic operations. REST's power comes from treating all resources the same way: GET retrieves, PUT replaces, DELETE removes. Generic tooling can work across APIs because the verbs are standardized. But domain operations aren't generic. "Cancel order" and "cancel subscription" may share a verb in English, but they have completely different validation rules, side effects, and error modes. Forcing them into the same PATCH or DELETE pattern hides these differences behind a uniform interface that clients must then learn to navigate through documentation and tribal knowledge.

Uniformity's practical value sits mostly in the plumbing. Client retry rules key off the method, gateways treat GET as safe, and rate limits and dashboards key off method and path. An operations-first context keeps nearly all of it, because its reads stay GET. Its transitions would have been POSTs or status PATCHes in a resource design too, and a client can't safely retry either one blindly. What it does give up is tooling that assumes resource semantics, like generated admin screens and generic CRUD clients, and those matter least for writes that a generic client shouldn't be making.

Few teams collect these benefits even where they would apply. Most learn "REST" from tutorials teaching HTTP + JSON + resource URLs, never encountering the actual constraints that make REST architecturally significant. They end up with HTTP-based RPC that pretends to be RESTful without gaining any of the benefits Fielding described in the REST chapter of his dissertation.

Choose Based on Your Domain Model

Neither approach is universally better. The choice depends on how your domain naturally models work. Most domain-driven systems contain both kinds of context, since supporting subdomains are often plain CRUD. So the choice is made per bounded context and, inside a context, per operation.

REST fits entity-driven systems. Media libraries, inventory catalogs, and configuration management often align well with REST. Resources have stable identities, relationships are navigable, and standard CRUD operations match what the business actually does. A photo library really is a collection of photo resources that you create, read, update, and delete. REST's constraints provide genuine value here: caching works because photos don't change often, hypermedia can express album-to-photo relationships for clients that follow links, and generic tooling can operate across different media types.

RPC fits operation-driven systems. Operation-heavy contexts are the ones where most state changes carry rules and side effects. They align better with explicit operations, meaning endpoints named after what the business does, whether they run over plain HTTP and JSON or a framework like gRPC. Endpoints like /orders/cancel, /orders/refund, and /orders/split-shipment map directly to what the business actually does. The API's vocabulary is the domain's vocabulary. Each endpoint serves a single purpose, so the API's structure, not a handler's switch statement, keeps transitions apart, and each one's request type and errors can be generated and documented on their own.

The URL form matters far less than that contrast. Whether it reads POST /orders/cancel or the AIP-style POST /orders/{id}:cancel, either beats a PATCH /orders/{id} that might update the order status, add line items, change shipping addresses, or trigger cancellation depending on the request body. The AIP style does keep the order ID visible to gateway rules and logs keyed on path.

Either form can be operations-first, and an AIP-style API built mostly from custom methods is an operations-first API with resource-style URLs. What makes a design operations-first is where it starts. It starts from the operations and their contracts, with resources added for reads. Starting there also means fields with workflows behind them, like status, can't be changed through a generic update at all.

What the domain does	What fits
Creates, reads, updates, and deletes entities with stable identities	REST resources
Manages an element with its own identity and lifecycle, like a label on an issue	A sub-resource
Moves an entity through a transition with rules and side effects, like cancelling an order	A named operation
Serves data that changes slowly and is read widely	REST with HTTP caching

Elegance doesn't matter here. What matters is which style matches how your domain actually works. Where a context manages entities with stable identities, use REST for them and for reads. Where it executes business operations with rules and side effects, stop forcing those operations into resource updates, even on an entity like an order.

Match your API style to your domain model, not to industry conventions or resume-driven development.

Architecture Pattern: "Compound Components" and Advanced Projection with `ngProjectAs`

Sat, 29 Nov 2025 17:37:29 +0000

When building a Design System or a library of shared components, the most difficult challenge is balancing consistency with flexibility.

You want all your Modals to look the same (consistency), but some Modals contain forms, others contain text, and others contain complex grids (flexibility).

The Architectural Pattern that solves this is Content Projection (specifically Multi-Slot Projection).

The Basics: The "Select" API

When you build a container, you define its API not by Inputs, but by Slots.

@Component({
  selector: 'app-layout',
  template: `
    <header>
      <ng-content select="nav"></ng-content>
    </header>
    <main>
      <ng-content></ng-content>
    </main>
  `
})
export class AppLayoutComponent {}

The Senior "Gotcha": Wrapper Elements

Here is a problem 99% of devs hit.

Imagine your app-layout expects a <nav> tag because of select="nav".

But you want to project a custom component called <app-top-bar>.

<app-layout>
  <app-top-bar></app-top-bar>
</app-layout>

Your app-top-bar will fall into the default slot (Main), not the Header slot.

The Junior Fix:
Wrap it in a nav tag.

<app-layout>
  <nav> <app-top-bar></app-top-bar>
  </nav>
</app-layout>

Problem: You just introduced an extra DOM node (<nav>) that might mess up your Flexbox or Grid layout.

The Senior Fix: ngProjectAs
Angular has a special attribute that allows you to "disguise" an element so it matches a specific selector, without adding extra DOM nodes.

<app-layout>
  <app-top-bar ngProjectAs="nav"></app-top-bar>
</app-layout>

This tells Angular: "Treat this component as if it were a <nav> tag for the purposes of projection."

The "Projected Content" Lifecycle Risk

As a Senior Developer, you need to know the performance cost.

Projected content is instantiated EAGERLY.

If you project a heavy component:
<app-modal><app-heavy-chart></app-heavy-chart></app-modal>

The app-heavy-chart is created, its constructor runs, and its ngOnInit runs immediately, even if the modal is hidden via display: none.

The Optimization:
If the content is extremely heavy, do not use basic Content Projection. Use Template Projection (ng-template).

<app-modal [contentTemplate]="myChart"></app-modal>

<ng-template #myChart>
  <app-heavy-chart></app-heavy-chart>
</ng-template>

// Child (Modal)
@Input() contentTemplate: TemplateRef<any>;

<ng-container *ngTemplateOutlet="contentTemplate"></ng-container>

This ensures the chart is not instantiated until the Modal actually renders the template outlet.

Mastering these nuances—ngProjectAs and TemplateRef—is what separates a component library author from a component user.

The Senior Developer's Blueprint: Implementing Container vs. Presentational Architecture in Angular

Sat, 22 Nov 2025 08:47:37 +0000

In my 8 years as a frontend engineer, I’ve seen many trends come and go. But one architectural principle has remained the absolute bedrock of scalable application design: the separation of Container (Smart) and Presentational (Dumb) components.

This isn't unique to Angular—it’s a core concept in React and Vue as well. But Angular's structured nature makes it particularly powerful to implement.

If your codebase feels brittle, if you can't reuse UI widgets, or if your unit tests require endless mocking of services just to check if a <div> exists, it's time to adopt this pattern.

The Problem: Coupled Chaos

Let's look at a typical "junior" implementation of a Product List.

You might have a ProductListComponent that:

Injects ProductService and CartService.
Injects ActivatedRoute to read query params for filtering.
Has an ngOnInit that calls this.productService.getProducts().
Has methods like addToCart(id) that call the cart service.
Crucially, its template defines the exact HTML and CSS for how a product card looks.

You have tightly coupled your Business Logic (fetching data, managing cart state) with your UI Concern (rendering a product image and title).

If you want to show a "Recommended Products" section on the cart page, you can't reuse this component. You'd have to copy-paste the HTML/CSS of the product card, leading to code duplication and UI inconsistencies.

The Solution: The Smart/Dumb Split

We need to take a machete to that component and split it into two distinct roles.

1. The Presentational Component ("Dumb")

This component’s sole responsibility is rendering UI. It should be pure and predictable.

Inputs: It receives everything it needs to render via @Input().
Outputs: It communicates user interaction via @Output() events.
Dependencies: NONE. It should not know that services exist.

Let's extract the product card UI.

// product-card.component.ts (Dumb)
@Component({
  selector: 'app-product-card',
  template: `
    <div class="card">
      <img [src]="product.image" [alt]="product.name">
      <h3>{{ product.name }}</h3>
      <p>{{ product.price | currency }}</p>
      <button (click)="addToCartClicked.emit(product.id)">
        Add to Cart
      </button>
    </div>
  `,
  // Pure UI components should always use OnPush for performance
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class ProductCardComponent {
  // The data required to render
  @Input({ required: true }) product!: Product;

  // The event to signal the parent
  @Output() addToCartClicked = new EventEmitter<string>();
}

This component is now a reusable UI asset.

2. The Container Component ("Smart")

This component is the "glue." It connects the application to the UI. It usually corresponds to a specific view or route.

Responsibilities: State management, communicating with services, handling routing.
Template: Mostly contains other components, passing data down and listening for events up.

// product-catalog.page.ts (Smart)
@Component({
  template: `
    <div class="catalog-page">
      <h1>Our Products</h1>
      <div class="grid">
        <app-product-card
          *ngFor="let p of products$ | async"
          [product]="p"
          (addToCartClicked)="handleAddToCart($event)">
        </app-product-card>
      </div>
    </div>
  `
})
export class ProductCatalogPage {
  // Inject dependencies
  private productService = inject(ProductService);
  private cartService = inject(CartService);

  // Manage data streams
  products$ = this.productService.getAll();

  // Define business logic
  handleAddToCart(productId: string) {
    console.log('Smart component handling logic for ID:', productId);
    this.cartService.addItem(productId);
  }
}

The Transformative Impact

By adopting this pattern, you change how you work:

Parallel Development: One developer can build the "Dumb" UI library using Storybook, focusing purely on CSS and visual states, while another developer builds the "Smart" containers and business logic.
Fearless Refactoring: You can completely rewrite your ProductService or change your state management library from NgRx to Elf, and you won't have to touch a single line of code in your ProductCardComponent. The UI is isolated.
Design Consistency: Since your UI components are reusable, you ensure that a Product Card looks the same everywhere in the app.

It requires discipline to not just inject a service into a component "real quick" because it's easier. But resisting that urge is what builds professional, scalable frontend architecture.

Monoliths for Discovery, Microservices for Optimization

Thu, 20 Nov 2025 23:41:52 +0000

I know, I know. It is another post about microservices versus monoliths. The debate feels exhausted at this point. Yet every time I start a new project, I find myself weighing the same questions. Not because the answer is unclear, but because the answer genuinely depends on where you are and what you're trying to learn.

The choice isn't about finding the "right" architecture in the abstract. It's about choosing what fits your context, your constraints, and most importantly, what you need to discover.

Principles That Decide the Choice

Microservices Are Optimizations, Monoliths Enable Discovery

Microservices are optimizations for specific problems: team scaling, independent deployment, technology diversity. They're solutions to constraints you've already identified. Monoliths, on the other hand, accelerate discovery. They let you learn where boundaries should be, understand domains as they reveal themselves, and validate assumptions quickly without the overhead of distributed systems.

That overhead is concrete. Once two parts of a system talk over the network, every call can time out, fail halfway, or arrive twice, and data that used to change in one transaction now needs a consistency strategy. Each service also needs its own deployment pipeline, monitoring, and on-call coverage. Martin Fowler calls this the microservice premium, and in his post of that name he advises against even considering microservices "unless you have a system that's too complex to manage as a monolith."

The premium grows with every service added. In "Goodbye Microservices," Alexandra Noonan describes how Segment split its event delivery into one service per destination, for a sound reason. A slow destination's retries had flooded a shared queue and delayed all the others. The split ended at more than 140 services. Shared libraries drifted apart, and three full-time engineers spent most of their time keeping the system alive, until the team merged the services back into one. The signal justified separating slow destinations from the rest, and it didn't justify a service for every destination.

The premium hurts most while the domain is still unclear, because early boundaries are mostly guesses. Inside one process, a wrong guess is fixed with a refactoring. You move a class or change a method signature, and the compiler finds every caller. Across services, the same correction means changing two APIs, coordinating two deployments, and migrating data between two databases. Fowler's companion post, "MonolithFirst," makes this argument. It also reports that almost all the successful microservice stories he had heard of started with a monolith that grew too big and was broken up. He offers that as an informal observation, not a study.

Start with what helps you learn fastest, then optimize when you understand what actually needs optimizing.

Monoliths Don't Excuse Poor Code Quality

The stigma around monoliths comes from poor practices, not the architecture itself. Terrible monoliths exist, but so do terrible microservices. A monolith whose modules call each other's internals and write each other's tables is hard to change and harder to split. A set of microservices that share tables and must deploy together has the same coupling, with network calls added. What decides whether either system stays changeable is good design discipline, meaning SOLID principles applied at the module level and clear boundaries. Each module depends on the others' public interfaces and never on their internals.

The deployment model does change one thing. A process boundary makes reaching into another module's internals impossible, while inside a monolith it takes one import. That enforcement is part of what the microservice premium buys, but during discovery it isn't worth the price, because the same process boundary makes every module boundary expensive to move.

A monolith can get most of that enforcement more cheaply. It needs it, because good intentions lose to deadlines. Give each module its own database schema, and have CI load and test each module with only the modules it declares as dependencies. A shortcut then fails a build instead of slipping through review. Moving a boundary still means editing a dependency list and a schema in one repository rather than redeploying two services.

Neither the per-module schemas nor the CI checks add a runtime component, a network hop, or a second deployment. Both need upkeep, such as test setups for each module, and they are far harder to retrofit than to start with.

Ship Before the Architecture Is Perfect

Ship and learn. Every week spent settling the architecture before launch is a week without users to show which parts of the design matter. The better approach is to make reversible decisions, establish clear boundaries, and iterate based on what you learn from real usage. Perfection is a moving target. Momentum matters more.

Shipping before the design settles works only if wrong guesses are cheap to undo, and the starting choice decides how often you pay for distribution. Extracting a module from a monolith still means moving its data and taking on partial failure for every call across the new boundary. A team that starts with a modular monolith pays that distributed cost once per boundary it has already validated. A team that starts with services pays it for every guess, and again for each guess it has to correct. Either way, a decision stays reversible when undoing it touches one module instead of every caller, which is why the next two principles are about boundaries.

Data Boundaries Matter From Day One

Define data ownership early, even if you're starting with a monolith. Sharing one database between modules, or even between early services, isn't inherently wrong when you're just getting started. It works as long as each table has one owning module, and everything else goes through that module's code instead of querying its tables directly.

Without that rule, extraction gets expensive. When three modules write to the same orders table, pulling the order module out means finding and rewriting every one of those queries. Each cross-module join also becomes a network call or a copy of the data. Tangled data models trap teams in legacy architectures.

The ownership rule keeps the cheap in-process refactoring from the first principle. When a table changes owner in a modular monolith, the compiler and the test suite find the code to change, and there are no dual writes between two databases. The rule makes an ownership change a schema migration inside one database and one deployment, rather than a data move between two services.

Abstract Infrastructure Early

Put one routing layer you control in front of the monolith early. An API gateway works, and so does the reverse proxy or ingress it already runs behind. Either gives you flexibility before you know what your final infrastructure will look like. When clients call that layer instead of the monolith's own address, extracting a service later can keep the address clients already use, because the route moves there. That holds when the extracted module owns its own URL paths and the new service keeps the old contract.

The routing layer doesn't help with the harder server-side work of partial failure and consistency. A dedicated gateway is also one more component to run and one more network hop. It pays off most when you have clients you can't update all at once, such as mobile apps or partner integrations. For those systems, the routing layer keeps an extraction from turning into a coordinated client release.

The Strongest Case Against Starting With a Monolith

Stefan Tilkov answered Fowler with "Don't start with a monolith." He argues that a monolith's parts "will become extremely tightly coupled to each other" through shared libraries, in-process calls, and shared domain objects and persistence models, and that splitting one up afterward is extremely hard. He is right about what happens to a monolith built without discipline. That coupling is the reason the principles above exist.

Module boundaries, one owner per table, and a routing layer between clients and the deployment don't make a later split cheap, but they make it a matter of cutting along seams that already exist. The queries to rewrite are the ones the owning module already exposes, instead of a search through every module for whoever touches the data. Public accounts that follow one system from monolith discovery through extraction along settled seams are rare, so this rebuttal rests on the cost mechanism above more than on a body of case studies.

His argument also marks where this approach stops applying. When the boundaries are already known, as when a team rebuilds a system whose domain it has run for years, there is less left to discover. Building separately deployable parts from the start then gives up little. Discovery is the reason to start with a monolith, so the case for one weakens as the amount left to discover shrinks.

Some constraints are known on day one even when the domain is new. An organization that starts a new product with several teams already has the coordination constraint. So does a component that must sit apart for compliance or security, such as card handling kept out of the rest of the system's PCI scope. A known constraint is what the optimization exists for, so a few coarse services along those lines, each a modular monolith inside, fit that case better than one shared deployment. Discovery then happens within each service, where moving a boundary is still cheap.

My Approach: Domain-Based Modular Monoliths

Start with domain-based modules: one modular monolith organized along natural business boundaries, which Eric Evans's domain-driven design calls bounded contexts. This gives you:

Clear separation of concerns from the beginning
Teams that own their domain's code, even while they share a deployment
A migration path to microservices that follows existing module boundaries instead of cutting new ones
Faster initial development than building distributed systems from day one

Shopify took this route with its main codebase. Kirsten Westeinde's account of the work describes reorganizing the code by business domain, such as orders, shipping, and billing, and building tooling to check that components talk only through their public interfaces. The goal, in her words, was more modularity "without increasing the number of deployment units."

Five years later, Gannon McGibbon and Chris Salzberg's "A Packwerk Retrospective" reported that static checks from Packwerk, the boundary-checking tool Shopify later built and open-sourced, hadn't been enough. A package with all its recorded violations resolved still failed to boot when loaded on its own, because of dependencies the static analysis couldn't see. What they found trustworthy was running code, so once they got that package to boot with only its own code loaded, they added a CI step that runs its tests in isolation. Packwerk 3.0 also dropped its privacy checks, the static rule meant to keep other packages out of a package's internals.

Boundaries hold when something executes them, and a folder structure or a lint rule alone tends to erode one convenient shortcut at a time. Where only static checks guard the boundaries, Tilkov's coupling warning holds. Shopify's answer was a stronger check inside the monolith, not a move to services.

Split When the Evidence Shows Up

Split into microservices when there's actual evidence it's needed: independent scaling requirements, team coordination becoming a bottleneck, or specific technology needs that justify the operational complexity.

Each of those signals, plus one more, can be checked instead of argued:

Independent scaling: one module's load differs so much from the rest that scaling the whole deployment to meet it mostly buys capacity nothing else uses
Team coordination: teams routinely wait on each other to release, or a shared test suite and deploy queue hold every change to the pace of the slowest one
Technology needs: a module needs a runtime or data store the rest of the system can't host, and the gain outweighs operating a second stack
Fault isolation: one part's failures or slowdowns keep spreading to unrelated parts, and timeouts, bulkheads, or separate queues inside the deployment haven't contained them

These signals arrive late, once the pain is present. The monolith also gives an earlier one. Track the share of merged changes that touch more than one module, and how often a change moves code or tables between modules. Watch them over several releases while feature work continues. The boundaries have probably settled when three things hold: the first number is falling, the second has dropped to near zero, and no duplicated logic or swelling module is absorbing the work. That says the seams are stable enough to plan an extraction around. It isn't a reason to extract, which still waits for one of the signals above.

A signal tells you that something needs to be separated, and the module boundaries tell you where the seam already runs. Until a signal shows up, the monolith is still doing the job it was chosen for, which is teaching you where the boundaries belong.

Event-Driven Updates with ThingsDB

Wed, 19 Nov 2025 08:55:19 +0000

In the world of real-time applications, delivering instantaneous updates to users is foundational. From collaborative documents to live chat applications, the ability to instantly reflect changes across all connected clients can make or break the user experience. ThingsDB, with its robust event-driven architecture, offers a powerful solution for achieving this.

Traditionally, implementing event-driven updates in a real-time application, like a chat room, often followed a pattern that could lead to unnecessary complexity. Let's break down the classic approach and then explore how ThingsDB's new "emit to peers only" feature simplifies this process.

Traditional Flow

Imagine a simple chat application. When a user sends a message, the desired flow is that the message appears instantly on the users screen, and via an event for everyone in the chat room.

Here's how that flow typically worked:

A chat client sends a new message to the ThingsDB server.
ThingsDB stores the message and then emits an event to a designated "room" (or topic) that all connected clients are listening to.
All clients subscribed to that room receive the event and display the new message in their respective chat interfaces.

This approach works, but it introduces a subtle challenge: the client that sent the message also receives the same event back.

Here's a visual representation of the traditional flow:

Self-Inflicted Updates

While seemingly harmless, receiving one's own message back as an event can create issues, especially if the client is designed to immediately display the message locally upon sending. This leads to a double-update scenario: the message appears instantly when sent, and then again when the event is received from the server.

To avoid this redundancy, developers often resorted to complex workarounds like implementing intricate code to detect if an incoming event originated from the current client, perhaps by including a unique client ID with each emitted event.

The ThingsDB Solution: Emitting to Peers Only

ThingsDB addresses this challenge elegantly with its new "emit to peers only" option. This powerful feature allows you to broadcast events to all listeners within a room except the one that initiated the event.

Here's how the simplified flow works:

A chat client sends a new message to ThingsDB, explicitly indicating that the event should only be emitted to other peers and displays the message in the chat screen.
ThingsDB stores the message and then emits the event to the designated room. Crucially, it filters out the originating client from the list of recipients.
All other clients subscribed to the room receive the event and display the new message.

Sender Updates Locally: The sending client, having already displayed the message locally, does not receive a redundant event from the server.

Let's visualize this improved flow:

Beyond Chat Rooms

The "emit to peers only" concept extends far beyond chat applications. Consider any scenario where a client initiates an action and immediately reflects that change locally, while also needing to inform other connected clients:

Collaborative Document Editing: When a user types a character, it appears instantly on their screen. Other collaborators see the update via an event, but the typing user doesn't need to process their own keystroke as an incoming event.
Real-time Dashboards: A user performs an action that updates a metric locally. Other users viewing the dashboard receive an event to update their views, but the initiating user's dashboard is already updated.
Gaming: A player moves their character. The local client updates the character's position instantly. Other players receive an event to update the character's position on their screens.

Conclusion

ThingsDB's "emit to peers only" feature is implemented by all supported clients and is addressing a common pain point in real-time application development. For any application built on the promise of instant updates, utilizing this feature means spending less time debugging logic and more time writing clean, purposeful code.

Decorate services in ASP.NET Core, step by step

Fri, 14 Nov 2025 11:21:56 +0000

Decorator pattern, in short

The decorator pattern is a structural design pattern that lets you add behavior to an object at runtime by wrapping it with another object that has the same interface. The wrapper forwards calls to the inner object, then adds extra work before or after the call. You keep the original contract, you can stack multiple decorators, and you avoid subclass explosion by preferring composition over inheritance.

Key points

Intent, attach additional responsibilities to an object dynamically
How, wrap an object that implements the same interface and forward
calls
Good for cross cutting concerns like logging, retry, caching,
metrics, authorization
Benefits, core code stays simple, behaviors are pluggable and
testable, decorators compose
Trade offs, more indirection and wiring, the order of decorators
matters

Why decorate in ASP.NET Core

Decoration lets you add cross cutting behavior around a service without touching its core code, for example retry, logging, metrics, caching. It keeps concerns separated and easy to test.

Packages

dotnet add package Scrutor
dotnet add package Polly

Core service

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;

public interface IInvoicesClient
{
    Task<PagedResultDtoOfInvoice> GetInvoicesAsync(
        string filter, string orderBy, string include,
        int? pageIndex, int? pageSize, bool? transactionCurrency, bool? skipRounding,
        CancellationToken ct = default);
}

public sealed class InvoicesClient : IInvoicesClient
{
    private readonly HttpClient _http;
    private readonly string _baseUrl;
    private readonly Func<string> _getToken;
    private static readonly JsonSerializerOptions _json = new() { PropertyNameCaseInsensitive = true };

    public InvoicesClient(HttpClient http, string baseUrl, Func<string> getToken)
    {
        _http = http;
        _baseUrl = baseUrl.TrimEnd('/');
        _getToken = getToken;
    }

    public async Task<PagedResultDtoOfInvoice> GetInvoicesAsync(
        string filter, string orderBy, string include,
        int? pageIndex, int? pageSize, bool? transactionCurrency, bool? skipRounding,
        CancellationToken ct = default)
    {
        var url = BuildUrl(_baseUrl, filter, orderBy, include, pageIndex, pageSize, transactionCurrency, skipRounding);

        using var req = new HttpRequestMessage(HttpMethod.Get, url)
        {
#if NET5_0_OR_GREATER
            VersionPolicy = HttpVersionPolicy.RequestVersionOrHigher
#endif
        };

        var token = _getToken?.Invoke();
        if (!string.IsNullOrEmpty(token))
            req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

        using var resp = await _http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, ct).ConfigureAwait(false);
        resp.EnsureSuccessStatusCode();

        await using var stream = await resp.Content.ReadAsStreamAsync(ct).ConfigureAwait(false);
        return await JsonSerializer.DeserializeAsync<PagedResultDtoOfInvoice>(stream, _json, ct).ConfigureAwait(false)
               ?? new PagedResultDtoOfInvoice();
    }

    private static string BuildUrl(
        string baseUrl, string filter, string orderBy, string include,
        int? pageIndex, int? pageSize, bool? transactionCurrency, bool? skipRounding)
    {
        var q = System.Web.HttpUtility.ParseQueryString(string.Empty);
        if (!string.IsNullOrWhiteSpace(filter)) q["filter"] = filter;
        if (!string.IsNullOrWhiteSpace(orderBy)) q["orderBy"] = orderBy;
        if (!string.IsNullOrWhiteSpace(include)) q["include"] = include;
        if (pageIndex.HasValue) q["pageIndex"] = pageIndex.Value.ToString();
        if (pageSize.HasValue) q["pageSize"] = pageSize.Value.ToString();
        if (transactionCurrency.HasValue) q["transactionCurrency"] = transactionCurrency.Value ? "true" : "false";
        if (skipRounding.HasValue) q["skipRounding"] = skipRounding.Value ? "true" : "false";
        return $"{baseUrl}/invoices?{q}";
    }
}

Decorators

using Polly;
using System.Net.Sockets;

public sealed class RetryInvoicesClientDecorator : IInvoicesClient
{
    private readonly IInvoicesClient _inner;
    private readonly IAsyncPolicy _retry;

    public RetryInvoicesClientDecorator(IInvoicesClient inner)
    {
        _inner = inner;
        _retry = Policy
            .Handle<HttpRequestException>()
            .Or<IOException>()
            .Or<SocketException>()
            .Or<TaskCanceledException>(ex => !ex.CancellationToken.IsCancellationRequested)
            .WaitAndRetryAsync(3,
                attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)) +
                           TimeSpan.FromMilliseconds(Random.Shared.Next(0, 750)));
    }

    public Task<PagedResultDtoOfInvoice> GetInvoicesAsync(
        string filter, string orderBy, string include,
        int? pageIndex, int? pageSize, bool? transactionCurrency, bool? skipRounding,
        CancellationToken ct = default)
    =>
        _retry.ExecuteAsync(t =>
            _inner.GetInvoicesAsync(filter, orderBy, include, pageIndex, pageSize, transactionCurrency, skipRounding, t),
            ct);
}

Logging decorator

public sealed class LoggingInvoicesClientDecorator : IInvoicesClient
{
    private readonly IInvoicesClient _inner;
    private readonly ILogger<LoggingInvoicesClientDecorator> _log;

    public LoggingInvoicesClientDecorator(IInvoicesClient inner, ILogger<LoggingInvoicesClientDecorator> log)
    { _inner = inner; _log = log; }

    public async Task<PagedResultDtoOfInvoice> GetInvoicesAsync(
        string filter, string orderBy, string include,
        int? pageIndex, int? pageSize, bool? transactionCurrency, bool? skipRounding,
        CancellationToken ct = default)
    {
        var sw = System.Diagnostics.Stopwatch.StartNew();
        try
        {
            _log.LogInformation("Invoices request pageIndex={PageIndex} pageSize={PageSize}", pageIndex, pageSize);
            var res = await _inner.GetInvoicesAsync(filter, orderBy, include, pageIndex, pageSize, transactionCurrency, skipRounding, ct);
            _log.LogInformation("Invoices response count={Count} in {Elapsed} ms", res?.Data?.Count ?? 0, sw.ElapsedMilliseconds);
            return res;
        }
        catch (Exception ex)
        {
            _log.LogError(ex, "Invoices failed in {Elapsed} ms", sw.ElapsedMilliseconds);
            throw;
        }
    }
}

Registration with Scrutor

using Scrutor;
using System.Net;

builder.Services.AddHttpClient("Invoices", c =>
{
    c.Timeout = Timeout.InfiniteTimeSpan;
    c.DefaultRequestHeaders.Accept.ParseAdd("application/json");
})
.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
{
    AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
    PooledConnectionLifetime = TimeSpan.FromMinutes(2),
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1),
    MaxConnectionsPerServer = 8
});

builder.Services.AddTransient<IInvoicesClient>(sp =>
{
    var http = sp.GetRequiredService<IHttpClientFactory>().CreateClient("Invoices");
    var cfg = sp.GetRequiredService<IConfiguration>();
    var baseUrl = cfg["Erp:BaseUrl"] ?? "";
    var tokenProvider = sp.GetRequiredService<ITokenProvider>();
    return new InvoicesClient(http, baseUrl, () => tokenProvider.GetToken());
});

builder.Services.Decorate<IInvoicesClient, LoggingInvoicesClientDecorator>();
builder.Services.Decorate<IInvoicesClient, RetryInvoicesClientDecorator>();

Native DI without Scrutor

builder.Services.AddHttpClient("Invoices", c =>
{
    c.Timeout = Timeout.InfiniteTimeSpan;
    c.DefaultRequestHeaders.Accept.ParseAdd("application/json");
});

builder.Services.AddTransient<IInvoicesClient>(sp =>
{
    var http = sp.GetRequiredService<IHttpClientFactory>().CreateClient("Invoices");
    var cfg = sp.GetRequiredService<IConfiguration>();
    var baseUrl = cfg["Erp:BaseUrl"] ?? "";
    var tokenProvider = sp.GetRequiredService<ITokenProvider>();

    IInvoicesClient svc = new InvoicesClient(http, baseUrl, () => tokenProvider.GetToken());
    svc = new LoggingInvoicesClientDecorator(svc, sp.GetRequiredService<ILogger<LoggingInvoicesClientDecorator>>());
    svc = new RetryInvoicesClientDecorator(svc);
    return svc;
});

DelegatingHandler for transport concerns

Use handlers for wire level logic, keep decorators for service level logic.

public sealed class LoggingHandler : DelegatingHandler
{
    private readonly ILogger<LoggingHandler> _log;
    public LoggingHandler(ILogger<LoggingHandler> log) => _log = log;

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
    {
        var sw = System.Diagnostics.Stopwatch.StartNew();
        var response = await base.SendAsync(request, ct);
        _log.LogInformation("{Method} {Uri} -> {Status} in {Elapsed} ms",
            request.Method, request.RequestUri, (int)response.StatusCode, sw.ElapsedMilliseconds);
        return response;
    }
}

builder.Services.AddTransient<LoggingHandler>();
builder.Services.AddHttpClient("Invoices", c => { /* defaults above */ })
    .AddHttpMessageHandler<LoggingHandler>();

Best practices checklist

One retry layer only.
Per call timeout with CancelAfter.
ResponseHeadersRead for large payloads.
Small page size for large ranges.
Keep HttpClient immutable after registration.
Put auth headers on the request message.

References

Polly, official docs and GitHub.
Scrutor, GitHub and NuGet.
Microsoft docs, HttpClientFactory with resilience patterns.
Source Code

Reliable Messaging in .NET: Domain Events and the Outbox Pattern with EF Core Interceptors

Mon, 13 Oct 2025 11:27:53 +0000

Introduction

Distributed systems are powerful — but they come with one big challenge: reliability.

What happens if your application updates a record in the database and then tries to publish a message to a message broker… but crashes in between?
You’ve just lost an event.

This problem is common in microservices, and it’s why the Outbox Pattern exists — a simple, elegant approach that guarantees message delivery without introducing distributed transactions or external coordinators.

In this article, we’ll implement a Domain Event + Outbox Pattern in .NET 9, using Entity Framework Core, SQLite, and an EF Core SaveChangesInterceptor.

⚙️ A Quick Look at Entity Framework Core

Entity Framework Core (EF Core) is Microsoft’s modern Object-Relational Mapper (ORM) for .NET.
It allows developers to work with a database using C# classes instead of raw SQL, automatically handling relationships, migrations, and change tracking.

When you call SaveChanges() or SaveChangesAsync(), EF Core:

Tracks your entity changes.
Generates SQL commands.
Executes them in a transaction.

This makes EF Core the perfect place to integrate the Outbox Pattern, since we can hook into its save pipeline and ensure domain events are written in the same transaction as the data itself.

What Are Interceptors?

In EF Core, interceptors are powerful hooks that allow you to intercept and extend the framework’s internal operations — such as saving, querying, or connecting to the database.

They work like middleware for EF Core:
you can observe, modify, or add logic before and after EF performs certain actions.

There are several types:

SaveChangesInterceptor
CommandInterceptor
ConnectionInterceptor
TransactionInterceptor

In this article, we’ll use SaveChangesInterceptor to detect domain events before EF saves, serialize them, and insert them into our Outbox table.

The Problem

In traditional architectures, your service might do something like this:

await _db.SaveChangesAsync();
await _bus.PublishAsync(new OrderPlacedEvent(orderId));

If your app crashes after saving but before publishing, your event never reaches other services — resulting in inconsistent state across systems.

We need a way to ensure atomicity: either both the data and the event are persisted, or neither are.

The Outbox Pattern (In a Nutshell)

The Outbox Pattern solves this by introducing a dedicated Outbox table inside your database.

When your aggregate raises a domain event, it’s captured and saved into the Outbox table within the same transaction as your entity.
A background worker (or a separate service) polls the Outbox table, publishes events, and marks them as processed.

This way, even if your app crashes, the events are safely stored and can be retried later.

The Architecture

┌──────────────────────────────┐
│         Application          │
│ ──────────────────────────── │
│  Order raises DomainEvent    │
│  → EF Interceptor writes     │
│    Outbox row                │
│  → Transaction commits       │
└──────────────┬───────────────┘
               │
               ▼
        Outbox Dispatcher
       ├─ Polls database
       ├─ Publishes messages
       └─ Marks them processed

This pattern elegantly blends Domain-Driven Design concepts with event-driven reliability.

Domain Events

Domain events capture something meaningful that happened in your domain model.
For example:

public sealed record OrderPlacedDomainEvent(Guid OrderId, decimal Total)
    : DomainEvent(DateTime.UtcNow);

And your aggregate raises them naturally:

public sealed class Order : IHasDomainEvents
{
    private readonly List<DomainEvent> _domainEvents = new();
    public Guid Id { get; private set; } = Guid.NewGuid();
    public decimal Total { get; private set; }

    public IReadOnlyCollection<DomainEvent> DomainEvents => _domainEvents;

    public Order(decimal total)
    {
        Total = total;
        AddEvent(new OrderPlacedDomainEvent(Id, Total));
    }

    private void AddEvent(DomainEvent @event) => _domainEvents.Add(@event);
    public void ClearDomainEvents() => _domainEvents.Clear();
}

⚙️ Capturing Events with an EF Core Interceptor

Instead of overriding SaveChangesAsync() directly inside AppDbContext, we can use a SaveChangesInterceptor — a clean, composable way to plug custom logic into EF’s lifecycle.


public sealed class OutboxSaveChangesInterceptor(IEventSerializer serializer) : SaveChangesInterceptor
{
    /// <summary>
    /// 
    /// </summary>
    /// <param name="eventData"></param>
    /// <param name="result"></param>
    /// <param name="cancellationToken"></param>
    /// <returns></returns>
    public override async ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        var context = eventData.Context;
        if (context is null) 
            return await base.SavingChangesAsync(eventData, result, cancellationToken);

        var aggregates = context.ChangeTracker
                    .Entries()
                    .Where(e => e.Entity is IHasDomainEvents hasEvents && hasEvents.DomainEvents.Count > 0)
                    .Select(e => (IHasDomainEvents)e.Entity)
                    .ToList();

        if (aggregates.Count == 0)
            return await base.SavingChangesAsync(eventData, result, cancellationToken);

        var outbox = context.Set<OutboxMessage>();

        foreach (var aggregate in aggregates)
        {
            foreach (var @event in aggregate.DomainEvents)
            {
                outbox.Add(new OutboxMessage
                {
                    OccurredOnUtc = @event.OccurredOnUtc,
                    Type = @event.GetType().AssemblyQualifiedName!,
                    Payload = serializer.Serialize(@event)
                });
            }
        }

        return await base.SavingChangesAsync(eventData, result, cancellationToken);
    }

}

Now every time you call SaveChangesAsync(), domain events are written to your OutboxMessages table automatically — in the same transaction.

The Outbox Dispatcher

Once the transaction is committed, a background worker can safely process these messages.


public sealed class OutboxDispatcher(IServiceProvider sp, 
    ILogger<OutboxDispatcher> logger) : BackgroundService
{
    private readonly IServiceProvider _sp = sp;
    private readonly ILogger<OutboxDispatcher> _logger = logger;
    private readonly TimeSpan _pollInterval = TimeSpan.FromSeconds(2);
    private const int BatchSize = 50;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation(" Outbox Dispatcher started...");

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                using var scope = _sp.CreateScope();
                var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

                var jsonSerializer = scope.ServiceProvider.GetRequiredService<IEventSerializer>();

                var pending = await db.OutboxMessages
                    .Where(x => x.ProcessedOnUtc == null)
                    .OrderBy(x => x.Id)
                    .Take(BatchSize)
                    .ToListAsync(stoppingToken);

                foreach (var msg in pending)
                {
                    try
                    {
                        var evt = jsonSerializer.Deserialize(msg.Payload, msg.Type);
                        await SimulatedBusPublish(evt, stoppingToken);
                        msg.ProcessedOnUtc = DateTime.UtcNow;
                        msg.Error = null;
                    }
                    catch (Exception ex)
                    {
                        msg.Error = ex.Message;
                        _logger.LogError(ex, "❌ Error dispatching OutboxMessage {Id}", msg.Id);
                    }
                }

                if (pending.Count > 0)
                    await db.SaveChangesAsync(stoppingToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Outbox dispatcher loop error");
            }

            await Task.Delay(_pollInterval, stoppingToken);
        }
    }

    private Task SimulatedBusPublish(DomainEvent evt, CancellationToken ct)
        => evt switch
        {
            OrderPlacedDomainEvent e => HandleOrderPlaced(e),
            _ => Task.CompletedTask
        };

    private Task HandleOrderPlaced(OrderPlacedDomainEvent e)
    {
        Console.WriteLine($"[BUS] ✅ OrderPlaced published => OrderId={e.OrderId}, Total={e.Total}");

        return Task.CompletedTask;
    }
}

Why Use an Interceptor?

Using an interceptor instead of overriding SaveChangesAsync() has several advantages:

Approach	Pros	Cons
Override SaveChangesAsync	Simple to start	Harder to reuse across contexts
Use Interceptor	Decoupled, reusable, testable	Slightly more setup

Interceptors follow the Open/Closed Principle — your DbContext remains focused on persistence, while cross-cutting logic (like event logging, auditing, or outbox handling) is easily attachable.

Benefits of the Outbox Pattern

✅ Transactional Safety — data + events saved atomically
✅ Guaranteed Delivery — retries handled by dispatcher
✅ DDD Alignment — aggregates raise domain events naturally
✅ Resilience — works even if message broker is offline
✅ Extensibility — can integrate with RabbitMQ, Kafka, or Azure Service Bus later

References

✨ Closing Thoughts

The Domain Events + Outbox Pattern is one of the most practical ways to achieve reliable, eventually consistent event-driven systems in .NET.

By combining Entity Framework Core, SaveChangesInterceptor, and a simple background dispatcher, you can ensure every event is persisted and delivered — even in the face of failure.

Small pattern. Big reliability.

Author

Spyros Ponaris
LinkedIn
Senior Software Engineer & .NET Enthusiast

MassTransit in ASP.NET Core: A Practical Guide to Event-Driven .NET

Mon, 29 Sep 2025 09:25:53 +0000

MassTransit in ASP.NET Core: A Practical Guide to Event-Driven .NET
Intro

Event-driven architectures help teams decouple services, scale independently, and handle failures gracefully. MassTransit is a mature, open-source library that makes message-based workflows in .NET straightforward. This guide shows a minimal but production-ready setup in ASP.NET Core with RabbitMQ.

1) Install packages

From your Web API project:

dotnet add package MassTransit
dotnet add package MassTransit.RabbitMQ

(For Azure Service Bus use MassTransit.Azure.ServiceBus.Core instead.)

2) Define a message contract

Contracts should be versionable and live in a shared project.

public interface SubmitOrder
{
    Guid OrderId { get; }
    string CustomerId { get; }
    DateTime Timestamp { get; }
}

3) Create a consumer

using MassTransit;

public sealed class SubmitOrderConsumer : IConsumer<SubmitOrder>
{
    public async Task Consume(ConsumeContext<SubmitOrder> context)
    {
        var msg = context.Message;
        // Your domain logic here (idempotent!)
        Console.WriteLine($"Received SubmitOrder {msg.OrderId} for {msg.CustomerId}");
        await Task.CompletedTask;
    }
}

4) Configure MassTransit in Program.cs (.NET 9 minimal hosting)

RabbitMQ example with retries and health checks.

using MassTransit;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMassTransit(cfg =>
{
    cfg.SetKebabCaseEndpointNameFormatter();

    cfg.AddConsumer<SubmitOrderConsumer>(c =>
    {
        // optional: configure consumer-level retry, etc.
    });

    cfg.UsingRabbitMq((context, bus) =>
    {
        bus.Host("rabbitmq", h =>
        {
            h.Username("guest");
            h.Password("guest");
        });

        bus.ReceiveEndpoint("submit-order-queue", e =>
        {
            e.ConfigureConsumeTopology = false; 
            e.ConfigureConsumer<SubmitOrderConsumer>(context);

            e.UseMessageRetry(r => r.Interval(3, TimeSpan.FromSeconds(5)));
            e.PrefetchCount = 16;
            e.ConcurrentMessageLimit = 8;
        });
    });
});

builder.Services.AddHealthChecks();

var app = builder.Build();
app.MapHealthChecks("/health");
app.MapGet("/", () => "OK");
app.Run();

Docker tip

If you run RabbitMQ locally via Docker:

docker run -d --hostname rabbit \
  -p 5672:5672 -p 15672:15672 \
  --name rabbitmq rabbitmq:3-management

UI is at http://localhost:15672 (guest/guest).

5) Publish a message (from a Controller or Service)

Inject IPublishEndpoint for pub/sub or ISendEndpointProvider for point-to-point.

using MassTransit;

public sealed class OrderAppService
{
    private readonly IPublishEndpoint _publish;
    public OrderAppService(IPublishEndpoint publish) => _publish = publish;

    public Task SubmitAsync(Guid orderId, string customerId)
        => _publish.Publish<SubmitOrder>(new
        {
            OrderId = orderId,
            CustomerId = customerId,
            Timestamp = DateTime.UtcNow
        });
}

Or via an endpoint (send to a specific queue):

public sealed class OrderSender
{
    private readonly ISendEndpointProvider _send;
    public OrderSender(ISendEndpointProvider send) => _send = send;

    public async Task SendAsync(Guid orderId, string customerId)
    {
        var endpoint = await _send.GetSendEndpoint(new Uri("queue:submit-order-queue"));
        await endpoint.Send<SubmitOrder>(new { OrderId = orderId, CustomerId = customerId, Timestamp = DateTime.UtcNow });
    }
}

6) Error handling, retries, and observability

Retries: use UseMessageRetry on endpoints or the bus. Prefer bounded retries with intervals or exponential backoff.

Poison messages: failed messages after retries land in _error queues automatically.

Health checks: expose /health and rely on container orchestration to restart unhealthy pods.

Idempotency: make consumers safe to reprocess (e.g., check a processed table or use dedup keys).

7) (Optional) Outbox & transactions

If you publish events within a DB transaction, consider an outbox pattern (MassTransit integrates with EFCore Outbox) to avoid dual-write issues and ensure at-least-once delivery without duplicates.

8) Azure Service Bus variant (quick sketch)

Swap the transport:

builder.Services.AddMassTransit(cfg =>
{
    cfg.AddConsumer<SubmitOrderConsumer>();

    cfg.UsingAzureServiceBus((context, bus) =>
    {
        bus.Host(builder.Configuration["ASB_CONNECTION"]!);

        bus.SubscriptionEndpoint<SubmitOrder>("submit-order-sub", e =>
        {
            e.ConfigureConsumer<SubmitOrderConsumer>(context);
            e.MaxConcurrentCalls = 8;
        });
    });
});

Conclusion

MassTransit keeps the happy path simple while giving you the tools for serious systems: retries, sagas, scheduling, observability, and transport flexibility. Start minimal, add policies as you learn your failure modes, and keep consumers idempotent.

Building a Pub/Sub System in .NET: MassTransit, Reactive Extensions, and BlockingCollection

Tue, 26 Aug 2025 13:57:29 +0000

Modern applications often need to broadcast events across multiple services.
Think of an order being placed in an e-commerce system. The order service publishes an event, and multiple subscribers react independently:

the billing service charges the customer,
the email service sends a receipt,
the analytics service tracks the order.

This is the essence of the Publish/Subscribe (Pub/Sub) pattern.

In this post we’ll explore what it is, why it matters, and three implementations in .NET:

MassTransit with RabbitMQ (for distributed systems)

Reactive Extensions (Rx) (for in-memory event streams)

BlockingCollection (for producer/consumer pipelines)

What is the Pub/Sub Pattern

The Pub/Sub pattern decouples senders from receivers.
The Publisher creates a message (e.g., OrderSubmitted) and sends it
to a broker or channel.
The Broker delivers that message to all interested Subscribers.

Each Subscriber receives a copy of the message and processes it independently.

Benefits

Decoupling — publishers do not know subscribers
Scalability — multiple subscribers can process in parallel
Flexibility — add or remove subscribers without changing the
publisher

Why it matters

This pattern has been around for decades in middleware like IBM MQ, JMS, RabbitMQ, and Kafka.
It is fundamental in:

Event-driven microservices

Real-time systems (chat apps, trading platforms)
Notification and alerting systems
Data pipelines and analytics

IoT device communication

At its core, Pub/Sub enables loose coupling and asynchronous communication.

⚙️ Hosted Services in ASP.NET Core

A hosted service is a background task that runs with your app host.
In .NET you typically inherit from BackgroundService and implement ExecuteAsync.

public class SampleWorker : BackgroundService
{
    private readonly ILogger<SampleWorker> _log;
    public SampleWorker(ILogger<SampleWorker> log) => _log = log;

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        _log.LogInformation("Worker started");
        while (!ct.IsCancellationRequested)
        {
            // do work here
            await Task.Delay(TimeSpan.FromSeconds(5), ct);
        }
        _log.LogInformation("Worker stopping");
    }
}

// Register in Program.cs
builder.Services.AddHostedService<SampleWorker>();

In the MassTransit demo below, a PublisherService is implemented as a hosted service to periodically publish messages.

1️⃣ Pub/Sub with MassTransit and RabbitMQ

appsettings.json
{
  "RabbitMq": { "Host": "localhost", "Username": "guest", "Password": "guest" },
  "PublishIntervalSeconds": 5
}

OrderSubmitted.cs

namespace MassTransitDemo;

public record OrderSubmitted(Guid OrderId, string CustomerEmail, decimal Total);

OrderSubmittedConsumer.cs

using MassTransit;
using Microsoft.Extensions.Logging;

namespace MassTransitDemo;

public class OrderSubmittedConsumer(ILogger<OrderSubmittedConsumer> logger) : IConsumer<OrderSubmitted>
{
    public Task Consume(ConsumeContext<OrderSubmitted> context)
    {
        var m = context.Message;
        logger.LogInformation("Consumed OrderSubmitted, OrderId {OrderId}, Email {Email}, Total {Total}",
            m.OrderId, m.CustomerEmail, m.Total);
        return Task.CompletedTask;
    }
}

PublisherService.cs

using MassTransit;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;

namespace MassTransitDemo;

public class PublisherOptions
{
    public int PublishIntervalSeconds { get; set; } = 5;
}

public class PublisherService(
    ILogger<PublisherService> logger,
    IPublishEndpoint publishEndpoint,
    IOptions<PublisherOptions> options) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var delay = TimeSpan.FromSeconds(options.Value.PublishIntervalSeconds);
        logger.LogInformation("Publisher started, interval {Seconds}s", options.Value.PublishIntervalSeconds);

        while (!stoppingToken.IsCancellationRequested)
        {
            var msg = new OrderSubmitted(Guid.NewGuid(), "*Emails are not allowed*", Random.Shared.Next(50, 300));
            await publishEndpoint.Publish(msg, stoppingToken);
            logger.LogInformation("Published OrderSubmitted, OrderId {OrderId}", msg.OrderId);
            await Task.Delay(delay, stoppingToken);
        }

        logger.LogInformation("Publisher stopping");
    }
}

Program.cs

    using MassTransit;
    using MassTransitDemo;
    using Microsoft.Extensions.Configuration;
    using Microsoft.Extensions.Hosting;
    using Microsoft.Extensions.Logging;
    
    var builder = Host.CreateApplicationBuilder(args);
    
    builder.Configuration.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true);
    builder.Services.Configure<PublisherOptions>(builder.Configuration);
    
    builder.Services.AddMassTransit(mt =>
    {
        mt.AddConsumer<OrderSubmittedConsumer>();
    
        mt.UsingRabbitMq((ctx, cfg) =>
        {
            var section = builder.Configuration.GetSection("RabbitMq");
            cfg.Host(section["Host"], h =>
            {
                h.Username(section["Username"]);
                h.Password(section["Password"]);
            });
    
            cfg.ReceiveEndpoint("masstransitdemo-order-submitted", e =>
            {
                e.ConfigureConsumer<OrderSubmittedConsumer>(ctx);
            });
    
            cfg.UseMessageRetry(r => r.Interval(3, TimeSpan.FromSeconds(5)));
            cfg.UseInMemoryOutbox();
        });
    });
    
    builder.Services.AddHostedService<PublisherService>();
    
    builder.Logging.ClearProviders();
    builder.Logging.AddSimpleConsole(o =>
    {
        o.SingleLine = true;
        o.TimestampFormat = "HH:mm:ss ";
    });
    
    await builder.Build().RunAsync();

Run RabbitMQ

docker run -it --rm -p 5672:5672 -p 15672:15672 rabbitmq:3-management
# UI at http://localhost:15672  user guest  pass guest

MassTransit is a distributed application framework for message brokers like RabbitMQ and Azure Service Bus. It takes care of serialization, consumer lifecycle, retries, and endpoint setup.

2️⃣ Pub/Sub with Reactive Extensions (Rx)

Reactive Extensions (Rx)
is a library for composing asynchronous and event based programs with observable sequences.

Uses IObservable (event source) and IObserver (subscriber)

Provides LINQ-style operators (Where, Select, Buffer) for event streams

Perfect for in-memory event pipelines and UI scenarios

⚠️ Limitation: Rx is in-memory only. Events vanish when the app stops.

Program.cs

using System;
using System.Reactive.Linq;
using System.Reactive.Subjects;

public record OrderSubmitted(Guid OrderId, string CustomerEmail, decimal Total);

class Program
{
    static void Main()
    {
        var bus = new Subject<OrderSubmitted>();

        // Subscriber A
        var subA = bus.Subscribe(order =>
            Console.WriteLine($"[Email] Send receipt to {order.CustomerEmail}"));

        // Subscriber B with filter and transform
        var subB = bus
            .Where(o => o.Total >= 100)
            .Select(o => new { o.OrderId, Vat = o.Total * 0.24m })
            .Subscribe(x =>
                Console.WriteLine($"[Analytics] Order {x.OrderId}, VAT {x.Vat:F2}"));

        // Publish a few messages
        bus.OnNext(new OrderSubmitted(Guid.NewGuid(), "*Emails are not allowed*", 79.90m));
        bus.OnNext(new OrderSubmitted(Guid.NewGuid(), "*Emails are not allowed*", 149.00m));
        bus.OnNext(new OrderSubmitted(Guid.NewGuid(), "*Emails are not allowed*", 220.00m));

        bus.OnCompleted();
        subA.Dispose();
        subB.Dispose();
    }
}

3️⃣ Pub/Sub with BlockingCollection

BlockingCollection is a thread safe producer and consumer collection in .NET.

Supports blocking (consumers wait until data is available)

Supports bounding (limit capacity to avoid flooding)

Useful for background workers, pipelines, or batch processors

Program.cs

using System.Collections.Concurrent;

public record OrderSubmitted(Guid OrderId, string CustomerEmail, decimal Total);

class Program
{
    static async Task Main()
    {
        using var queue = new BlockingCollection<OrderSubmitted>(boundedCapacity: 100);

        // Subscriber A
        var emailTask = Task.Run(() =>
        {
            foreach (var order in queue.GetConsumingEnumerable())
                Console.WriteLine($"[Email] Send receipt to {order.CustomerEmail}");
        });

        // Subscriber B
        var analyticsTask = Task.Run(() =>
        {
            foreach (var order in queue.GetConsumingEnumerable())
                Console.WriteLine($"[Analytics] Track order {order.OrderId}, total {order.Total}");
        });

        // Publisher
        foreach (var price in new[] { 49.50m, 129.00m, 250.00m, 15.00m })
        {
            queue.Add(new OrderSubmitted(Guid.NewGuid(), $"user{price}@example.com", price));
        }

        queue.CompleteAdding();
        await Task.WhenAll(emailTask, analyticsTask);
    }
}

⚠️ Limitation: Only works inside a single process. No distribution.

References

MassTransit Documentation

MassTransit GitHub

RabbitMQ Tutorials

Microsoft Docs: Worker Services

Microsoft Docs: Publisher-Subscriber Pattern

System.Reactive GitHub

BlockingCollection Overview

✅ With these three approaches, you now have the full spectrum of Pub/Sub in .NET:

Lightweight in-memory streams with Rx and BlockingCollection

Robust distributed messaging with MassTransit and RabbitMQ

The Pub/Sub pattern has lasted decades because it makes systems more modular, more scalable, and more resilient to change.

Saga Pattern — an Introduction

Sun, 17 Aug 2025 07:58:36 +0000

In the world of microservices and distributed systems, managing data consistency across multiple services presents unique challenges. Traditional database transactions with their ACID guarantees work beautifully within a single database, but they fall short when your business logic spans multiple services, each with its own database. Enter the Saga pattern—a powerful approach to handling distributed transactions that has become essential in modern microservices architectures.

You can read the blog or read the research paper. I recommend the latter.

Sample projects:

Online Store Saga Choreography Example
Hotel Booking Saga Orchestration Example

What is the Saga Pattern?

The Saga pattern, first introduced by Hector Garcia-Molina and Kenneth Salem in their 1987 research paper, provides a way to manage long-running transactions that span multiple services in a distributed system. Rather than treating the entire business process as a single atomic transaction, a saga breaks it down into a series of smaller, independent transactions that can be coordinated across services.

Think of booking a vacation package that involves reserving a flight, hotel, and rental car. In a monolithic system, you might wrap all these operations in a single database transaction. With microservices, each service (Flight Service, Hotel Service, Car Rental Service) manages its own data independently. The Saga pattern allows you to coordinate these separate operations while maintaining the ability to handle failures gracefully.

At its core, a saga consists of a sequence of transactions T₁, T₂, ..., Tₙ, where each transaction has a corresponding compensating transaction C₁, C₂, ..., Cₙ. If any transaction fails, the saga executes the compensating transactions in reverse order to undo the work already completed, ensuring the system remains in a consistent state.

Problems it Solves and Consistency Trade-offs

The Saga pattern addresses several critical challenges in distributed systems:

Distributed Data Management: In microservices architectures, services are designed to be autonomous, each owning its data. Traditional two-phase commit protocols can create tight coupling and availability issues across services. Sagas enable coordination without sacrificing service autonomy.

Long-Running Processes: Business processes often involve multiple steps that may take minutes, hours, or even days to complete. Holding database locks for such extended periods is impractical and can severely impact system performance. Sagas allow these processes to progress incrementally without blocking resources.

Failure Handling: In distributed systems, failures are inevitable. Network partitions, service outages, and timeouts are part of the reality. Sagas provide a structured approach to handle these failures through compensation, rather than simply rolling back and starting over.

Eventual Consistency Trade-off: The Saga pattern embraces eventual consistency over immediate consistency. This means that at any given moment, the system might be in an intermediate state, but it will eventually reach a consistent state once the saga completes or compensates. This trade-off is acceptable—and often preferable—in many business scenarios where absolute consistency isn't critical, but availability and resilience are paramount.

Unlike strict ACID transactions that provide immediate consistency but can be brittle in distributed environments, sagas offer a pragmatic approach that acknowledges the realities of distributed systems. The business logic determines whether eventual consistency is acceptable, and in most real-world scenarios involving multiple services, it is.

Types of Saga Patterns

The Saga pattern can be implemented using two primary approaches, each with distinct characteristics and use cases.

Choreography-Based Sagas

In choreography-based sagas, services coordinate themselves through events without a central coordinator. Each service listens for events, performs its part of the transaction, and publishes events for other services to consume.

How it works: When a user places an order, the Order Service creates the order and publishes an "OrderCreated" event. The Payment Service listens for this event, processes payment, and publishes a "PaymentProcessed" event. The Inventory Service then reserves items and publishes an "ItemsReserved" event, and so on.

Pros:

Decentralized control promotes service autonomy
No single point of failure from a coordinator perspective
Natural fit for event-driven architectures
Services remain loosely coupled

Cons:

Complex to track and debug the overall flow
Difficult to understand the complete business process from code
Challenging to handle circular dependencies
Error handling can become distributed and complex

When to use: Choose choreography when you have a relatively simple saga with clear, linear flow and when you want to maximize service independence. It works well for scenarios where the business process is stable and unlikely to change frequently.

For a practical example, check out this choreography-based online store implementation that demonstrates how services coordinate through events to handle order processing.

Orchestration-Based Sagas

In orchestration-based sagas, a central orchestrator (saga manager) controls the execution flow, explicitly calling services and managing the overall transaction state.

How it works: A Saga Orchestrator receives a request to start a saga, then sequentially calls each service based on predefined logic. It maintains the saga's state and handles both success and failure scenarios by invoking appropriate compensating actions.

Pros:

Clear, centralized control flow that's easy to understand and debug
Explicit state management makes monitoring and troubleshooting straightforward
Easier to implement complex routing logic and conditional flows
Better support for timeout handling and retry mechanisms

Cons:

Central orchestrator can become a bottleneck or single point of failure
Orchestrator needs to know about all participating services
Can lead to more coupled architecture
Additional infrastructure component to maintain

When to use: Opt for orchestration when you have complex business flows with conditional logic, when you need clear visibility into the saga state, or when you're dealing with frequently changing business requirements that benefit from centralized control.

The hotel booking saga orchestration project provides a comprehensive example of how to implement orchestration-based sagas with proper state management and compensation handling.

Comparisons with Other Patterns

Understanding how the Saga pattern compares to other consistency approaches helps clarify when to use each.

Saga vs. Two-Phase Commit (2PC): Two-Phase Commit provides strong consistency through a prepare-commit protocol but comes with significant drawbacks in distributed systems. It's blocking (services must wait for coordinator decisions), has poor fault tolerance (coordinator failure blocks everything), and doesn't scale well across networks with high latency. Sagas, in contrast, are non-blocking, more fault-tolerant, and better suited for loosely coupled microservices, though they provide only eventual consistency.

Saga vs. Event Sourcing: While both patterns work well in event-driven systems, they serve different purposes. Event sourcing focuses on storing state changes as events and rebuilding state from these events. Sagas focus on coordinating multi-service transactions. They complement each other well—you can implement sagas in an event-sourced system.

Saga vs. Distributed Transactions: Traditional distributed transactions aim for immediate consistency across all resources but are complex to implement correctly and perform poorly at scale. Sagas acknowledge that immediate consistency isn't always necessary and provide a simpler, more resilient alternative for most business scenarios.

The practical advantage of sagas lies in their alignment with microservices principles: they maintain service autonomy, provide better availability characteristics, and offer a more pragmatic approach to consistency in distributed systems.

Implementation in Practice with Spring Boot

Spring Boot provides excellent support for implementing saga patterns through various approaches. The most common implementation leverages Spring's event handling capabilities and message queues.

For choreography-based sagas, developers typically use:

Spring Events for intra-service communication
Message brokers (RabbitMQ, Apache Kafka) for inter-service events
Spring Boot Actuator for monitoring saga progress
Custom event handlers that implement both forward and compensating actions

For orchestration-based sagas, the implementation often includes:

A dedicated Saga Orchestrator service built with Spring Boot
Spring State Machine for managing saga states and transitions
RestTemplate or WebClient for service-to-service communication
Scheduled tasks for handling timeouts and retries
Database persistence for saga state management

A typical Spring Boot saga implementation involves creating:

Saga Events: Domain events that represent saga steps
Event Handlers: Methods annotated with @EventListener that process saga events
Compensation Logic: Corresponding handlers for rollback operations
State Management: Tracking saga progress and current state
Error Handling: Timeout management and retry mechanisms

The referenced sample projects demonstrate these concepts in action, showing how to structure your code, handle failures, and implement proper monitoring for production-ready saga implementations.

Common Challenges and Testing Considerations

Implementing sagas in production environments presents several challenges that require careful consideration and planning.

Timeout Management: Services in a saga may become temporarily unavailable or respond slowly. Implementing appropriate timeout strategies is crucial—too short, and you'll have false failures; too long, and failed sagas will tie up resources. Design your timeouts based on realistic service response times and implement exponential backoff for retries.

Compensating Transaction Complexity: Not all operations can be easily compensated. Sending an email notification, for example, can't be "unsent." Design your sagas to minimize non-compensatable actions, or implement semantic compensation (like sending an apology email). Sometimes, the compensation is more complex than the original transaction.

Idempotency: Saga steps may be retried due to network issues or timeouts, so all operations must be idempotent. This means that executing the same operation multiple times should have the same effect as executing it once. Implement proper idempotency keys and state checking to handle duplicate requests gracefully.

Partial Failure Scenarios: The most challenging aspect of sagas is handling scenarios where some steps succeed while others fail, potentially leaving the system in an intermediate state. Design your business processes to be resilient to these intermediate states, and ensure your UI and downstream systems can handle eventual consistency appropriately.

Testing Saga Flows: Testing distributed sagas requires sophisticated approaches:

Unit Testing: Test individual saga steps and their compensations in isolation
Integration Testing: Use tools like TestContainers to test saga flows with real message brokers and databases
Chaos Testing: Deliberately introduce failures at different points to verify compensation logic
End-to-End Testing: Test complete saga flows in staging environments that mirror production

Monitoring and Observability: Implement comprehensive logging and monitoring for saga execution. Track saga instances, their current state, execution times, and failure rates. Tools like distributed tracing can help you follow saga execution across multiple services.

Design Recommendations:

Keep saga steps as small and focused as possible
Design for failure from the beginning—assume every step can fail
Implement proper dead letter queues for handling poison messages
Use correlation IDs to track saga instances across services
Consider implementing saga timeouts at the business process level
Plan for manual intervention in complex failure scenarios

The key to successful saga implementation is thorough testing and gradual rollout. Start with simple, linear sagas before moving to complex orchestration scenarios, and always have monitoring and alerting in place to catch issues early.

Conclusion

The Saga pattern represents a pragmatic approach to managing distributed transactions in microservices architectures. By embracing eventual consistency and providing structured failure handling through compensation, sagas enable developers to build resilient, scalable systems that can handle the complexities of distributed environments.

Whether you choose choreography for simple, event-driven flows or orchestration for complex business processes, the key is to understand your specific requirements and constraints. The pattern's flexibility allows for various implementation approaches, from simple Spring Boot applications to sophisticated orchestration engines.

As distributed systems continue to evolve, the Saga pattern remains a fundamental tool for managing complexity while maintaining the benefits of microservices architecture. Success with sagas comes from careful design, thorough testing, and a clear understanding of the consistency trade-offs that make modern distributed systems both scalable and resilient.

References

Garcia-Molina, H., & Salem, K. (1987). Sagas. ACM SIGMOD Record.
Microservices Patterns: Saga Pattern
Online Store Saga Choreography Example
Hotel Booking Saga Orchestration Example

Supercharging EF Core Specifications with EF.CompileQuery

Tue, 05 Aug 2025 07:56:23 +0000

Introduction

When you’re using EF Core in production, query compilation can quietly become a performance bottleneck — especially if the same query is executed thousands of times.

Normally, EF Core parses your LINQ, generates SQL, and prepares the execution plan every time.
With EF.CompileQuery, EF Core does that work once, caching the query plan for all future executions.

The catch?

If you’re using the Specification pattern for clean, reusable queries, your repository method probably applies a spec dynamically to DbSet — which makes EF.CompileQuery less obvious to use.

In this article, we’ll solve that and show you how to bake compiled queries into your specification-driven repository.

Quick Recap: Specification Pattern

The Specification pattern encapsulates query logic into reusable, composable units.

Example spec for active customers:

public class ActiveCustomersSpec : Specification<Customer>
{
    public ActiveCustomersSpec()
    {
        Query.Where(c => c.IsActive)
             .OrderBy(c => c.Name)
             .Include(c => c.Orders);
    }
}

Your repository then applies the spec:

public async Task<IReadOnlyList<T>> ListAsync(ISpecification<T> spec)
{
    var evaluator = new SpecificationEvaluator();
    var query = evaluator.GetQuery(_db.Set<T>().AsQueryable(), spec);
    return await query.ToListAsync();
}

The Problem

EF.CompileQuery needs a strongly-typed lambda starting from your DbContext:

private static readonly Func<AppDbContext, bool, IEnumerable<Customer>> _activeCustomers =
    EF.CompileQuery((AppDbContext db, bool isActive) =>
        db.Customers.Where(c => c.IsActive == isActive));

But with the Specification pattern, you usually pass in a spec, not a lambda on DbContext.
You don’t want every caller to remember how to invoke the compiled query.
We need a way to integrate compiled queries into the repository itself.

The Solution: Encapsulate Compiled Queries in the Repository

4.1 Create the compiled query

public static class CompiledQueries
{
    public static readonly Func<AppDbContext, bool, IEnumerable<Customer>> ActiveCustomers =
        EF.CompileQuery((AppDbContext db, bool isActive) =>
            db.Customers
              .Where(c => c.IsActive == isActive)
              .OrderBy(c => c.Name)
              .Include(c => c.Orders));
}

4.2 Update the repository

public class EfRepository<T> where T : class
{
    private readonly AppDbContext _db;
    public EfRepository(AppDbContext db) => _db = db;

    public async Task<IReadOnlyList<T>> ListAsync(ISpecification<T> spec)
    {
        // Detect known spec → use compiled query
        if (typeof(T) == typeof(Customer) && spec is ActiveCustomersSpec)
        {
            var result = CompiledQueries.ActiveCustomers(_db, true).ToList();
            return (IReadOnlyList<T>)result;
        }

        // Fallback: normal spec evaluation
        var evaluator = new SpecificationEvaluator();
        var query = evaluator.GetQuery(_db.Set<T>().AsQueryable(), spec);
        return await query.ToListAsync();
    }
}

4.3 Usage stays clean

var repo = new EfRepository<Customer>(db);
var customers = await repo.ListAsync(new ActiveCustomersSpec());

The caller doesn’t know (or care) if the query was compiled
but hot-path specs now run ~3x faster.

Ready-to-Use Libraries
Instead of writing your own Specification pattern, you can use:

Ardalis.Specification

Well-maintained, feature-rich.
Supports includes, projections, ordering, pagination.

NSpecifications

DDD-focused, composable specifications.
Great for domain-driven designs.

Both integrate nicely with EF Core and can work with this
compiled-query approach.

Best Practices
Use compiled queries for hot paths — they have a cost to set up but shine when reused often.

Avoid over-compiling — not every query benefits from precompilation.

Keep specs small and focused — huge includes and joins can still dominate runtime.

Combine with async wisely — EF.CompileQuery is sync; use EF.CompileAsyncQuery for async enumeration.

Conclusion

You don’t have to choose between clean architecture (Specification pattern) and speed.
By encapsulating EF.CompileQuery inside your repository for frequently-used specs,
you can keep your calling code clean while still getting huge performance wins.

Source Code :
https://github.com/stevsharp/EfCompileSpecDemo

Understanding MediatR Assembly Registration in .NET

Fri, 04 Jul 2025 09:33:30 +0000

Introduction
When building clean, modular applications in .NET using the MediatR library, developers often encounter this configuration line:

builder.Services.AddMediatR(typeof(Application.Assembly.AssemblyReference).Assembly);

For newcomers to MediatR, this syntax can appear cryptic. However, it serves a critical role in enabling the framework to function correctly. This article provides a comprehensive explanation of assembly registration in MediatR, covering its purpose, implementation, and best practices.
What Is MediatR?
MediatR is a lightweight, in-process messaging library for .NET that facilitates decoupling between request senders (such as controllers) and request handlers (such as services or command processors). It implements several important patterns:

**- Command Query Responsibility Segregation (CQRS)

Mediator pattern
Pipeline behaviors for cross-cutting concerns
The library works by defining requests (commands or queries) and their corresponding handlers, then routing requests through a mediator to the appropriate handler.
Understanding Assembly Registration
The Core Concept**
MediatR requires explicit assembly registration to discover and register your handlers in the dependency injection container. The framework cannot automatically scan every assembly in your application—you must specify which assemblies contain your MediatR handlers.

builder.Services.AddMediatR(typeof(SomeTypeInTargetAssembly).Assembly);
Assembly Location: typeof(SomeTypeInTargetAssembly).Assembly provides MediatR with access to the target assembly
Handler Discovery: MediatR uses reflection to scan the assembly for types implementing MediatR interfaces (IRequestHandler<,>, INotificationHandler<>, etc.)
Service Registration: Discovered handlers are automatically registered with the dependency injection container
Why Assembly Registration Is Required
MediatR operates through dependency injection and reflection, but it cannot magically locate your handlers across all loaded assemblies. Without proper assembly registration, you will encounter this runtime exception:

System.InvalidOperationException: No service for type 'IRequestHandler<YourCommand, YourResponse>' has been registered.
This error occurs because the dependency injection container cannot resolve the required handler service.
Implementation Best Practices
Using a Marker Class
The recommended approach is to create a dedicated marker class within your handler assembly:
Application/Assembly/AssemblyReference.cs

namespace Application.Assembly
{
```
 public class AssemblyReference 
 {
     // This class serves as an assembly marker for MediatR registration
 }
```
}

Program.cs (or Startup.cs)

builder.Services.AddMediatR(typeof(Application.Assembly.AssemblyReference).Assembly);

This approach offers several advantages:

Maintainability: Creates a stable reference point that won't change
Clarity: Makes the registration intent explicit
Decoupling: Avoids tight coupling to specific handler classes
Here's a typical Clean Architecture project structure:

Solution/
├── Api/ # Presentation layer
│ └── Program.cs # Application entry point
├── Application/ # Application layer
│ ├── Features/
│ │ ├── Authentication/
│ │ │ ├── LoginCommand.cs
│ │ │ └── LoginCommandHandler.cs
│ │ └── Users/
│ │ ├── GetUserQuery.cs
│ │ └── GetUserQueryHandler.cs
│ └── Assembly/
│ └── AssemblyReference.cs # Marker class
├── Domain/ # Domain layer
└── Infrastructure/ # Infrastructure layer

An Example
Defining a Command and Handler
LoginCommand.cs

    using MediatR;

namespace Application.Features.Authentication;

public class LoginCommand : IRequest<LoginResponse>
{
    public string Username { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
}

public class LoginResponse
{
    public bool IsSuccess { get; set; }
    public string Token { get; set; } = string.Empty;
    public string Message { get; set; } = string.Empty;
}

Using the Handler in a Controller

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly IMediator _mediator;

    public AuthController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpPost("login")]
    public async Task<ActionResult<LoginResponse>> Login([FromBody] LoginCommand command)
    {
        var response = await _mediator.Send(command);
        return Ok(response);
    }
}

Conclusion
Proper assembly registration is fundamental to MediatR's operation in .NET applications. By understanding how AddMediatR(typeof(...).Assembly) works and following established best practices, you can build maintainable, decoupled applications that leverage MediatR's powerful messaging capabilities.

Key Takeaways

Always register the assembly containing your MediatR handlers
Use marker classes for clean, maintainable assembly references
Ensure proper project references between your API and Application layers
Consider pipeline behaviors for implementing cross-cutting concerns

Next Steps
To further enhance your MediatR implementation:

Implement validation using FluentValidation with MediatR pipeline behaviors
Add logging and monitoring through custom pipeline behaviors
Explore notifications using INotification and INotificationHandler<>
Consider performance optimization with caching behaviors
Implement error handling strategies using pipeline behaviors

Is the Repository Pattern Dead?

Wed, 04 Jun 2025 07:25:26 +0000

Is the Repository Pattern Dead?

Introduction

The repository pattern has been a cornerstone of enterprise .NET architecture for years. It promised clean separation between business logic and data access, testability, and maintainability. But with modern ORMs like Entity Framework Core, and new design trends like CQRS, many developers are asking:

Is the repository pattern still relevant, or is it finally dead?

What Is the Repository Pattern?

The Repository pattern is a well-known design pattern that aims to separate the logic that retrieves data from the business logic that acts on the data.

"A Repository mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects."— Martin Fowler, Patterns of Enterprise Application Architecture

In practice, this means using a class that acts like an in-memory collection of domain objects — hiding whether the data comes from SQL, a web service, or somewhere else:

public interface ICustomerRepository
{
    Task<Customer> GetByIdAsync(Guid id);
    Task AddAsync(Customer customer);
}

Originally, this was valuable when ORMs weren’t mature and data access logic was verbose and database-specific.

Why People Say It’s Dead

✅ EF Core Is Already a Repository

DbContext and DbSet provide the core functionality repositories offer: querying, adding, removing, and tracking entities.

❌ Boilerplate Hell

Most custom repositories end up duplicating what EF already provides:

public Task<Customer> GetByIdAsync(Guid id) => _context.Customers.FindAsync(id);

...which is not value-added abstraction.

Over-Abstraction Hurts

You lose direct access to EF Core's powerful features like:

.Include() for eager loading
.AsNoTracking() for read-only queries
Raw SQL with .FromSqlRaw()

However, patterns like Ardalis.Specification allow you to retain advanced EF Core features such as eager loading via .Include(), while still keeping your repository clean and decoupled. Specifications can express query logic clearly, including filters, includes, and sorting.

“Switching databases” is not a strong reason anymore

A common argument for using repositories is to make it easier to swap out databases (e.g., from SQL Server to PostgreSQL). But with Entity Framework Core, your application already depends on an abstraction — EF itself. Changing providers typically involves minimal changes to the DbContext configuration and nothing in your business logic. Adding another repository layer just to enable “swap-ability” is usually over-engineering.

When the Repository Pattern Still Makes Sense

Despite the criticism, there are valid scenarios where repositories shine:

Domain-Driven Design (DDD) with rich aggregates and business rules

Abstracting external data sources (SQL + API + NoSQL)

Clear boundaries in microservices

NuGet/Repo Suggestions:

Ardalis.Specification: A clean implementation of the Specification Pattern that works great with EF Core.

Ardalis.CleanArchitecture: A full solution template with proper use of repositories and separation of concerns.

Refit: For when your "repository" is actually calling an external API.

EFCore.BulkExtensions: If you do stay close to DbContext, this helps with batch operations and performance.

Modern Alternatives

Rather than force-fitting repositories, modern .NET developers are adopting:

CQRS + MediatR: Commands and queries are separated cleanly.

MediatR: Lightweight in-process messaging.

Query Object Pattern: Encapsulates complex queries into reusable classes.

Minimal APIs + DbContext injection (in .NET 6+): Simple, fast, and testable.

Pragmatic Verdict

So, is the repository pattern dead? Not quite.

It's just no longer mandatory.

Use it when it adds value — such as enforcing boundaries, abstracting external sources, or aligning with your team's architecture. But don’t blindly wrap EF Core unless there’s a real reason.

Conclusion

The repository pattern isn’t dead — it’s evolved. In modern .NET, we have better tools, smarter defaults, and community-tested patterns like Ardalis.Specification that give you structure only when you need it.

Choose the right tool for your context. That’s real architecture.

References

Martin Fowler – Repository Pattern

Steve Smith – Ardalis.Specification GitHub

Steve Smith – Clean Architecture Template

Jeremy Bogard – MediatR GitHub

EFCore Bulk Extensions – GitHub Repository

Refit – GitHub Repository

Clean React code pattern with the useImperativeHandle hook

Tue, 20 May 2025 07:26:26 +0000

In the quest for a cleaner and more concise codebase that adheres to the DRY principle, one React hook that stands out is useImperativeHandle hook.

React’s declarative nature encourages developers to build components that rely on props and state to manage behavior and rendering. However, in some cases imperative programming can simplify complex state management, especially when a child component interacts with multiple parents.

The `useImperativeHandle()` hook Pattern

In React, as the app size grows, it also starts to grow in complexity and it becomes expedient for devs to utilize advanced patterns to reach their goals, as simpler patterns can no longer adequately provide the clean solutions we require.

Managing state in child components typically involves lifting state up to parent components. However, when a child is shared among multiple parents, duplicating state can lead to repetitive code and potential inconsistencies. To address this, you can centralize state management within the child itself, using the useImperativeHandle hook to expose imperative methods for modifying its state. This approach not only prevents redundancy but also promotes a more maintainable architecture.

The Pattern in Action

Below is an example that demonstrates how to leverage useImperativeHandle for better state management. In this pattern, a child component exposes methods like focus and clear through its ref, allowing parent components to control its behavior without relying solely on props or state hooks.

Example

import React, { useRef, forwardRef, useImperativeHandle } from 'react';

const ChildInput = forwardRef((props, ref) => {
  const inputRef = useRef();

  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current?.focus(),
    clear: () => {
      inputRef.current.value = '';
    },
  }));

  return <input ref={inputRef} {...props} />;
});

export default function ParentComponent() {
  const inputRef = useRef();

  return (
    <div className="p-4 space-y-4">
      <ChildInput ref={inputRef} placeholder="Type something..." />
      <div className="space-x-2">
        <button
          onClick={() => inputRef.current.focus()}
          className="px-3 py-1 bg-blue-500 text-white rounded"
        >
          Focus Input
        </button>
        <button
          onClick={() => inputRef.current.clear()}
          className="px-3 py-1 bg-red-500 text-white rounded"
        >
          Clear Input
        </button>
      </div>
    </div>
  );
}

React 19 further refines this pattern by eliminating the need for forwardRef. The example below illustrates the same behavior with a cleaner syntax.

React 19 Example

import React, { useImperativeHandle, useRef } from 'react';

function ChildInput(props, ref) {
  const inputRef = useRef();

  // Expose imperative methods to the parent via the ref.
  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current?.focus(),
    clear: () => {
      if (inputRef.current) {
        inputRef.current.value = '';
      }
    },
  }));

  return <input ref={inputRef} {...props} />;
}

function ParentComponent() {
  const inputRef = useRef();

  return (
    <div className="p-4 space-y-4">
      <ChildInput ref={inputRef} placeholder="Type something..." />
      <div className="space-x-2">
        <button
          onClick={() => inputRef.current.focus()}
          className="px-3 py-1 bg-blue-500 text-white rounded"
        >
          Focus Input
        </button>
        <button
          onClick={() => inputRef.current.clear()}
          className="px-3 py-1 bg-red-500 text-white rounded"
        >
          Clear Input
        </button>
      </div>
    </div>
  );
}

export default ParentComponent;

Conclusion

This approach demonstrates how useImperativeHandle can simplify state management in complex React applications. While the example above provides a practical solution, I would encourage you to learn more about useImperativeHandle, Declarative and Imperative programming,

I have provided starter prompts you can feed into an LLM to get detailed explanations for each of the concepts, and to fully appreciate the trade-offs and best practices behind this each of them.

Explain declarative and imperative programming?

Explain declarative and imperative programming in the context of React

Explain the useImperativeHandle hook, and give examples of when to utilize this hook versus using just props and state?

The Proxy Pattern: A Software Developer’s Essential Tool

Fri, 25 Apr 2025 15:31:01 +0000

The Proxy Pattern is a structural design pattern that provides a surrogate or placeholder for another object to control access to it. It's like having a representative that acts on behalf of another object.

The Proxy Pattern allows you to:

• Provide a substitute or placeholder for another object

• Control access to the original object

• Perform operations before or after requests reach the original object

When to Use the Proxy Pattern

Lazy initialization is needed: When creating objects is expensive and you want to delay creation until absolutely necessary
Access control is required: When you need to restrict access to certain operations or resources based on permissions
Resource management is important: When working with limited resources that need controlled allocation
Added functionality is needed before/after access: When you want to perform operations before or after accessing the real object (like logging or caching)

The key indicator is when you need to control access to an object without changing its interface.

Structure of the Proxy Pattern
The pattern consists of these key components:
• Subject: An interface that defines the common operations for both the RealSubject and Proxy

• RealSubject: The actual object that the proxy represents

• Proxy: Maintains a reference to the RealSubject and controls access to it

• Client: Interacts with the Subject interface

Types of Proxies

1. Virtual Proxy
• Creates expensive objects on demand (lazy initialization)
• Example: Loading large images in a document only when they need to be displayed

2. Protection Proxy
• Controls access permissions to objects
• Example: Access control systems that verify user permissions before allowing resource access

3. Remote Proxy
• Represents objects in different address spaces
• Example: A local object representing a remote service

4. Smart Reference
• Performs additional actions when objects are accessed
• Example: Reference counting, locking mechanisms

Example: Virtual Proxy for Image Loading in C#

Problem: Loading high-resolution images is expensive and may not be immediately necessary.

Solution: Use a Virtual Proxy to load the actual image only when it needs to be displayed.

// Subject Interface
public interface IImage
{
    void Display();
}

// RealSubject
public class HighResolutionImage : IImage
{
    private string _filename;
    
    public HighResolutionImage(string filename)
    {
        _filename = filename;
        LoadImageFromDisk();
    }
    
    private void LoadImageFromDisk()
    {
        Console.WriteLine($"Loading high-resolution image: {_filename}");
        // Expensive operation: loading image data
        // In a real implementation, this might use System.Drawing or ImageSharp
        // to load and process the actual image file
    }
    
    public void Display()
    {
        Console.WriteLine($"Displaying high-resolution image: {_filename}");
    }
}

// Proxy
public class ImageProxy : IImage
{
    private string _filename;
    private HighResolutionImage _realImage;
    
    public ImageProxy(string filename)
    {
        _filename = filename;
    }
    
    public void Display()
    {
        // Create the real image only when Display is called
        if (_realImage == null)
        {
            _realImage = new HighResolutionImage(_filename);
        }
        _realImage.Display();
    }
}

// Client
public class Program
{
    public static void Main(string[] args)
    {
        // Using proxies for multiple images
        IImage image1 = new ImageProxy("photo1.jpg");
        IImage image2 = new ImageProxy("photo2.jpg");
        
        // The high-resolution image is loaded only when displayed
        Console.WriteLine("Application started...");
        Console.WriteLine("Displaying first image:");
        image1.Display();  // Only now is the first image loaded
        
        Console.WriteLine("Second image is not displayed, so it's never loaded");
        
        Console.ReadKey(); // Wait for user input before closing
    }
}

Benefits of the Proxy Pattern

Improved performance: Defers costly object creation until necessary
Enhanced security: Controls access to sensitive objects
Reduced complexity: Hides implementation details from clients
Increased flexibility: Enables features like caching, logging, and access control without changing the original object
Location transparency: Provides unified access to distributed objects

Limitations of the Proxy Pattern

Increased response time: Adds a level of indirection
Implementation complexity: Some proxy types can be complex to implement
Potential for overuse: Not every object needs a proxy

Real-World Applications

Web browsers: Caching proxy for web pages
ORM frameworks: Proxies for lazy loading of database entities
Credit cards: Act as proxies for bank accounts

Summary
The Proxy Pattern provides a surrogate for another object to control access to it. It's particularly useful for lazy loading, access control, and adding behavior when accessing objects. The pattern maintains the same interface as the original object while providing additional functionality.

Reference : Book : ”Design Patterns: Elements of Reusable Object-Oriented Software” by Gamma, Helm, Johnson, and Vlissides. also call Gun of Fure

Utility class of POM: Screenplay Pattern

Tue, 15 Apr 2025 08:51:06 +0000

Understanding the Screenplay Pattern in Test Automation

Test automation often starts simple a few UI actions, maybe a Page Object or two. But as the system grows, maintaining and scaling those tests becomes a real challenge.

Enter the Screenplay Pattern: a powerful, actor-based model for writing clean, reusable, and maintainable tests.

What is the Screenplay Pattern?

The Screenplay Pattern is a test automation design pattern that models test scripts like a movie script involving Actors, Tasks, Abilities, Interactions, and Questions.

It encourages us to:

Think in terms of what the actor does, not how
Build modular, readable, and reusable test logic
Focus on behavior rather than implementation

Key Building Blocks

Actor

Represents the user or persona interacting with the system.

Actor yusuf = Actor.named("Yusuf").whoCan(BrowseTheWeb.with(driver));

Task

A meaningful action or series of steps the actor performs.

public class Login implements Task {
    public static Login withCredentials(String username, String password) {
        return instrumented(Login.class, username, password);
    }

    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Enter.theValue(username).into(USERNAME_FIELD),
            Enter.theValue(password).into(PASSWORD_FIELD),
            Click.on(LOGIN_BUTTON)
        );
    }
}

Usage:

yusuf.attemptsTo(Login.withCredentials("admin", "1234"));

Question

Used to extract information from the system, like validations or assertions.

public class WelcomeMessage implements Question<String> {
    public String answeredBy(Actor actor) {
        return Text.of(WELCOME_MESSAGE_LOCATOR).viewedBy(actor).asString();
    }
}

Usage:

String message = yusuf.asksFor(new WelcomeMessage());

Ability

Defines what the actor can do. For example, browse the web or call APIs.

BrowseTheWeb.with(driver); // Enables web interactions

Target: Screenplay’s Way of Handling Locators

If you stuck with POM and cant quit completely(like me) you can still integrate it to your POM too. Instead of using Page Object Model and WebElements, the Screenplay Pattern uses Target objects to define locators.

In traditional POM:

@AndroidFindBy(accessibility = "Login Screen")
public WebElement loginScreen;

In Screenplay:

public final class LandingPage {

    private LandingPage() {} // Prevent instantiation

    public static final Target LOGIN_SCREEN = Target.the("Login screen")
        .locatedByAccessibilityId("Login Screen");

    public static final Target ECHO_BOX_SCREEN = Target.the("Echo Box screen")
        .locatedByAccessibilityId("Echo Box");

    public static final Target LIST_DEMO_SCREEN = Target.the("List Demo screen")
        .locatedByAccessibilityId("List Demo");

    public static final Target LIST_DATE_SCREEN = Target.the("Date Picker screen")
        .locatedByAccessibilityId("Picker Demo");

    public static final Target WEBVIEW_SCREEN = Target.the("WebView screen")
        .locatedByAccessibilityId("Webview Demo");
}

And in your tasks:

actor.attemptsTo(
    Click.on(LandingPage.LOGIN_SCREEN)
);

Benefits:

No need for PageFactory or WebElement instantiation
Targets are static, so they can be reused anywhere
Fully integrates with Screenplay’s task-based structure

If you're using Appium with Serenity, you can also use:

Target LOGIN_SCREEN = Target.the("Login screen")
    .located(MobileBy.AccessibilityId("Login Screen"));

Benefits of Screenplay Pattern

Improved readability (tests look like real scenarios)
High reusability (Tasks & Questions are shared across tests)
Better scalability for growing test suites
Strong adherence to SOLID principles

If you notice classes not using extends keyword for inheritance.(Congrats you are detail-oriented person) Because Screenplay prefers Composition over Inheritance.

Inheritance in Page Object Model vs. Implementation in Screenplay Pattern

One of the key architectural differences between the Page Object Model (POM) and the Screenplay Pattern lies in their use of object-oriented principles—specifically, inheritance versus implementation.

Page Object Model: Inheritance-Based Structure

In POM, it is common to use inheritance via the extends keyword. Typically, a base class (e.g., BasePage) is created to house shared functionalities such as clicking elements, sending input, or waiting for elements. All page classes then extend this base class to inherit these methods. This approach promotes code reuse but can lead to tightly coupled and less flexible designs.

public class BasePage {
    public void click(WebElement element) {
        element.click();
    }
}

public class LoginPage extends BasePage {
    WebElement loginButton;
}

Screenplay Pattern: Interface Implementation

Screenplay, on the other hand, follows a more composition-driven design by using interfaces like Task, Question, or Interaction, which are implemented rather than extended. This provides greater flexibility and promotes the principle of "composition over inheritance."

Each Actor performs actions by executing these Tasks or Questions, making the codebase more modular and maintainable.

public class Login implements Task {
    private final String username;
    private final String password;

    public static Login withCredentials(String username, String password) {
        return Tasks.instrumented(Login.class, username, password);
    }

    @Override
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Enter.theValue(username).into(LoginPage.USERNAME_FIELD),
            Enter.theValue(password).into(LoginPage.PASSWORD_FIELD),
            Click.on(LoginPage.LOGIN_BUTTON)
        );
    }
}

While POM is easier to grasp and implement for smaller test suites, the Screenplay Pattern offers a more scalable and maintainable architecture for complex testing needs.

Comparison: POM vs Screenplay

Feature	Page Object Model	Screenplay Pattern
Structure	Page-based	Actor-based
Code Reuse	Inheritance	Composition
Reusability	Moderate	High
Readability	Good	Excellent
Maintainability	Challenging in large projects	Easier due to modularity
Test Style	Imperative	Declarative
Design Focus	Pages & Elements	Tasks & Behaviors

Final Thoughts

The Screenplay Pattern takes a bit of setup at the beginning, because its a approach rather than ready-to-use methods.(Serenity Library comes with that methods!) but the benefits in clarity, reusability, and scalability are huge especially in large automation projects. If you're building or maintaining a serious test framework, it's worth giving Screenplay a try!

Thanks for reading.

Facade Pattern provides a simplified interface to complex subsystems, hiding implementation details behind a clean API.

Wed, 09 Apr 2025 19:04:44 +0000

The Facade Pattern: Simplifying Complex Systems

In modern software development, we often work with complex systems that consist of numerous interrelated components. These systems, while powerful, can be challenging to understand and use effectively. The Facade Pattern offers an elegant solution to this problem by providing a simplified interface to a complex subsystem.

The Problem: Complexity in Action

Consider a home theater system with multiple components:

Popcorn popper
Theater lights
Amplifier
Projection screen
Projector
CD player
Tuner
DVD player

To watch a movie, a user would need to perform 13 separate operations:

Turn on the popcorn popper
Start the popper popping
Dim the lights
Put the screen down
Turn the projector on
Put the projector on wide-screen mode
Set the projector input to DVD
Turn the sound amplifier on
Set the amplifier to DVD input
Set the amplifier volume to medium
Turn the DVD player on
Set the amplifier to surround sound
Start the DVD player playing

This process is cumbersome, error-prone, and requires detailed knowledge of each component and their interactions. Clearly, we need a highly abstract approach that simplifies our interaction with the system without worrying about the details.

The Facade Pattern: Definition and Purpose

The Facade Pattern provides a unified interface to a set of interfaces in a subsystem. It defines a higher-level interface that makes the subsystem easier to use by hiding its complexity from clients.

The pattern emerged from the need to simplify interactions with complex systems. As software systems grow, they often develop intricate subsystems with numerous components and relationships. This complexity creates several challenges:

Steep learning curves for new developers
Increased coupling between clients and implementation details
Difficulty in maintaining code that interacts with many components
Error-prone integration processes

How It Works

The Facade Pattern works by:

Creating a new class (the facade) that presents a simplified interface
Internally, the facade manages the complex interactions with subsystem components
Clients interact only with the facade rather than directly with the subsystem
The facade translates simple, high-level requests into the appropriate sequence of subsystem operations

This approach shields clients from the complexity of the subsystem while still allowing them to access its functionality.

Basic Components

The Facade Pattern consists of:

The Facade: A class that provides a simplified interface to the subsystem
The Subsystem: A set of complex classes that implement functionality
The Client: Code that interacts with the subsystem through the façade

Important Note: The pattern does not alter the subsystem classes or prevent clients from accessing them directly if needed. It simply offers an easier way to use the subsystem for common tasks.

Solution to the Home Theater Problem

To solve our home theater complexity problem, we can create a HomeTheaterFacade class that wraps all the subsystem components and provides simplified methods:

public class HomeTheaterFacade {
    
    // Component references
    Amplifier amp;
    Tuner tuner;
    DvdPlayer dvd;
    CdPlayer cd;
    Projector projector;
    TheaterLights lights;
    Screen screen;
    PopcornPopper popper;
    
    // Constructor with component initialization
    public void watchMovie(String movie) {
        
        System.out.println("Get ready to watch a movie...");
        popper.on();
        popper.pop();
        lights.dim(10);
        screen.down();
        projector.on();
        projector.wideScreenMode();
        amp.on();
        amp.setDvd(dvd);
        amp.setSurroundSound();
        amp.setVolume(5);
        dvd.on();
        dvd.play(movie);
    }
    
    public void endMovie() {
        // Similar sequence to shut everything down
    }
    
    // Other methods for different use cases
}

Now, instead of 13 separate operations, the client simply calls:

homeTheater.watchMovie("Raiders of the Lost Ark");
// When finished
homeTheater.endMovie();

The Principle of Least Knowledge

The Facade Pattern supports the Principle of Least Knowledge (or Law of Demeter), which states: "Talk only to your immediate friends." This principle guides us to reduce the interactions between objects to just a few closely related classes.

For any object, you should only invoke methods that belong to:

The object itself
Objects passed as parameters to a method
Any object the method creates
Any direct component objects

The Facade Pattern supports this principle by:

Providing clients with a single point of contact (the facade)
Handling all the complex interactions with the subsystem internally
Reducing the number of objects the client needs to know about
Creating clear boundaries between the client and the subsystem

This reduces dependencies and makes the system more maintainable.

Benefits of the Facade Pattern

Simplified Interface: Provides a simple interface to a complex subsystem, making it easier to use.
Reduced Coupling: Decreases the dependency between client code and subsystem components.
Subsystem Flexibility: Allows the subsystem to change without affecting client code.
Improved Code Readability: Makes client code more readable and focused on high-level tasks.
Better System Organization: Creates clear layers in your architecture.

Disadvantages of the Facade Pattern

Limited Functionality Access: May restrict access to some advanced features of the subsystem.
Additional Indirection Layer: Adds an extra layer in the architecture.
Potential Facade Bloat: The facade class can become too large if not designed carefully.
Maintenance Overhead: Requires updating when the subsystem changes.
Minor Performance Impact: May introduce slight overhead due to delegation.

Relation with Other Patterns

The Facade Pattern differs from similar patterns in key ways:

Facade vs. Adapter

Purpose: Adapter converts one interface to another; Facade simplifies complex interfaces
Interface Change: Adapter changes interface format; Facade maintains format but simplifies
Intent: Adapter makes incompatible interfaces compatible; Facade hides complexity

Facade vs. Abstract Factory

Purpose: Abstract Factory creates families of related objects; Facade simplifies access to subsystem functionality
Intent: Abstract Factory abstracts object creation; Facade abstracts subsystem use
Client Knowledge: Abstract Factory client creates objects; Facade client uses existing objects

Application in Layered Architecture

The Facade Pattern is frequently used in layered architectures where it acts as a gateway between layers. For example, in a typical application with UI, Domain, and Data layers, facades can provide clean interfaces between these layers.

Modern Applications: CQRS Facades

In modern software architecture, the Facade Pattern finds application in Command Query Responsibility Segregation (CQRS) where separate facades are used for commands (write operations) and queries (read operations), providing cleaner code separation.

CQRS Facades: Cleaner Code Separation | by Anthony Miller | Medium

Conclusion

The Facade Pattern offers a powerful way to manage complexity in software systems. By providing a simplified interface to complex subsystems, it makes code more maintainable, readable, and flexible. While it does introduce an additional layer of abstraction, the benefits in terms of usability and maintainability often outweigh this cost, particularly in systems with complex components that need to work together seamlessly.

When designing your next complex system, consider whether a facade might help simplify your client code and create cleaner boundaries between system components.

Mastering System Design: Your Definitive Guide to Success in Tech Interviews

Mon, 31 Mar 2025 18:31:47 +0000

Table of Contents

Introduction
Key Concepts of System Architecture
Imagine This Scenario
How This Relates to Design Patterns
Problems Solved by Scalability
Example in TypeScript, JavaScript
Pros and Cons of Real-Time Systems
Summary
Key Takeaways

Introduction

System design is a critical component in the toolkit of any software engineer, especially when preparing for interviews at top tech companies like "MAANG" (Meta, Amazon, Apple, Netflix, Google) or "MAMAA" (Meta, Amazon, Microsoft, Apple, Alphabet). A deep understanding of system architecture, design patterns, and the ability to build scalable systems is indispensable. This guide provides insights and practical knowledge to ace system design interviews and excel in the tech industry.

Key Concepts of System Architecture

System architecture refers to the structured design of a system’s components and their interactions. It involves defining software and hardware components, implementing system requirements, and ensuring the system's overall integrity and flexibility to adapt to future demands. Understanding system architecture is crucial for designing scalable, maintainable, and efficient software solutions.

Imagine This Scenario

To grasp system architecture better, let’s consider a real-world analogy:

Imagine a bustling cafe that starts with a single barista serving coffee. As its popularity grows:

Vertical Scaling: The cafe upgrades its equipment (e.g., faster coffee machines) to serve more customers.
Horizontal Scaling: The cafe opens new branches in different locations to handle demand.

Similarly, in system design, ensuring your architecture can scale both horizontally and vertically is essential to maintaining performance as demand increases.

How This Relates to Design Patterns

System architecture and design patterns are closely linked:

System Architecture: Provides the high-level overview of the entire system.
Design Patterns: Offer tested templates for solving specific problems within that architecture.

Design patterns not only enhance scalability and maintainability but also enforce coding standards, improve readability, and reduce technical debt—all crucial for solving complex real-world problems.

Problems Solved by Scalability

Scalability addresses the need to handle increased loads while maintaining performance and cost-efficiency. Key benefits include:

Managing large volumes of data efficiently.
Maintaining system performance during peak loads.
Reducing latency.
Supporting elasticity (scaling up during high demand and scaling down to optimize costs during low demand).

Load balancers play a pivotal role in scalable architectures by distributing traffic evenly across servers, ensuring seamless performance.

Example in TypeScript, JavaScript

Here’s an example demonstrating the Singleton Design Pattern with a practical use case: managing a database connection.

// Singleton Pattern - Managing a Database Connection in TypeScript
class Database {
  private static instance: Database;

  private constructor() {
    console.log("Database connection established.");
  }

  public static getInstance(): Database {
    if (!Database.instance) {
      Database.instance = new Database();
    }
    return Database.instance;
  }

  public query(sql: string) {
    console.log(`Executing query: ${sql}`);
  }
}

// Usage
const db1 = Database.getInstance();
const db2 = Database.getInstance();

db1.query("SELECT * FROM users");
console.assert(db1 === db2, "Both are the same instance");

Notes:

Use Singleton patterns cautiously as they introduce global state and can make unit testing more challenging.
In modern applications, dependency injection is often preferred to manage shared resources like database connections.

Pros and Cons of Real-Time Systems

Pros

Provide immediate processing and response.
Essential for applications requiring prompt data handling (e.g., stock trading platforms, IoT systems).
Cloud services like AWS Kinesis or Azure Event Hubs make real-time processing more accessible.

Cons

Developing real-time systems is complex and demands precise specifications.
Maintenance costs can be higher due to specialized requirements.
Testing real-time systems requires simulating live environments, which can be resource-intensive.

Summary

This article explored key aspects of system design, including system architecture, design patterns, scalability, and real-time systems. By understanding these concepts:

Developers can design robust systems capable of handling modern demands.
Interview candidates can prepare effectively for high-stakes system design discussions at top tech companies.

Key Takeaways

Scalability:

Involves horizontal scaling (adding more servers) and vertical scaling (upgrading existing servers).
Elasticity allows systems to scale up or down based on demand, optimizing costs in cloud environments.
Load balancers are critical for distributing traffic efficiently.

Design Patterns:

Enhance maintainability, readability, and scalability while reducing technical debt.
Singleton patterns should be used judiciously due to their impact on global state management.

Real-Time Systems:

Pros: Immediate response times are essential for critical applications.
Cons: Complex development and maintenance requirements, though cloud-based solutions reduce infrastructure costs.

Understanding the Observer Pattern in C# with IObservable and IObserver

Tue, 11 Mar 2025 10:41:06 +0000

Introduction

The Observer Pattern is a behavioral design pattern that allows an object (the subject) to notify multiple other objects (observers) about state changes. It is commonly used in event-driven programming, messaging systems, and real-time notifications.

C# provides a built-in way to implement this pattern using the IObservable and IObserver interfaces. Unlike traditional event handlers, IObservable offers better flexibility, structured error handling, and built-in subscription management.

Implementation of the Observer Pattern

The following example is based on the ObserverPattern repository by me.

using System;
using System.Collections.Generic;

namespace ObserverPattern
{
    // Observable: Order Processor
    public class OrderProcessor : IObservable<string>
    {
        private List<IObserver<string>> observers = new();

        public IDisposable Subscribe(IObserver<string> observer)
        {
            if (!observers.Contains(observer))
                observers.Add(observer);
            return new Unsubscriber(observers, observer);
        }

        public void ProcessOrder(int orderId)
        {
            Notify($"Order {orderId} is Processing");
            Notify($"Order {orderId} is Shipped");
            Notify($"Order {orderId} is Delivered");
        }

        private void Notify(string message)
        {
            foreach (var observer in observers)
                observer.OnNext(message);
        }

        private class Unsubscriber : IDisposable
        {
            private List<IObserver<string>> _observers;
            private IObserver<string> _observer;

            public Unsubscriber(List<IObserver<string>> observers, IObserver<string> observer)
            {
                _observers = observers;
                _observer = observer;
            }

            public void Dispose()
            {
                if (_observer != null && _observers.Contains(_observer))
                    _observers.Remove(_observer);
            }
        }
    }

    // Observer: Console Logger
    public class ConsoleLogger : IObserver<string>
    {
        public void OnNext(string value) => Console.WriteLine($"[Console] {value}");
        public void OnError(Exception error) => Console.WriteLine("[Console] Error occurred.");
        public void OnCompleted() => Console.WriteLine("[Console] No more updates.");
    }

    // Observer: File Logger
    public class FileLogger : IObserver<string>
    {
        private readonly string filePath = "log.txt";

        public void OnNext(string value)
        {
            using StreamWriter writer = new(filePath, append: true);
            writer.WriteLine(value);
        }

        public void OnError(Exception error)
        {
            using StreamWriter writer = new(filePath, append: true);
            writer.WriteLine("[File] Error occurred.");
        }

        public void OnCompleted()
        {
            using StreamWriter writer = new(filePath, append: true);
            writer.WriteLine("[File] No more updates.");
        }
    }

    // Main Program
    class Program
    {
        static void Main()
        {
            var orderProcessor = new OrderProcessor();
            var consoleLogger = new ConsoleLogger();
            var fileLogger = new FileLogger();

            using var consoleSubscription = orderProcessor.Subscribe(consoleLogger);
            using var fileSubscription = orderProcessor.Subscribe(fileLogger);

            orderProcessor.ProcessOrder(101);
        }
    }
}

1.OrderProcessor (Observable)

-Implements IObservable<string>    
-Notifies observers of order status changes    
-Allows observers to subscribe and unsubscribe dynamically

2.Observers (ConsoleLogger & FileLogger)

-Implement IObserver
-ConsoleLogger logs messages to the console
-FileLogger writes updates to a log file

3.Subscription Management

-Uses IDisposable to allow safe unsubscription
-Observers receive updates dynamically

Why Not Use Event Handlers (event and delegate)?

Benefits of Using IObservable and IObserver

✅ Better Resource Management: Unsubscribing is handled via IDisposable, reducing memory leaks.

✅ Built-in Error Handling: The OnError(Exception) method provides structured error handling.

✅ Completion Notification: OnCompleted() informs observers when no more updates will be sent.

✅ Supports Asynchronous & Reactive Programming: Works seamlessly with Reactive Extensions (Rx.NET).

✅ Scales Well for Complex Scenarios: Ideal for event-driven architectures where multiple observers must react to state changes dynamically.

Real-World Use Cases

Event-driven programming (e.g., UI events, logging systems)
Stock market applications (e.g., notifying traders about price

changes)
Messaging and notification systems (e.g., email/SMS updates)
Reactive programming (e.g., Rx.NET, streaming APIs)
IoT (Internet of Things) (e.g., sensor data updates)

Conclusion

The Observer Pattern is an essential design pattern for event-driven applications. While event handlers (event and delegate) are useful for simple event propagation, IObservable and IObserver provide a more structured and flexible approach to managing subscriptions, error handling, and completion notifications.

By leveraging this pattern, developers can build scalable, reactive, and event-driven applications that efficiently manage state changes across multiple subscribers.

References

GitHub Repository:

        <a href="https://github.com/stevsharp/ObserverPattern" target="_blank">ObserverPattern</a>

Microsoft Docs:

Reactive Extensions (Rx.NET) Official:

Book Reference :

Design Patterns: Elements of Reusable Object-Oriented Software

Coder Legion - Recent posts tagged designpatterns

Security by Design in the Age of Artificial Intelligence: Fundamentals, Risks and Resilience Strateg

From traditional security to algorithmic security

Vulnerabilities specific to the AI era

Data poisoning

Adversarial Attacks

Model Inversion & Data Extraction

Prompt Injection (in LLMs)

Integrating Security into the AI Lifecycle

Zero Trust and the new paradigm of trust

Regulation, governance and accountability

The ethical dimension of security

Red Teaming and Operational Resilience

Future Challenges

Conclusion: Security as the Foundation of Trust

Bibliography

Anatomy of a Short Link, When People Actually Want to Click?

Five small details that make a short url feel clearer, safer, and more memorable

1. A recognizable domain comes first

Developer checklist

2. The slug should explain the destination

3. The words around the link must set expectations

4. Visual treatment should make the click obvious

5. The redirect should feel safe and predictable

Putting the five details together

A quick pre-publish test for web developers

Final takeaway

Frequently Asked Questions

What makes a link more clickable?

Should developers use descriptive link text instead of “click here”?

Are short links safe to click?

Do branded short links improve trust?

Do short links help SEO?

Demystifying Dependency Injection: Writing Code That Doesn't Break When Things Change

What is Dependency Injection?

The Hybrid Car Battery Analogy

Why Dependency Injection Matters Every Day

Dependency Injection in Action

The Takeaway

Resources

Three Go Concurrency Mistakes I See in Almost Every Worker Pool

Mistake 1: Goroutine leaks from channels that never close

Mistake 2: WaitGroup counter manipulation in the wrong place

Mistake 3: Unidirectional channel types ignored on function boundaries

Summary

Go Interfaces: Why Less Is Almost Always More

Go Interfaces: Why Less Is Almost Always More

What the standard library is trying to tell you

The fat interface trap

The Go way: consumer-defined, minimal interfaces

Accepting interfaces, returning structs

Composing small interfaces when you need more

Summary

Prototype Design Pattern in C#: Cloning Objects Efficiently

Introduction

Understanding the Prototype Pattern

Structure

Prototype Pattern Example in C

Abstract Prototype

Explanation

Concrete Prototype: Ford

Explanation

Client Code

How the Program Works

Step 1: Create Prototype Objects

Step 2: Clone Instead of Creating

Step 3: Customize the Clone

Step 4: Repeat for Other Car Types

Understanding MemberwiseClone()

What Gets Copied?

Value Types

Reference Types

Shallow Copy vs Deep Copy

Shallow Copy

Deep Copy

Is MemberwiseClone() Safe?

Yes, when:

Be Careful When:

Benefits of the Prototype Pattern

1. Faster Object Creation

Understanding `MemberwiseClone()`

Is `MemberwiseClone()` Safe?

What is `SemaphoreSlim`?

Why do we still need `lock`?

Other options instead of `lock`

Option 1: `Monitor`

Option 2: `Mutex`

Alternative 1: `Channel<T>`

Alternative 2: `BlockingCollection<T>`

Alternative 3: `ConcurrentQueue<T>`

Alternative 4: `Semaphore`