DEV Community: Naimul Karim

Stop Prompt Engineering, Start Context Engineering

Naimul Karim — Mon, 03 Aug 2026 04:32:35 +0000

AI agents get talked about a lot, but most explanations stay abstract. Here's a short, practical breakdown of what actually makes an agent work — plus a simple example.

Chat vs. Agent

Chat model → question → answer (you do the work)
Agent → goal → result (it plans + executes for you)

Chat:   You ask ──> Model answers ──> You act
Agent:  You set goal ──> Agent plans → acts → checks ──> Result delivered

The Agent Loop

Every agent — no matter the platform — runs the same loop:

   ┌─────────┐
   │ OBSERVE │  read context, current state
   └────┬────┘
        ▼
   ┌─────────┐
   │  THINK  │  decide next action
   └────┬────┘
        ▼
   ┌─────────┐
   │   ACT   │  execute, then loop again
   └────┬────┘
        │
        └──────► repeats until task is done

An agent = LLM (brain) + Loop + Tools + Context. The "harness" (Claude Code, Cowork, Codex, etc.) is just the app that runs this loop.

The Stack, in Layers

┌────────────────────────────┐
│ 5. Skills   → reusable SOPs │
├────────────────────────────┤
│ 4. Tools    → via MCP       │
├────────────────────────────┤
│ 3. Memory   → memory.md     │
├────────────────────────────┤
│ 2. Context  → agents.md     │
├────────────────────────────┤
│ 1. Loop     → observe→think→act │
└────────────────────────────┘

Context file (agents.md / Claude.md) — persistent "system prompt" with your role, business, tools, and preferences. Loaded every session.
Memory (memory.md) — updated whenever the agent is corrected. Compounds over time.
Tools (MCP) — Model Context Protocol connects the agent to Gmail, Notion, Calendar, Stripe, etc. without custom integration work per tool.
Skills — a markdown file documenting a repeatable process once, so it never needs re-explaining. Can be chained or scheduled.

Prompt engineering → Context engineering. Rich context turns a 2-word prompt into a great result.

A Quick Example

A solo creator automating their weekly newsletter:

agents.md — newsletter's audience, tone, format, connected tools (Notion, Docs, social)
memory.md — learns preferences over time ("shorter subject lines," etc.)
Connect Notion + Docs + social via MCP
One prompt: "Pull this week's notes, draft the issue, write a companion thread."
Package it as a weekly-newsletter skill → schedule it for every Thursday

Same shape every time: context + memory + tools set up once → simple prompts → consistent results.

Starter Checklist

[ ] Pick a simple harness, create a project folder
[ ] Write agents.md (role, business, tools, preferences)
[ ] Add a starter memory.md
[ ] Connect 2–3 high-value tools via MCP
[ ] Run a real task, watch the loop work
[ ] Turn a repeatable task into a skill
[ ] Schedule a recurring skill
[ ] Repeat for another role/project

This isn't about cleverer prompts — it's front-loading context once so every future ask can stay simple.

AI Agentic Workflow Explained: A Quick Tour of Harness, Tools, Skills, MCP, and Memory

Naimul Karim — Wed, 22 Jul 2026 04:35:27 +0000

AI applications are moving beyond simple chat experiences.

The next generation of AI systems are AI agents — systems that can understand goals, reason about problems, use external tools, access enterprise data, and complete multi-step workflows.

However, an AI agent is not just a Large Language Model (LLM) with a prompt.

A production AI agent is a combination of multiple components working together:

AI Agent
   |
   +-- Model
   |
   +-- Harness
   |
   +-- Tools
   |
   +-- MCP Integrations
   |
   +-- AGENTS.md
   |
   +-- Skills
   |
   +-- Memory

The model provides intelligence and reasoning.

The surrounding infrastructure provides the ability to take action reliably.

Understanding the AI Agent Workflow

A typical AI agent execution flow looks like this:

                    User Request
                         |
                         v
                  Agent Harness
                         |
        +----------------+----------------+
        |                                 |
        v                                 v
 Load Always-On Context          Understand Task
        |                                 |
        |                                 v
        |                         Select Relevant Skills
        |                                 |
        |                                 v
        +------------------------ Load Skill Context
                         |
                         v
                 Retrieve Memory
                         |
                         v
              Discover Tools via MCP
                         |
                         v
                  Agent Reasoning
                         |
                         v
                  Execute Actions
                         |
                         v
              Observe Tool Results
                         |
                         v
              Update Context/Memory
                         |
                         v
                  Task Completed

At the core of this workflow is a continuous loop:

Reason → Act → Observe → Repeat

The model decides what should happen next.

The agent infrastructure makes those decisions actionable.

1. Agent Harness: The Runtime Behind the Agent

The AI Agent Harness is the execution layer that surrounds the model.

It manages:

Task execution
Context assembly
Tool access
Skill loading
Memory retrieval
Security policies
Observability

A useful analogy:

The model is the brain. The harness is the environment that allows the brain to interact with the world.

For example:

User request:

"Find customers who have not logged in for 90 days and send them a reminder email."

The model reasons:

"I need customer activity data and an email capability."

The harness handles:

Loading relevant capabilities
Accessing customer data
Generating email content
Applying approval rules
Sending the communication

The harness connects reasoning with execution.

2. Tools: Giving Agents the Ability to Act

Tools provide agents with the ability to interact with external systems.

Examples:

APIs
Databases
Search engines
Code execution environments
File systems
Business applications

Without tools, an LLM can only provide recommendations.

With tools, an agent can perform actions.

Example:

The model decides:

"I need customer information.
I will query the database."

The harness executes:

SELECT *
FROM customers
WHERE last_login < CURRENT_DATE - INTERVAL '90 days';

The result is returned to the model.

This creates the agent loop:

Reason → Tool Call → Result → Reason Again

3. Model Context Protocol (MCP): Standardizing Tool Connections

As agents become more capable, they need access to many external systems.

Managing custom integrations for every application does not scale.

This is where Model Context Protocol (MCP) becomes important.

MCP provides a standard way for AI applications to connect with external tools and data sources.

Without MCP:

Agent

 ├── Custom Database Connector
 ├── Custom File Connector
 ├── Custom API Connector
 └── Custom Search Connector

With MCP:

Agent

       |
  MCP Client

       |
 -------------------------
 |          |             |
Database   Files        APIs
MCP        MCP          MCP
Server     Server       Server

An MCP server can expose capabilities:

search_customers()

get_customer_orders()

update_customer_record()

MCP separates:

Agent reasoning
Tool implementation
Enterprise system access

4. AGENTS.md: The Agent's Always-Loaded Instructions

As agent systems grow, context management becomes critical.

Not every instruction should be loaded for every task.

AGENTS.md provides the agent with its always-available operating instructions.

It defines the baseline rules for how an agent should work.

Typical contents include:

Project conventions
Coding standards
Security rules
Repository guidelines
Environment instructions
Common workflows

Example:

project/

├── AGENTS.md
├── src/
├── tests/
└── skills/

Example AGENTS.md:

# Agent Instructions

## Project Rules

- Follow coding standards
- Run tests before committing changes
- Never expose secrets
- Update documentation when required

## Development Workflow

1. Understand the requirement
2. Inspect existing code
3. Implement changes
4. Validate results
5. Provide a summary

Because AGENTS.md is always included in the context, it should contain only essential instructions.

A large AGENTS.md increases context usage and can reduce agent effectiveness.

5. Skills: Dynamic Agent Capabilities

Skills provide specialized knowledge and workflows that are loaded only when relevant.

Unlike AGENTS.md, skills are not always included in the context.

They are selected dynamically based on the task.

Examples:

Database migration skill
Security review skill
Frontend development skill
Documentation skill

Example structure:

skills/

├── database-migration/
│   └── SKILL.md
│
├── security-review/
│   └── SKILL.md
│
└── api-development/
    └── SKILL.md

Example SKILL.md:

# Database Migration Skill

## Purpose

Safely modify database schemas.

## Workflow

1. Analyze schema changes
2. Create migration scripts
3. Validate compatibility
4. Run migration tests
5. Review rollback strategy

The harness loads this skill only when a database migration task appears.

AGENTS.md vs Skills: Why Both Matter

A common mistake is putting every instruction into AGENTS.md.

Example:

AGENTS.md

- Coding rules
- Database procedures
- Deployment workflows
- Security reviews
- Testing strategies
- Documentation rules

Over time, this file becomes too large.

The agent receives unnecessary information for every task.

A better approach:

AGENTS.md

Always loaded:
- Core rules
- Project conventions
- Security requirements


Skills

Loaded when needed:
- Database workflows
- Deployment procedures
- Security analysis
- API patterns

The goal is not maximum information.

The goal is the right information at the right time.

6. Memory: Giving Agents Continuity

LLMs are stateless by default.

Without memory, every interaction starts from zero.

Agent memory usually has multiple layers.

Short-Term Memory

Current conversation context.

Example:

User:
"My order arrived damaged."

Agent remembers:

- Order details
- Previous messages
- Current issue

Working Memory

Temporary information needed during execution.

Example:

Research Task:

Files analyzed:

- sales_report.csv
- customer_feedback.json
- product_notes.md

Long-Term Memory

Information retained across sessions.

Example:

{
  "user_preferences": {
    "communication": "email",
    "language": "English"
  }
}

Memory allows agents to become more personalized and effective.

Complete AI Agent Workflow Example

Consider a software engineering agent.

User request:

"Fix the failing payment API tests."

Step 1: Load Agent Instructions

The harness loads:

AGENTS.md

- Coding standards
- Repository rules
- Security policies

Step 2: Load Relevant Skills

The harness identifies the task and loads:

software-engineering-skill/

├── SKILL.md
├── coding-guidelines.md
└── testing-workflow.md

Step 3: Retrieve Memory

The agent recalls:

Previous changes:

- Payment API migration completed
- Database schema updated
- Authentication tests modified

Step 4: Discover Tools Through MCP

The agent accesses:

MCP Servers:

- Git repository
- CI/CD system
- Test runner
- Issue tracker

Step 5: Execute the Task

Actions:

1. Analyze failing tests
2. Inspect source code
3. Modify implementation
4. Run tests
5. Review results

Step 6: Verify and Complete

The harness validates:

Tests pass
Policies are followed
No restricted actions occurred

The agent delivers the result.

Why Agentic Workflows Matter

Building AI agents is no longer only about choosing a powerful model.

Reliable agents require:

Component	Purpose
Harness	Runs and coordinates the agent
Tools	Enable external actions
MCP	Standardizes integrations
AGENTS.md	Provides always-on instructions
Skills	Provide task-specific expertise
Memory	Maintains context over time

The model provides intelligence.

The workflow around the model provides capability.

Final Thoughts

The future of AI applications will be built around agentic workflows.

Successful AI agents will combine:

Reasoning models
Execution harnesses
Tool ecosystems
MCP-based integrations
Dynamic skills
Context-aware memory

The biggest shift is moving from:

"How do we prompt the model?"

to:

"How do we design the complete system around the model?"

That is the foundation of modern AI agent engineering.

What is an AI Agent Harness?

Naimul Karim — Wed, 22 Jul 2026 04:20:31 +0000

Large Language Models (LLMs) are incredibly good at understanding language, reasoning through problems, and generating responses. However, on their own, they cannot execute code, call APIs, access files, remember previous work, or complete multi-step workflows.

To move beyond answering prompts and actually perform tasks, an LLM needs an AI Agent Harness.

An AI Agent Harness is the software infrastructure that surrounds a Large Language Model (LLM) and enables it to interact with the outside world. It connects the model to tools, memory, execution environments, and safety controls, allowing the model's decisions to be translated into meaningful actions.

Simply put:

AI Agent = Model + Harness

Think of the model as the brain that reasons and decides what should happen next. The harness is everything around it that enables those decisions to be executed safely and reliably.

What Does an AI Agent Harness Provide?

A typical AI agent harness consists of four key capabilities.

Tools

The harness connects the model to external systems, including:

APIs
Databases
Search engines
Code execution environments
Business applications

These tools allow the agent to perform actions instead of simply generating text.

Memory

Models have limited context windows and do not remember previous interactions by default.

The harness manages:

Conversation history
User preferences
Previous workflow state
Long-term task context

This enables agents to continue work across multiple interactions.

Workspace

Agents often need an environment where they can perform tasks.

A harness provides access to:

Files
Documents
Data
Execution environments
Shared storage

This workspace allows agents to create, modify, and persist information while completing tasks.

Guardrails

Enterprise agents need to operate safely.

The harness enforces:

Permissions
Security policies
Human approval workflows
Monitoring
Governance controls

Without these safeguards, an agent could perform actions that should not happen automatically.

Why Do AI Agents Need Both a Model and a Harness?

Modern AI agents are built around two complementary layers:

Component	Responsibility
Model	Reasons, plans, and decides what to do next
Harness	Executes those decisions using tools, memory, and external systems

The model focuses on thinking.

The harness focuses on doing.

Together, they form a complete AI agent.

The Reason → Act → Observe Loop

Most AI agents operate using a continuous execution cycle known as the ReAct (Reason + Act) pattern.

Reason
   |
   v
Act
   |
   v
Observe
   |
   v
Repeat

1. Reason

The model analyzes:

The user's request
Available context
Previous results

It determines the next action required to move toward the goal.

2. Act

The harness executes that action by:

Calling an API
Running code
Querying a database
Searching external sources
Updating files

3. Observe

The result of that action is returned to the model as new context.

4. Repeat

The model reasons again using the updated information.

This cycle continues until the task is completed.

For example, consider a coding agent fixing a bug:

The model proposes a code change.
The harness runs the code in an isolated sandbox.
Test results are returned to the model.
If tests fail, the model analyzes the errors and tries another approach.

The model focuses on solving the problem, while the harness manages execution and feedback.

Model vs Harness vs Agent

These terms are often used interchangeably, but they represent different parts of an AI system.

Component	What it Does	Analogy
Model	Reasons and generates outputs	Brain
Harness	Executes actions, manages memory, tools, and policies	Body and workspace
Agent	Complete system combining model and harness	Worker that can think and act

The agent is not just the model.

It is the combination of intelligent reasoning and the infrastructure required to turn decisions into real-world actions.

Core Building Blocks of an AI Agent Harness

Most production-ready harnesses include several foundational components.

System Prompts

System prompts provide persistent instructions that define:

The agent's role
Objectives
Rules
Behavioral constraints

They establish the operating guidelines before the agent begins a task.

Tool Execution

The model decides which tool should be used.

The harness is responsible for:

Executing the tool
Handling authentication
Capturing results
Returning information back to the model

Execution Environments (Sandboxes)

Running AI-generated code directly on production systems creates security risks.

Sandboxes provide isolated environments where agents can:

Execute code safely
Experiment
Run tests
Avoid unintended system changes

Filesystem and Storage

Long-running tasks require persistent storage.

The harness manages:

Files
Intermediate results
Notes
Plans
Generated artifacts

This allows agents to maintain progress across sessions.

Memory and Context Management

Models have limited context windows, so the harness manages what information remains available.

This includes:

Keeping relevant information active
Summarizing older conversations
Retrieving previous task history

Good context management helps agents maintain performance during complex workflows.

Feedback and Self-Verification

Reliable agents do not simply generate output and stop.

The harness can:

Run tests
Validate results
Check outputs
Ask the model to review its own work

These feedback loops allow agents to detect mistakes and improve their actions.

Guardrails and Human-in-the-Loop Controls

Some actions require human approval.

Examples include:

Sending external communications
Making financial transactions
Deleting important data

The harness can introduce approval checkpoints before executing sensitive operations.

Observability and Logging

Production systems need visibility into agent behavior.

The harness records:

Tool calls
Execution traces
Latency
Errors
Token usage
Workflow history

This helps developers debug, evaluate, and improve agent systems.

Why Harness Design Matters

As LLMs become more capable, the harness becomes an increasingly important factor in agent performance.

A strong harness improves:

Context management
Tool orchestration
Memory handling
Verification
Safety
Reliability

In many real-world scenarios, a well-designed harness around a smaller model can outperform a more capable model with poor execution infrastructure.

The future of AI performance will depend not only on better models but also on better systems built around those models.

Harness Engineering: The Next Evolution

AI development has evolved through several stages:

Discipline	Focus
Prompt Engineering	Writing better instructions for models
Context Engineering	Controlling the information provided to models
Harness Engineering	Designing the complete runtime environment around models

Prompt engineering and context engineering are now becoming parts of a broader discipline: Harness Engineering.

Harness engineering focuses on building the complete ecosystem that allows AI agents to operate reliably in real-world environments.

Final Thoughts

A language model provides intelligence, but intelligence alone does not create an AI agent.

An AI Agent Harness transforms that intelligence into action by connecting the model to tools, memory, execution environments, and safety mechanisms.

As AI agents become more autonomous and move into production systems, harnesses will become one of the most important layers of the AI technology stack.

The future of AI will not be defined only by the models we build. It will also be defined by the quality of the harnesses that allow those models to work effectively.

How I Fixed Windows 11 Sleep Not Working by Tracking Down a Hidden WebView2 Video Wake Lock

Naimul Karim — Wed, 22 Jul 2026 02:59:39 +0000

Have you ever configured your Windows laptop to sleep after a few minutes of inactivity, only to find the screen never turns off?

I recently ran into this issue on my Dell Inspiron 16 running Windows 11 Pro, and after hours of troubleshooting, I discovered the culprit wasn't Windows itself—it was an application using Microsoft Edge WebView2.

Here's how I diagnosed and fixed it.

🖥️ The Problem

My power settings were configured correctly:

Display turns off after 3 minutes
Sleep after 3 minutes
Hibernate enabled

Despite that, the laptop would remain awake indefinitely. The display never turned off, and the system never entered sleep.

🔍 Step 1: Check for Power Requests

Windows includes a built-in command that tells you what's preventing your computer from sleeping.

Open Command Prompt as Administrator and run:

powercfg /requests

The output looked something like this:

DISPLAY:
[PROCESS] msedgewebview2.exe
Video Wake Lock

The important part was Video Wake Lock.

A Video Wake Lock tells Windows that media playback is active, so Windows intentionally keeps the display awake.

🔎 Step 2: Find Which Application Owns WebView2

Many Windows applications use Microsoft Edge WebView2, so simply seeing msedgewebview2.exe doesn't tell you which application is responsible.

I used PowerShell to identify the parent process for each WebView2 instance:

Get-CimInstance Win32_Process |
Where-Object {$_.Name -eq "msedgewebview2.exe"} |
Select-Object ProcessId, ParentProcessId,
@{
    Name="Host"
    Expression={
        (Get-CimInstance Win32_Process -Filter "ProcessId=$($_.ParentProcessId)").Name
    }
} | Sort-Object Host

The output revealed several applications using WebView2:

Widgets.exe
Microsoft Teams
SearchHost.exe
Visual Studio (devenv.exe)
PCAppStore.exe

At this point I still didn't know which one was preventing sleep.

🧪 Step 3: Eliminate Processes One by One

I terminated each host process individually and checked the power requests again.

Stop-Process -Id <PID> -Force

After each process was stopped, I reran:

powercfg /requests

When I terminated PCAppStore.exe, the output immediately changed to:

DISPLAY:
None.

🎉 That was the smoking gun.

PCAppStore.exe was holding a Video Wake Lock through WebView2, preventing Windows from turning off the display or entering sleep.

💻 Step 4: Verify Sleep Support

To ensure there wasn't a hardware limitation, I checked the supported sleep states:

powercfg /a

The output showed:

Standby (S0 Low Power Idle)
Hibernate

This means the laptop uses Modern Standby (S0) rather than the traditional S3 Sleep.

Modern Standby is more sensitive to applications requesting wake locks, making powercfg /requests an essential troubleshooting tool.

✅ Step 5: Fix the Root Cause

Once I identified the offending application, the fix was straightforward:

Disable the application from Startup
Close it when not needed
Uninstall it if you never use it

After preventing PCAppStore from running, my laptop finally behaved as expected:

✅ Display turns off after 3 minutes
✅ Laptop enters sleep automatically
✅ Wake-up works normally

🔐 Bonus: Require a PIN After Sleep

After fixing sleep, I noticed another issue:

The laptop woke directly to the desktop instead of asking for my PIN.

To fix that:

Settings → Accounts → Sign-in options

Configure:

If you've been away, when should Windows require you to sign in again?

Choose the shortest available delay (or Immediately, depending on your Windows version).

🛠 Useful Commands

Check what's preventing sleep

powercfg /requests

View supported sleep states

powercfg /a

Generate an energy report

powercfg /energy

Generate a Sleep Study report

powercfg /sleepstudy

Show devices allowed to wake the PC

powercfg /devicequery wake_armed

💡 Lessons Learned

A few things I learned from this experience:

Start with powercfg /requests whenever Windows won't sleep.
msedgewebview2.exe is often just the messenger—you need to identify the parent application.
Modern Standby systems are more susceptible to applications holding wake locks.
Third-party utilities can unintentionally interfere with Windows power management.

Final Thoughts

Initially, I suspected Windows, Dell firmware, or Modern Standby itself.

In reality, a background application was keeping the display awake by holding a WebView2 Video Wake Lock.

If your Windows laptop refuses to sleep despite correct power settings, don't overlook background applications.

A single process may be the only thing standing between you and a properly sleeping system.

Hopefully this saves someone else a few hours of troubleshooting.

Have you encountered a similar issue?

I'd love to hear what prevented sleep on your machine.

Share your experience in the comments!

Windows #Windows11 #PowerManagement #Troubleshooting #WebView2 #PowerShell #Dell #ModernStandby #DeveloperTips

Building a Secure Real-Time Messaging App with .NET 8 and Angular 18

Naimul Karim — Fri, 22 May 2026 04:42:50 +0000

A deep dive into JWT authentication, AES-256-GCM encryption, SignalR, and production security patterns.

Introduction

Real-time messaging apps are everywhere, but most tutorials gloss over the hard parts — the security. In this post I'll walk you through SecureChat, a production-grade messaging app I built with .NET 8 and Angular 18. By the end you'll understand:

How to encrypt messages at rest using AES-256-GCM
How to build a JWT + rotating refresh token authentication flow
How to wire up SignalR with a Redis backplane for real-time delivery
How to implement a silent token refresh interceptor in Angular
How to layer in rate limiting, security headers, and an audit trail

The full source is on GitHub: github.com/naimulkarim/SecureChat

Architecture Overview

Before we dive into code, here's the full picture:

┌─────────────────────────────────────────────┐
│             Angular 18 Frontend             │
│   Auth guard · Chat module · JWT interceptor│
└──────────────────┬──────────────────────────┘
                   │ HTTPS + WSS (TLS 1.3)
┌──────────────────▼──────────────────────────┐
│              .NET 8 Web API                 │
│  Auth API · Messages API · SignalR Hub      │
│  Rate limiting · JWT · Security headers     │
└────┬──────────────────┬───────────────┬─────┘
     │                  │               │
┌────▼────┐     ┌───────▼──────┐  ┌────▼─────┐
│SQL Server│     │    Redis     │  │  Azure   │
│Users/Msgs│     │Cache/Backpl. │  │  Blobs   │
└──────────┘     └──────────────┘  └──────────┘

The key design decisions:

Short-lived JWTs (15 min) limit the blast radius if a token is stolen
Rotating refresh tokens mean a stolen refresh token can only be used once
AES-256-GCM encrypts every message before it hits the database
Redis backplane allows the SignalR hub to scale across multiple API instances
Per-user SignalR groups deliver messages to all of a user's devices simultaneously

Part 1 — The .NET 8 Backend

Setting up `Program.cs`

The entry point wires together every security concern. Let me break it down section by section.

JWT Authentication

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(jwtKey)),
            ValidateIssuer   = true,
            ValidIssuer      = builder.Configuration["Jwt:Issuer"],
            ValidateAudience = true,
            ValidAudience    = builder.Configuration["Jwt:Audience"],
            ValidateLifetime = true,
            ClockSkew        = TimeSpan.Zero   // ← no grace period on expiry
        };

        // SignalR WebSocket upgrades can't send headers,
        // so we read the token from the query string instead
        options.Events = new JwtBearerEvents
        {
            OnMessageReceived = ctx =>
            {
                var token = ctx.Request.Query["access_token"];
                if (!string.IsNullOrEmpty(token) &&
                    ctx.HttpContext.Request.Path.StartsWithSegments("/hubs"))
                    ctx.Token = token;
                return Task.CompletedTask;
            }
        };
    });

The ClockSkew = TimeSpan.Zero is intentional. The default is 5 minutes, meaning a "15-minute" token actually lives for 20 minutes. That's an unnecessary exposure window.

The OnMessageReceived event is needed because WebSocket upgrade requests can't carry Authorization headers — the browser spec doesn't allow it. So the Angular client appends the JWT as a query parameter only for hub connections.

Rate Limiting

builder.Services.AddRateLimiter(opt =>
{
    opt.AddFixedWindowLimiter("message", lim =>
    {
        lim.Window      = TimeSpan.FromMinutes(1);
        lim.PermitLimit = 60;
    });
    opt.AddFixedWindowLimiter("auth", lim =>
    {
        lim.Window      = TimeSpan.FromMinutes(5);
        lim.PermitLimit = 10;   // max 10 login attempts per 5 min
    });
});

Auth endpoints get a stricter limit to slow down brute-force attacks. Message endpoints are generous enough for normal usage but will stop a script flooding the server.

Security Headers

app.Use(async (ctx, next) =>
{
    ctx.Response.Headers.Append("X-Content-Type-Options", "nosniff");
    ctx.Response.Headers.Append("X-Frame-Options",        "DENY");
    ctx.Response.Headers.Append("X-XSS-Protection",       "1; mode=block");
    ctx.Response.Headers.Append("Referrer-Policy",         "no-referrer");
    ctx.Response.Headers.Append("Content-Security-Policy",
        "default-src 'self'; connect-src 'self' wss:");
    await next();
});

These headers are cheap to add and block an entire category of attacks — MIME sniffing, clickjacking, and cross-site scripting.

Authentication Service — JWT + BCrypt + Refresh Tokens

The AuthService handles the full auth lifecycle.

Registration

public async Task<AuthResult> RegisterAsync(RegisterRequest req)
{
    if (await _db.Users.AnyAsync(u => u.Email == req.Email.ToLower()))
        return AuthResult.Fail("Email already registered.");

    var user = new User
    {
        Id           = Guid.NewGuid().ToString(),
        Email        = req.Email.ToLower().Trim(),
        DisplayName  = req.DisplayName.Trim(),
        PasswordHash = BCrypt.Net.BCrypt.HashPassword(req.Password, workFactor: 12),
        CreatedAt    = DateTime.UtcNow,
    };

    _db.Users.Add(user);
    await _db.SaveChangesAsync();
    await _audit.LogAsync("auth.register", user.Id, null);

    return await IssueTokensAsync(user);
}

Work factor 12 for BCrypt means ~250ms to hash a password on modern hardware — fast enough for users, slow enough to make brute-forcing impractical.

JWT Generation

private string GenerateJwt(User user)
{
    var key   = new SymmetricSecurityKey(
        Encoding.UTF8.GetBytes(_config["Jwt:Key"]!));
    var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

    var claims = new[]
    {
        new Claim(ClaimTypes.NameIdentifier, user.Id),
        new Claim(ClaimTypes.Email,          user.Email),
        new Claim(ClaimTypes.Name,           user.DisplayName),
        new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
    };

    var token = new JwtSecurityToken(
        issuer:             _config["Jwt:Issuer"],
        audience:           _config["Jwt:Audience"],
        claims:             claims,
        expires:            DateTime.UtcNow.AddMinutes(15),
        signingCredentials: creds);

    return new JwtSecurityTokenHandler().WriteToken(token);
}

The Jti (JWT ID) claim is a unique identifier for each token. This is what lets you build a token blocklist if you ever need to revoke individual tokens before expiry.

Rotating Refresh Tokens

public async Task<AuthResult> RefreshAsync(string refreshToken)
{
    var stored = await _db.RefreshTokens
        .Include(r => r.User)
        .FirstOrDefaultAsync(r => r.Token == refreshToken && !r.IsRevoked);

    if (stored is null || stored.ExpiresAt < DateTime.UtcNow)
        return AuthResult.Fail("Invalid or expired refresh token.");

    stored.IsRevoked = true;   // ← revoke old token immediately
    await _db.SaveChangesAsync();

    return await IssueTokensAsync(stored.User);   // ← issue fresh pair
}

Rotation means every successful refresh invalidates the old token and issues a new one. If an attacker steals a refresh token and uses it, the legitimate user's next refresh will detect the conflict (token already revoked) and you can force a full re-login.

Encryption Service — AES-256-GCM

This is the most security-critical piece of the backend.

public string Encrypt(string plaintext)
{
    // Fresh 96-bit nonce for every single message
    var nonce = new byte[AesGcm.NonceByteSizes.MaxSize];
    RandomNumberGenerator.Fill(nonce);

    var plaintextBytes = Encoding.UTF8.GetBytes(plaintext);
    var ciphertext     = new byte[plaintextBytes.Length];
    var tag            = new byte[AesGcm.TagByteSizes.MaxSize]; // 128-bit auth tag

    using var aes = new AesGcm(_key, tag.Length);
    aes.Encrypt(nonce, plaintextBytes, ciphertext, tag);

    // Pack: [nonce 12B][tag 16B][ciphertext nB]
    var combined = new byte[nonce.Length + tag.Length + ciphertext.Length];
    Buffer.BlockCopy(nonce,      0, combined, 0,                        nonce.Length);
    Buffer.BlockCopy(tag,        0, combined, nonce.Length,              tag.Length);
    Buffer.BlockCopy(ciphertext, 0, combined, nonce.Length + tag.Length, ciphertext.Length);

    return Convert.ToBase64String(combined);
}

Why AES-256-GCM specifically?

AES-256 — the key length (256 bits) is computationally infeasible to brute-force
GCM mode — provides both confidentiality (encryption) and integrity (the 128-bit authentication tag). If anyone tampers with the ciphertext in the database, decryption throws an exception rather than silently returning garbage
Fresh nonce per message — reusing a nonce with the same key in GCM mode catastrophically breaks security. We use RandomNumberGenerator.Fill (cryptographically secure) for each encryption call

The nonce and tag are packed together with the ciphertext so decryption is self-contained — no separate columns needed.

SignalR Hub

[Authorize]
public class ChatHub : Hub
{
    public override async Task OnConnectedAsync()
    {
        var userId = GetUserId();
        // Each user gets a personal group across all their devices
        await Groups.AddToGroupAsync(Context.ConnectionId, $"user:{userId}");
        await _audit.LogAsync("hub.connected", userId,
            Context.GetHttpContext()?.Connection.RemoteIpAddress?.ToString());
        await base.OnConnectedAsync();
    }

    public async Task SendMessage(SendMessageRequest request)
    {
        if (string.IsNullOrWhiteSpace(request.Content) || request.Content.Length > 4000)
            throw new HubException("Invalid message content.");

        var senderId = GetUserId();
        var saved    = await _messages.SaveAsync(senderId, request);

        // Fan out to every participant's group (covers multi-device)
        foreach (var participantId in saved.ParticipantIds)
        {
            await Clients.Group($"user:{participantId}")
                .SendAsync("ReceiveMessage", saved);
        }
    }

    public async Task SendTyping(string conversationId, bool isTyping)
    {
        var userId       = GetUserId();
        var participants = await _messages.GetParticipantsAsync(conversationId, userId);

        foreach (var participantId in participants.Where(p => p != userId))
        {
            await Clients.Group($"user:{participantId}")
                .SendAsync("TypingIndicator",
                    new { conversationId, userId, isTyping });
        }
    }
}

A few design decisions worth noting:

Personal groups vs connection IDs. We add each connection to user:{userId} instead of tracking individual ConnectionId values. This means if a user has two browser tabs open, both get the message without any extra code. If you used ConnectionId you'd need a lookup table mapping users to connections.

Typing indicators are never persisted. They're pure ephemeral SignalR events — no database write, no message history. They disappear the moment the connection drops.

HubException for client-visible errors. Regular C# exceptions become generic 500-style errors on the client. HubException propagates the message string to the caller, which lets Angular show a human-readable error.

Part 2 — The Angular 18 Frontend

JWT Interceptor with Silent Refresh

This is the piece most tutorials get wrong. The naive approach — refresh on 401, retry — breaks badly when multiple requests expire simultaneously. Our interceptor queues concurrent requests while a refresh is in flight.

let isRefreshing = false;
const refreshSubject = new BehaviorSubject<string | null>(null);

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const auth  = inject(AuthService);
  const token = auth.accessToken();

  const addToken = (r: typeof req, t: string) =>
    r.clone({ setHeaders: { Authorization: `Bearer ${t}` } });

  const request = token ? addToken(req, token) : req;

  return next(request).pipe(
    catchError((err: HttpErrorResponse) => {
      if (err.status !== 401 || req.url.includes('/auth/'))
        return throwError(() => err);

      if (isRefreshing) {
        // Another request is already refreshing — wait for it
        return refreshSubject.pipe(
          filter((t): t is string => t !== null),
          take(1),
          switchMap(t => next(addToken(req, t)))
        );
      }

      isRefreshing = true;
      refreshSubject.next(null);   // signal "refreshing in progress"

      return auth.refresh$().pipe(
        switchMap(newToken => {
          isRefreshing = false;
          refreshSubject.next(newToken);   // unblock queued requests
          return next(addToken(req, newToken));
        }),
        catchError(refreshErr => {
          isRefreshing = false;
          auth.logout();
          return throwError(() => refreshErr);
        })
      );
    })
  );
};

Walk through the flow:

Request goes out with the current JWT
Server returns 401 (token expired)
If no refresh is in progress, start one and set isRefreshing = true
All other requests that 401 in the meantime subscribe to refreshSubject and wait
When refresh succeeds, refreshSubject.next(newToken) unblocks all queued requests
Each queued request clones itself with the new token and retries

Without this queuing, three simultaneous expired requests would trigger three parallel refresh calls, the second and third would fail (token already rotated), and the user would be logged out unexpectedly.

SignalR Chat Service with Angular Signals

@Injectable({ providedIn: 'root' })
export class ChatService {
  // Reactive state using Angular 18 signals
  messages      = signal<Message[]>([]);
  conversations = signal<Conversation[]>([]);
  typingUsers   = signal<TypingIndicator[]>([]);
  connected     = signal(false);

  // Derived state — no manual subscription management
  unreadCount = computed(() =>
    this.conversations().reduce((sum, c) => sum + c.unreadCount, 0)
  );

  async connect(): Promise<void> {
    this.hub = new signalR.HubConnectionBuilder()
      .withUrl(`${environment.apiUrl}/hubs/chat`, {
        accessTokenFactory: () => this.auth.accessToken() ?? '',
        transport: signalR.HttpTransportType.WebSockets,
        skipNegotiation: true,
      })
      .withAutomaticReconnect([0, 2000, 5000, 10000, 30000])
      .build();

    this.hub.on('ReceiveMessage', (msg: Message) => {
      this.messages.update(msgs => [...msgs, msg]);
      this.conversations.update(convs =>
        convs.map(c =>
          c.id === msg.conversationId
            ? { ...c, lastMessage: msg, unreadCount: c.unreadCount + 1 }
            : c
        )
      );
    });

    // ...
    await this.hub.start();
    this.connected.set(true);
  }
}

accessTokenFactory is a function, not a value. SignalR calls it on every reconnect attempt, so it will always pick up the freshest token (including any that were silently refreshed by the interceptor).

withAutomaticReconnect([0, 2000, 5000, 10000, 30000]) defines a custom backoff schedule — immediate retry, then 2s, 5s, 10s, 30s. After exhausting this list SignalR stops retrying, which lets you show a "connection lost" UI rather than hammering the server forever.

Using Angular signals instead of RxJS BehaviorSubject keeps the state management simple — components read chatService.messages() directly in their templates and Angular handles change detection automatically.

Part 3 — Security Checklist

Here's every security mechanism in the app and why it's there:

Threat	Mitigation
Password database breach	BCrypt, work factor 12
Token theft	JWT expiry 15 min, `ClockSkew = Zero`
Refresh token theft	Server-side rotation — stolen token is single-use
Eavesdropping in transit	HTTPS + WSS enforced, TLS 1.3
Database breach (messages)	AES-256-GCM at rest
GCM nonce reuse	`RandomNumberGenerator.Fill` per message
Message tampering	GCM authentication tag — tampered ciphertext throws
Brute-force login	Rate limit: 10 attempts / 5 min
Message flooding	Rate limit: 60 messages / min
Clickjacking	`X-Frame-Options: DENY`
MIME sniffing	`X-Content-Type-Options: nosniff`
Unauthorized hub access	`[Authorize]` attribute, JWT validated on upgrade
Hub conversation access	Server-side participant check before join/deliver
XSS	`Content-Security-Policy: default-src 'self'`
Forensics / incident response	Append-only audit log on every auth event

Part 4 — Running It Locally

# Clone
git clone https://github.com/naimulkarim/SecureChat.git
cd SecureChat

# Generate secrets
openssl rand -base64 32   # → Encryption:Key
openssl rand -base64 64   # → Jwt:Key

# Backend
cd SecureChat.API
# Add secrets to appsettings.Development.json (never commit this file)
dotnet ef database update
dotnet run

# Frontend (new terminal)
cd ../secure-chat-ui
npm install
ng serve

Navigate to https://localhost:4200.

What's Next

There are a few things I'd add before calling this truly production-ready:

Key management — move the AES key and JWT secret out of appsettings.json and into Azure Key Vault (or AWS Secrets Manager). The current setup is fine for local dev but secrets should never live in a config file in a real deployment.

Client-side encryption — the current model encrypts at the server before writing to the DB. True end-to-end encryption (where even the server can't read messages) requires encrypting on the client with the recipient's public key. This would involve WebCrypto API on the Angular side and a public key exchange flow.

Message deletion / expiry — a GDPR-friendly implementation needs the ability to delete or expire messages, with the encrypted blobs actually removed from storage.

Push notifications — when the user isn't connected to the hub, they need push notifications. Web Push API + a service worker can deliver notifications even when the tab is closed.

Conclusion

The patterns in this post — short-lived JWTs with rotating refresh tokens, AES-GCM encryption at rest, request queuing during token refresh, and per-user SignalR groups — are the foundations of any serious real-time app. None of them are particularly exotic, but getting all the details right (nonce freshness, clock skew, refresh token rotation, concurrent refresh queuing) makes the difference between a demo and something you'd trust with real user data.

The full source is at github.com/naimulkarim/SecureChat. PRs and issues welcome.

Tags: dotnet angular security signalr webdev csharp typescript

🔐 SecretVault Internals: How the Code Is Actually Implemented

Naimul Karim — Tue, 19 May 2026 02:46:31 +0000

This is the implementation companion to the SecretVault introduction post. Where that post showed you what SecretVault does, this one shows you how it's built — every class, every design decision, and why things are structured the way they are.

Project Structure at a Glance

SecretVault/
├── src/
│   ├── SecretVault.Core/                  # Abstractions, caching, chaining
│   │   ├── ISecretManager.cs
│   │   ├── ISecretRotationManager.cs
│   │   ├── Models.cs
│   │   ├── CachedSecretManager.cs
│   │   └── ChainedSecretManager.cs
│   ├── SecretVault.Aws/                   # AWS Secrets Manager
│   │   └── AwsSecretManager.cs
│   ├── SecretVault.Azure/                 # Azure Key Vault
│   │   └── AzureKeyVaultSecretManager.cs
│   ├── SecretVault.HashiCorp/             # HashiCorp Vault KV v2
│   │   └── HashiCorpVaultSecretManager.cs
│   ├── SecretVault.Gcp/                   # GCP Secret Manager
│   │   └── GcpSecretManager.cs
│   └── SecretVault.Extensions.Hosting/   # ASP.NET Core integration
│       ├── SecretVaultServiceExtensions.cs
│       └── SecretVaultHealthCheck.cs
└── tests/
    └── SecretVault.Core.Tests/
        └── CachedAndChainedTests.cs

The golden rule: if a class only references ISecretManager → it goes in Core. If it references a provider SDK (AWS, Azure, etc.) → it goes in that provider's project.

Part 1 — The Core Abstractions

`ISecretManager` — The Unified Interface

This is the only type your application code ever depends on:

namespace SecretVault.Core;

public interface ISecretManager
{
    // On-demand runtime fetching
    Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default);
    Task<T?> GetSecretAsync<T>(string secretName, CancellationToken ct = default);
    Task SetSecretAsync(string secretName, string value, CancellationToken ct = default);
    Task DeleteSecretAsync(string secretName, CancellationToken ct = default);

    // Bulk fetch — useful at startup to warm secrets
    Task<IReadOnlyDictionary<string, string?>> GetSecretsAsync(
        IEnumerable<string> secretNames, CancellationToken ct = default);
}

Why string? and not string? Returning null instead of throwing when a secret doesn't exist is a deliberate choice — it lets callers decide whether a missing secret is an error or an expected condition without forcing a try/catch everywhere.

Why Task<T?> GetSecretAsync<T>? Many secrets are stored as JSON objects (e.g. a database config with host, port, and password together). The generic overload deserializes directly into your type so you don't have to JsonSerializer.Deserialize manually on every call.

`ISecretRotationManager` — Rotation on Top

Rotation is an optional capability — not every use case needs it. So instead of bloating ISecretManager, we extend it:

public interface ISecretRotationManager : ISecretManager
{
    Task<SecretRotationResult> RotateSecretAsync(
        string secretName,
        string newValue,
        TimeSpan? gracePeriod = null,
        CancellationToken ct = default);

    Task<IReadOnlyList<SecretVersion>> ListVersionsAsync(
        string secretName, CancellationToken ct = default);

    Task<string?> GetSecretVersionAsync(
        string secretName, string version, CancellationToken ct = default);
}

All four provider implementations (AwsSecretManager, AzureKeyVaultSecretManager, etc.) implement ISecretRotationManager — which means they also satisfy ISecretManager. You can inject either interface depending on what you need.

The return types:

// Returned from RotateSecretAsync — tells you what happened
public record SecretRotationResult(
    string SecretName,
    string NewVersion,
    string? PreviousVersion,
    DateTimeOffset RotatedAt,
    DateTimeOffset? GracePeriodEndsAt  // null if no grace period requested
);

// One entry from ListVersionsAsync
public record SecretVersion(
    string Version,
    DateTimeOffset CreatedAt,
    bool IsCurrent,
    string? Status
);

C# records are used here because these are pure data carriers — immutable, with built-in equality and ToString(). No behaviour, no setters.

The Exception Hierarchy

Provider SDKs throw completely different exceptions — AmazonServiceException, RequestFailedException, RpcException. Your application shouldn't need to know which one it got. We normalize them:

// Base — all SecretVault errors derive from this
public class SecretVaultException : Exception { ... }

// Secret doesn't exist in the provider
public class SecretNotFoundException : SecretVaultException
{
    public string SecretName { get; }  // carry the name so callers can log it
}

// IAM / RBAC permissions failure
public class SecretAccessDeniedException : SecretVaultException { ... }

// Network outage or provider down
public class SecretProviderUnavailableException : SecretVaultException { ... }

Each provider catches its own SDK exception types and re-throws as the appropriate SecretVaultException. Your application catches one hierarchy regardless of which provider is running:

catch (SecretNotFoundException ex)    { /* missing secret */ }
catch (SecretAccessDeniedException)   { /* permissions issue */ }
catch (SecretProviderUnavailableException) { /* outage */ }

Part 2 — The AWS Implementation

AwsSecretManager implements ISecretRotationManager (which includes all of ISecretManager):

public class AwsSecretManager : ISecretRotationManager
{
    private readonly IAmazonSecretsManager _client;
    private readonly ILogger<AwsSecretManager> _logger;

    public AwsSecretManager(IAmazonSecretsManager client, ILogger<AwsSecretManager> logger)
    {
        _client = client;
        _logger = logger;
    }

IAmazonSecretsManager not AmazonSecretsManagerClient — we take the interface, not the concrete class. This makes the provider testable via mocking without hitting real AWS.

GetSecretAsync

public async Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default)
{
    try
    {
        _logger.LogDebug("Fetching secret '{Name}' from AWS Secrets Manager", secretName);

        var response = await _client.GetSecretValueAsync(new GetSecretValueRequest
        {
            SecretId = secretName
        }, ct);

        // AWS can return either a string OR binary — handle both
        return response.SecretString
            ?? Convert.ToBase64String(response.SecretBinary.ToArray());
    }
    catch (ResourceNotFoundException)
    {
        throw new SecretNotFoundException(secretName);   // normalize
    }
    catch (AmazonServiceException ex) when (ex.ErrorCode == "AccessDeniedException")
    {
        throw new SecretAccessDeniedException(secretName, ex);  // normalize
    }
    catch (Exception ex)
    {
        throw new SecretProviderUnavailableException("AWS Secrets Manager", ex); // normalize
    }
}

Exception filters (when) are used to catch only the specific AWS error codes we care about, letting other AmazonServiceException subtypes fall through to the general handler.

SetSecretAsync — Create or Update

public async Task SetSecretAsync(string secretName, string value, CancellationToken ct = default)
{
    try
    {
        await _client.PutSecretValueAsync(new PutSecretValueRequest
        {
            SecretId = secretName,
            SecretString = value
        }, ct);
    }
    catch (ResourceNotFoundException)
    {
        // Secret doesn't exist yet — create it first
        await _client.CreateSecretAsync(new CreateSecretRequest
        {
            Name = secretName,
            SecretString = value
        }, ct);
    }
}

AWS PutSecretValue requires the secret to already exist. We catch ResourceNotFoundException and create it automatically so callers don't have to think about whether a secret is new or existing.

RotateSecretAsync

public async Task<SecretRotationResult> RotateSecretAsync(
    string secretName, string newValue, TimeSpan? gracePeriod = null, CancellationToken ct = default)
{
    // 1. Read the current version ID before rotating
    var current = await _client.DescribeSecretAsync(
        new DescribeSecretRequest { SecretId = secretName }, ct);
    var previousVersion = current.VersionIdsToStages?.Keys.FirstOrDefault();

    // 2. Write the new value, explicitly marking it as current
    await _client.PutSecretValueAsync(new PutSecretValueRequest
    {
        SecretId = secretName,
        SecretString = newValue,
        VersionStages = ["AWSCURRENT"]
    }, ct);

    // 3. Read back the new version ID
    var describe = await _client.DescribeSecretAsync(
        new DescribeSecretRequest { SecretId = secretName }, ct);
    var newVersion = describe.VersionIdsToStages?.Keys.FirstOrDefault() ?? "unknown";

    var rotatedAt = DateTimeOffset.UtcNow;

    return new SecretRotationResult(
        SecretName: secretName,
        NewVersion: newVersion,
        PreviousVersion: previousVersion,
        RotatedAt: rotatedAt,
        GracePeriodEndsAt: gracePeriod.HasValue ? rotatedAt.Add(gracePeriod.Value) : null
    );
}

The AWSCURRENT stage label is how AWS tracks which version is active. The old version automatically moves to AWSPREVIOUS — staying accessible during the grace period before it expires.

Part 3 — CachedSecretManager (The Decorator Pattern)

CachedSecretManager is a decorator — it wraps any ISecretManager and adds caching without modifying the wrapped class:

Your App → CachedSecretManager → AwsSecretManager → AWS API

public class CachedSecretManager : ISecretManager
{
    private readonly ISecretManager _inner;   // the real provider
    private readonly IMemoryCache _cache;
    private readonly ILogger<CachedSecretManager> _logger;
    private readonly CachedSecretManagerOptions _options;

    public CachedSecretManager(
        ISecretManager inner,
        IMemoryCache cache,
        ILogger<CachedSecretManager> logger,
        CachedSecretManagerOptions? options = null)
    {
        _inner = inner;
        _cache = cache;
        _logger = logger;
        _options = options ?? new CachedSecretManagerOptions(); // defaults to 5 min
    }

GetSecretAsync — Cache-Aside Pattern

public async Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default)
{
    var cacheKey = CacheKey(secretName);  // "secretvault:my-secret"

    // 1. Check cache first
    if (_cache.TryGetValue(cacheKey, out string? cached))
    {
        _logger.LogDebug("Cache hit for secret '{SecretName}'", secretName);
        return cached;
    }

    // 2. Cache miss — fetch from the real provider
    _logger.LogDebug("Cache miss for '{SecretName}', fetching from provider", secretName);
    var value = await _inner.GetSecretAsync(secretName, ct);

    // 3. Store in cache (only if we got a value)
    if (value is not null)
    {
        _cache.Set(cacheKey, value, new MemoryCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = _options.AbsoluteExpiration,
            SlidingExpiration = _options.SlidingExpiration
        });
    }

    return value;
}

This is the classic cache-aside (lazy loading) pattern: populate the cache on demand, not upfront.

Write-Through Cache Invalidation

public async Task SetSecretAsync(string secretName, string value, CancellationToken ct = default)
{
    await _inner.SetSecretAsync(secretName, value, ct);  // write to provider first
    _cache.Remove(CacheKey(secretName));                 // then invalidate cache
}

Why invalidate instead of update? Updating the cache after a write seems logical but introduces a race condition — between the write and the cache update, another thread could read the old value. Invalidating forces the next read to fetch fresh from the provider, which is always safe.

Bulk Fetch — Partial Cache Hits

public async Task<IReadOnlyDictionary<string, string?>> GetSecretsAsync(
    IEnumerable<string> secretNames, CancellationToken ct = default)
{
    var result = new Dictionary<string, string?>();
    var missing = new List<string>();   // secrets not in cache

    // 1. Check cache for each name
    foreach (var name in secretNames)
    {
        if (_cache.TryGetValue(CacheKey(name), out string? cached))
            result[name] = cached;     // cache hit
        else
            missing.Add(name);         // needs fetching
    }

    // 2. Fetch only the ones that weren't cached
    if (missing.Count > 0)
    {
        var fetched = await _inner.GetSecretsAsync(missing, ct);
        foreach (var (key, value) in fetched)
        {
            result[key] = value;
            if (value is not null)
                _cache.Set(CacheKey(key), value, _options.AbsoluteExpiration);
        }
    }

    return result;
}

If you request 10 secrets and 7 are cached, only 3 API calls go to the provider. The result dictionary combines both.

The Options Class

public class CachedSecretManagerOptions
{
    // Expires exactly N minutes after caching, regardless of usage
    public TimeSpan AbsoluteExpiration { get; set; } = TimeSpan.FromMinutes(5);

    // Resets the timer on every access — null means disabled
    public TimeSpan? SlidingExpiration { get; set; }
}

You can combine both: sliding keeps frequently-accessed secrets warm, while absolute prevents them from living in cache indefinitely even if constantly hit.

Part 4 — ChainedSecretManager (The Chain of Responsibility Pattern)

public class ChainedSecretManager : ISecretManager
{
    private readonly IReadOnlyList<ISecretManager> _managers;

    public ChainedSecretManager(
        IEnumerable<ISecretManager> managers,
        ILogger<ChainedSecretManager> logger)
    {
        _managers = managers.ToList();
        if (_managers.Count == 0)
            throw new ArgumentException("At least one ISecretManager must be provided.");
    }

    public async Task<string?> GetSecretAsync(string secretName, CancellationToken ct = default)
    {
        foreach (var manager in _managers)
        {
            try
            {
                var value = await manager.GetSecretAsync(secretName, ct);
                if (value is not null)
                {
                    _logger.LogDebug("Secret '{Name}' found in {Provider}",
                        secretName, manager.GetType().Name);
                    return value;
                }
            }
            catch (SecretNotFoundException)
            {
                // Not found here — try next provider
                _logger.LogDebug("Secret '{Name}' not found in {Provider}, trying next",
                    secretName, manager.GetType().Name);
            }
            catch (Exception ex)
            {
                // Provider error — log and try next, don't crash
                _logger.LogWarning(ex, "Error fetching '{Name}' from {Provider}, trying next",
                    secretName, manager.GetType().Name);
            }
        }

        // Exhausted all providers
        throw new SecretNotFoundException(secretName);
    }

    // Writes always go to the PRIMARY (first) provider only
    public Task SetSecretAsync(string secretName, string value, CancellationToken ct = default)
        => _managers[0].SetSecretAsync(secretName, value, ct);
}

Key design decisions:

SecretNotFoundException from a provider means "not here, try next" — it's expected and swallowed
Any other exception (network error, auth failure) is logged as a warning and the chain continues — one broken provider doesn't block fallbacks
Writes go to _managers[0] (primary) only — writing to all providers would create sync problems

Part 5 — ASP.NET Core Integration

`AddSecretVault` — The DI Extension Method

public static IServiceCollection AddSecretVault(
    this IServiceCollection services,
    ISecretManager manager,
    Action<CachedSecretManagerOptions>? configureCaching = null)
{
    if (configureCaching is not null)
    {
        services.AddMemoryCache();

        // Register the CachedSecretManager as a concrete singleton
        services.AddSingleton(sp =>
        {
            var options = new CachedSecretManagerOptions();
            configureCaching(options);   // apply caller's configuration
            var cache = sp.GetRequiredService<IMemoryCache>();
            var logger = sp.GetRequiredService<ILogger<CachedSecretManager>>();
            return new CachedSecretManager(manager, cache, logger, options);
        });

        // Map ISecretManager → CachedSecretManager
        // Any class that injects ISecretManager gets the cached version
        services.AddSingleton<ISecretManager>(
            sp => sp.GetRequiredService<CachedSecretManager>());
    }
    else
    {
        // No caching — register the raw provider directly
        services.AddSingleton<ISecretManager>(manager);
    }

    return services;
}

The key line is services.AddSingleton<ISecretManager>(sp => sp.GetRequiredService<CachedSecretManager>()). This creates an alias in the DI container — ISecretManager resolves to CachedSecretManager, which itself wraps AwsSecretManager. Your services inject ISecretManager and silently get three layers of behavior.

`IConfiguration` Integration

// The source tells the config system how to build our provider
public class SecretVaultConfigurationSource : IConfigurationSource
{
    private readonly ISecretManager _manager;
    private readonly IEnumerable<string> _secretNames;

    public IConfigurationProvider Build(IConfigurationBuilder builder)
        => new SecretVaultConfigurationProvider(_manager, _secretNames);
}

// The provider does the actual loading
public class SecretVaultConfigurationProvider : ConfigurationProvider
{
    public override void Load()
    {
        // Fetch all secrets synchronously at startup
        var secrets = _manager.GetSecretsAsync(_secretNames).GetAwaiter().GetResult();

        // Store in the Data dictionary — this is what IConfiguration reads from
        Data = secrets
            .Where(kvp => kvp.Value is not null)
            .ToDictionary(kvp => kvp.Key, kvp => kvp.Value!);
    }
}

Why .GetAwaiter().GetResult() instead of await? IConfigurationProvider.Load() is synchronous — it's called during host startup before the async pipeline is running. This is one of the few legitimate places to block on async code in .NET.

Health Check

public class SecretVaultHealthCheck : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken ct = default)
    {
        try
        {
            await _manager.GetSecretAsync("__healthcheck__", ct);
            return HealthCheckResult.Healthy("Secret provider is reachable.");
        }
        catch (SecretNotFoundException)
        {
            // Provider is reachable — the probe secret just doesn't exist, which is fine
            return HealthCheckResult.Healthy("Secret provider is reachable.");
        }
        catch (SecretProviderUnavailableException ex)
        {
            return HealthCheckResult.Unhealthy("Secret provider is unavailable.", ex);
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Degraded("Unexpected error.", ex);
        }
    }
}

The __healthcheck__ probe secret almost certainly doesn't exist — and that's intentional. SecretNotFoundException proves the provider is reachable and responding. Only SecretProviderUnavailableException (network issue, auth failure) marks the check as unhealthy.

Part 6 — Tests

public class CachedSecretManagerTests
{
    private readonly ISecretManager _inner = Substitute.For<ISecretManager>();
    private readonly IMemoryCache _cache = new MemoryCache(new MemoryCacheOptions());
    private readonly CachedSecretManager _sut;

    [Fact]
    public async Task GetSecretAsync_SecondCall_ReturnsCachedValue()
    {
        _inner.GetSecretAsync("my-secret", default).Returns("super-secret");

        await _sut.GetSecretAsync("my-secret");  // first call — hits inner
        await _sut.GetSecretAsync("my-secret");  // second call — from cache

        // Inner was only called ONCE despite two GetSecretAsync calls
        await _inner.Received(1).GetSecretAsync("my-secret", default);
    }

    [Fact]
    public async Task SetSecretAsync_InvalidatesCache()
    {
        _inner.GetSecretAsync("my-secret", default).Returns("old-value", "new-value");

        await _sut.GetSecretAsync("my-secret");         // caches "old-value"
        await _sut.SetSecretAsync("my-secret", "new-value"); // invalidates cache
        var result = await _sut.GetSecretAsync("my-secret"); // re-fetches "new-value"

        result.Should().Be("new-value");
        await _inner.Received(2).GetSecretAsync("my-secret", default);
    }
}

public class ChainedSecretManagerTests
{
    [Fact]
    public async Task GetSecretAsync_FallsBackToSecondary_WhenPrimaryThrowsNotFound()
    {
        _primary.GetSecretAsync("key", default)
            .Throws(new SecretNotFoundException("key"));
        _fallback.GetSecretAsync("key", default).Returns("from-fallback");

        var result = await _sut.GetSecretAsync("key");

        result.Should().Be("from-fallback");
    }
}

NSubstitute is used for mocking — Substitute.For<ISecretManager>() creates a fake implementation that returns configured values. FluentAssertions makes assertions read like English. Real MemoryCache is used instead of a mock because testing with the actual cache catches real caching bugs that a mock would hide.

Part 7 — GitHub Actions CI/CD

CI (`ci.yml`) — Every push and PR

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x'
      - run: dotnet restore SecretVault.sln
      - run: dotnet build SecretVault.sln --configuration Release --no-restore
      - run: dotnet test SecretVault.sln --configuration Release --no-build

Publish (`publish.yml`) — Tag a version, ship everything

on:
  push:
    tags:
      - 'v*.*.*'   # v1.0.0, v1.2.3, etc.

steps:
  - name: Extract version from tag
    id: version
    run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
    # v1.0.0 → 1.0.0 (strips the "v" prefix for NuGet)

  - name: Pack all packages
    run: |
      dotnet pack src/SecretVault.Core/SecretVault.Core.csproj \
        --configuration Release \
        /p:Version=${{ steps.version.outputs.VERSION }} \
        --output ./nupkgs
      # ... repeated for all 6 packages

  - name: Publish to NuGet
    run: |
      dotnet nuget push ./nupkgs/*.nupkg \
        --api-key ${{ secrets.NUGET_API_KEY }} \
        --source https://api.nuget.org/v3/index.json \
        --skip-duplicate

${GITHUB_REF_NAME#v} is a bash parameter expansion — it strips the v prefix from the tag name so v1.0.0 becomes 1.0.0, which is what NuGet expects for version numbers.

--skip-duplicate prevents the pipeline from failing if a package version was already published (e.g. if you re-run the workflow).

To release:

git tag v1.0.0
git push origin v1.0.0
# GitHub Actions handles the rest automatically

Summary — Design Patterns Used

Pattern	Where	Why
Interface segregation	`ISecretManager` + `ISecretRotationManager`	Rotation is optional — don't force it on basic consumers
Decorator	`CachedSecretManager`	Add caching without modifying providers
Chain of responsibility	`ChainedSecretManager`	Fallback across providers without coupling
Factory via DI	`AddSecretVault` extension	Compose the full object graph in one place
Normalized exceptions	Per-provider catch/rethrow	Shield callers from SDK-specific error types
Cache-aside	`CachedSecretManager.GetSecretAsync`	Lazy populate, invalidate on write
Configuration provider	`SecretVaultConfigurationSource`	Plug into the standard .NET config pipeline

View the full source on GitHub · NuGet Packages

I Built an AI-Powered Dead Code Detector for VS Code

Naimul Karim — Tue, 12 May 2026 03:10:26 +0000

We've all been there. You're reading through a codebase and you spot it — a feature flag that's been set to false for two years, a function exported from a module that nothing ever imports, a block of logic sitting underneath a return statement that will never, ever run.

ESLint catches unused variables. TypeScript catches type mismatches. But dead business logic? That's a different beast — and that's what I built this extension to hunt.

What Is "Dead Code" Really?

Most linters think dead code = unused variable. But in production codebases the real offenders are:

1. Unreachable Logic
Code that can never execute — not because of a syntax issue, but because of your business logic:

function calculateDiscount(price: number, userType: string): number {
  if (userType === "admin") {
    return price * 0;
  }
  return price * 0.9;

  // Never reached — the return above always fires
  const bonus = price * 0.05;
  console.log("Applying bonus:", bonus);
  return price - bonus;
}

2. Unused APIs and Functions
Exported functions nobody calls. Classes defined and never instantiated. Entire modules orphaned after a refactor:

// Exported but nothing in the codebase ever calls this
export class OldReportGenerator {
  generate(data: any[]) {
    return data.map((d) => JSON.stringify(d)).join("\n");
  }
  exportToCsv(data: any[]) {
    return data.join(",");
  }
}

3. Obsolete Feature Flags
The slowest-burning dead code. A flag gets hardcoded, the ticket gets closed, and the condition guards code that either always runs or never runs:

const FEATURE_DARK_MODE = false;    // 🚩 Has been false for 18 months
const USE_NEW_CHECKOUT = true;      // 🚩 Always true — the else branch is dead

if (FEATURE_DARK_MODE) {
  applyDarkTheme(); //  Never runs
}

if (USE_NEW_CHECKOUT) {
  showNewCheckout();
} else {
  showLegacyCheckout(); //  Never runs
  trackLegacyCheckoutEvent();
}

Traditional static analysis tools struggle with these because they require understanding intent, not just syntax.

The Solution: AI-Powered Analysis

I built Dead Code Detector — a VS Code extension that sends your file to Claude (via the Anthropic API) with a carefully engineered prompt, gets back a structured JSON response, and renders the results as both inline diagnostics and a filterable results panel.

GitHub: github.com/naimulkarim/dead-code-detector

Here's what it looks like in action:

🔴 Inline squiggles in the editor (appears in your Problems panel)
📊 A results panel that opens beside your file with filtering, severity badges, and jump-to-line

How It Works

The Prompt Engineering

The heart of the extension is the system prompt in src/analyzer.ts. Getting an LLM to return reliable, parseable structured data requires being very explicit:

const SYSTEM_PROMPT = `You are an expert static analysis tool specializing in dead code detection. 
Analyze the provided source code and identify:

1. **Unreachable Business Logic** — code after unconditional returns, inside impossible 
   conditions (e.g. if (false), if (1 === 2)), catch blocks that swallow everything, etc.

2. **Unused APIs / Functions** — exported or defined functions/classes/variables that appear 
   to never be called or referenced within the file.

3. **Obsolete Feature Flags** — boolean constants or config checks that are hardcoded to 
   true/false, e.g. const FEATURE_X = false used in conditions.

Respond ONLY with a JSON array (no markdown, no preamble). Each item must have:
{
  "category": "unreachable-logic" | "unused-api" | "obsolete-feature-flag" | "dead-code",
  "message": "Short one-line summary (< 80 chars)",
  "explanation": "2-3 sentences explaining why this is dead/obsolete code",
  "suggestion": "What to do — remove, refactor, or clean up",
  "line": <integer line number where the issue starts, or null>,
  "severity": "high" | "medium" | "low"
}

Return [] if no issues found.`;

Key decisions here:

"Respond ONLY with a JSON array" — no preamble, no markdown fences in the model's thinking. We strip any stray fences client-side as a safety net.
Explicit schema — defining every field prevents the model from inventing its own structure.
"Return [] if no issues found" — so a clean file doesn't produce a parse error.

Calling the API

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "anthropic-version": "2023-06-01",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 2048,
    system: SYSTEM_PROMPT,
    messages: [{ role: "user", content: userMessage }],
  }),
});

const data = await response.json();
const text = data.content
  .filter((b) => b.type === "text")
  .map((b) => b.text)
  .join("");

// Strip possible markdown fences before parsing
const clean = text.replace(/```
{% endraw %}
json|
{% raw %}
```/g, "").trim();
const results = JSON.parse(clean);

We cap the file at 12,000 characters before sending — enough for most real-world files without burning tokens unnecessarily.

Turning Results into VS Code Diagnostics

Once we have the JSON array back, we map each issue to a vscode.Diagnostic so it shows up inline in the editor and the Problems panel:

function applyDiagnostics(doc: vscode.TextDocument, results: DeadCodeResult[]) {
  const diagnostics = results.map((result) => {
    const line = Math.max(0, (result.line ?? 1) - 1);
    const range = doc.lineAt(Math.min(line, doc.lineCount - 1)).range;
    const diag = new vscode.Diagnostic(
      range,
      `[${result.category}] ${result.message}`,
      vscode.DiagnosticSeverity.Warning
    );
    diag.source = "Dead Code AI";
    diag.code = result.category;
    return diag;
  });

  diagnosticCollection.set(doc.uri, diagnostics);
}

The Results Panel

Results also open in a Webview panel beside your editor. It's filterable by category and sortable by severity, with a Jump to Line button on each card that snaps the cursor to the exact location in your file.

// The webview posts a message back to the extension host
ResultsPanel.currentPanel.webview.onDidReceiveMessage(async (msg) => {
  if (msg.command === "jumpTo") {
    const editor = vscode.window.visibleTextEditors[0];
    const pos = new vscode.Position(Math.max(0, msg.line - 1), 0);
    editor.selection = new vscode.Selection(pos, pos);
    editor.revealRange(
      new vscode.Range(pos, pos),
      vscode.TextEditorRevealType.InCenter
    );
  }
});

Features

✅ Detects unreachable logic, unused APIs, and obsolete feature flags
✅ Works on JS, TS, JSX, TSX, and Python
✅ Inline squiggles in the editor via VS Code's Diagnostics API
✅ Filterable results panel with severity badges and jump-to-line
✅ Workspace-wide scan (with a confirmation prompt for large repos)
✅ Configurable severity level (error / warning / information / hint)
✅ Toggle individual checks on/off in settings
✅ Works via environment variable (ANTHROPIC_API_KEY) or Settings UI

Installation & Setup

Prerequisites

Node.js v18+
VS Code 1.85+
An Anthropic API key — get one at console.anthropic.com

From GitHub

# Clone the repo
git clone https://github.com/naimulkarim/dead-code-detector.git
cd dead-code-detector

# Install dependencies
npm install

# Open in VS Code
code .

Then press F5 — this opens a new Extension Development Host window with the extension loaded.

Add Your API Key

Option A — Settings UI (recommended):

Open Settings (Cmd+, on Mac / Ctrl+, on Windows)
Search for Dead Code
Paste your key into Dead Code Detector: Anthropic Api Key

Option B — Environment variable:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Usage

Action	Shortcut / How
Analyze current file	`Cmd+Shift+D` / `Ctrl+Shift+D`
Analyze current file	Right-click in editor → Dead Code: Analyze Current File
Analyze entire workspace	Command Palette → Dead Code: Analyze Entire Workspace
Clear diagnostics	Command Palette → Dead Code: Clear All Diagnostics

Test It Immediately

The repo includes sample-test.ts — a file pre-loaded with intentional dead code of all three types. Open it and hit Cmd+Shift+D to see the extension in action right away.

Configuration

// .vscode/settings.json or user settings
{
  "deadCode.anthropicApiKey": "sk-ant-...",
  "deadCode.severity": "warning",
  "deadCode.checks": {
    "unreachableLogic": true,
    "unusedApis": true,
    "obsoleteFeatureFlags": true
  }
}

Architecture Overview

User triggers Cmd+Shift+D
        ↓
extension.ts
  → reads active document text
  → reads enabled checks from config
        ↓
analyzer.ts
  → builds user prompt with language + filename + code
  → POST /v1/messages → Claude Sonnet
  → strips markdown fences, JSON.parse()
  → returns DeadCodeResult[]
        ↓
extension.ts
  → vscode.DiagnosticCollection.set() → squiggles in editor
        ↓
resultsPanel.ts
  → Webview HTML panel with filter buttons + severity cards
  → postMessage() → jump-to-line on click

What's Next

A few things I want to add:

[ ] Quick Fix actions — a code action that lets you delete the dead code with one click
[ ] Sidebar tree view — persistent panel showing all issues across the workspace
[ ] Git blame integration — show who added the dead code and when
[ ] Caching — skip re-analyzing files that haven't changed since last scan
[ ] More languages — Go, Ruby, Rust

PRs and issues are very welcome at github.com/naimulkarim/dead-code-detector.

Building a Multi-Channel Notification Service in .NET 8

Naimul Karim — Fri, 08 May 2026 20:56:20 +0000

TL;DR — This post walks through building a complete notification service in .NET 8 that delivers messages across Email, SMS, and Push channels using a message queue, Scriban template engine, per-channel rate limiting, and parallel fan-out dispatch. Full source code on GitHub at the end.

Why Build a Notification Service?

Every production application eventually needs to notify its users — a welcome email, a password reset SMS, a push alert when their order ships. The naive approach is to call SendGrid inline in your controller. That works until:

Your SMTP provider is slow and your API response time balloons
You hit a Twilio rate limit and lose messages silently
You need to add a new channel and it requires touching 12 files
A downstream outage takes your whole API down with it

A proper notification service decouples delivery from your application logic. Requests are queued instantly, workers deliver asynchronously, and channels are isolated — one failing provider never blocks another.

Architecture Overview

Producers (API / Scheduled Jobs / Webhooks)
                    │
                    ▼
         ┌─────────────────┐
         │  Message Queue  │   RabbitMQ (topic exchange)
         └────────┬────────┘
                  │
    ┌─────────────▼──────────────────┐
    │          Dispatcher            │
    │  ┌──────────────────────────┐  │
    │  │    Template Service      │  │   Scriban engine + cache
    │  └──────────────────────────┘  │
    │  ┌──────────────────────────┐  │
    │  │      Rate Limiter        │  │   Sliding window per recipient
    │  └──────────────────────────┘  │
    └──────┬──────────┬──────────┬───┘
           │          │          │
    ┌──────▼──┐  ┌────▼───┐  ┌──▼──────┐
    │  Email  │  │  SMS   │  │  Push   │   Channel Workers
    │ Worker  │  │ Worker │  │ Worker  │   (IHostedService)
    └──────┬──┘  └────┬───┘  └──┬──────┘
           │          │          │
    ┌──────▼──┐  ┌────▼───┐  ┌──▼──────┐
    │  SMTP   │  │Twilio  │  │Firebase │   External Providers
    │ MailKit │  │  API   │  │  FCM    │
    └─────────┘  └────────┘  └─────────┘
                    │
         ┌──────────▼──────────┐
         │    Observability    │   OpenTelemetry + Serilog + Prometheus
         └─────────────────────┘

Data flow in plain English

Your API receives POST /api/notifications and immediately publishes to RabbitMQ — the HTTP response is instant
RabbitMqConsumer (a BackgroundService) picks up the message
The Dispatcher resolves the recipient, checks the rate limiter, renders the template, and fans out to all requested channels in parallel
Each channel worker calls its external provider (MailKit, Twilio, FCM)
Failures nack the message — RabbitMQ retries up to 3 times, then routes to a dead-letter queue

Project Structure

NotificationService/
├── src/
│   ├── NotificationService.Api/            # ASP.NET Core Web API
│   ├── NotificationService.Core/           # Domain models & interfaces
│   ├── NotificationService.Templates/      # Scriban template engine
│   ├── NotificationService.Dispatcher/     # Rate limiter + orchestration
│   ├── NotificationService.Channels/       # Email / SMS / Push workers
│   └── NotificationService.Infrastructure/ # RabbitMQ, persistence, DI
├── tests/
│   ├── NotificationService.UnitTests/
│   └── NotificationService.IntegrationTests/
├── docker-compose.yml
└── NotificationService.sln

The key design decision: every layer depends only on Core interfaces. Swapping RabbitMQ for Azure Service Bus, or Twilio for Vonage, touches exactly one file.

Part 1 — Core Domain Models

Everything starts with the models. Keeping them in a separate project enforces that no business logic leaks into infrastructure.

// Core/Models/NotificationModels.cs

public record NotificationRequest
{
    public Guid Id { get; init; } = Guid.NewGuid();
    public required string RecipientId { get; init; }
    public required string[] Channels { get; init; }      // "email" | "sms" | "push"
    public required string TemplateName { get; init; }
    public Dictionary<string, object> Data { get; init; } = new();
    public NotificationPriority Priority { get; init; } = NotificationPriority.Normal;
    public DateTimeOffset CreatedAt { get; init; } = DateTimeOffset.UtcNow;
}

public record RenderedNotification
{
    public required string Recipient { get; init; }
    public required string Subject { get; init; }
    public required string Body { get; init; }
    public string? HtmlBody { get; init; }
    public Dictionary<string, string> Metadata { get; init; } = new();
}

public record DeliveryResult
{
    public bool IsSuccess { get; init; }
    public DeliveryStatus Status { get; init; }
    public string? MessageId { get; init; }
    public string? ErrorMessage { get; init; }

    public static DeliveryResult Success(string? messageId = null) => new()
        { IsSuccess = true, Status = DeliveryStatus.Delivered, MessageId = messageId };

    public static DeliveryResult Failure(string error) => new()
        { IsSuccess = false, Status = DeliveryStatus.Failed, ErrorMessage = error };
}

The core interfaces define the contracts every implementation must honour:

// Core/Interfaces/INotificationInterfaces.cs

public interface INotificationChannel
{
    string ChannelName { get; }
    Task<DeliveryResult> SendAsync(RenderedNotification notification, CancellationToken ct = default);
}

public interface ITemplateService
{
    Task<RenderedNotification> RenderAsync(
        string templateName,
        Dictionary<string, object> data,
        string channel,
        string recipient);
}

public interface IDispatcher
{
    Task DispatchAsync(NotificationRequest request, CancellationToken ct = default);
}

public interface IRateLimiter
{
    bool TryAcquire(string recipientId, string channel);
    Task<bool> TryAcquireAsync(string recipientId, string channel, CancellationToken ct = default);
}

Part 2 — Message Queue with RabbitMQ

Publisher

The publisher converts a NotificationRequest to bytes and publishes to a topic exchange. Priority is encoded as the AMQP message priority so high-priority messages jump the queue.

// Infrastructure/Queue/RabbitMqPublisher.cs

public class RabbitMqPublisher : INotificationPublisher, IDisposable
{
    public Task PublishAsync(NotificationRequest request, CancellationToken ct = default)
    {
        EnsureConnected();

        var body  = JsonSerializer.SerializeToUtf8Bytes(request);
        var props = _channel!.CreateBasicProperties();
        props.Persistent = true;
        props.Priority   = (byte)request.Priority;
        props.MessageId  = request.Id.ToString();

        var routingKey = $"notification.{request.Priority.ToString().ToLower()}";

        _channel.BasicPublish(
            exchange:        _opts.ExchangeName,
            routingKey:      routingKey,
            basicProperties: props,
            body:            body);

        return Task.CompletedTask;
    }
}

Consumer (BackgroundService)

The consumer runs as a hosted service. Failed messages are nacked — RabbitMQ routes them to the dead-letter queue after max retries.

// Infrastructure/Queue/RabbitMqConsumer.cs

public class RabbitMqConsumer : BackgroundService
{
    protected override Task ExecuteAsync(CancellationToken stoppingToken)
    {
        Connect();

        var consumer = new AsyncEventingBasicConsumer(_channel!);

        consumer.Received += async (_, ea) =>
        {
            try
            {
                var request = JsonSerializer.Deserialize<NotificationRequest>(ea.Body.Span)!;

                using var scope  = _scopeFactory.CreateScope();
                var dispatcher   = scope.ServiceProvider.GetRequiredService<IDispatcher>();

                await dispatcher.DispatchAsync(request, stoppingToken);
                _channel!.BasicAck(ea.DeliveryTag, multiple: false);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing notification");
                _channel!.BasicNack(ea.DeliveryTag, multiple: false, requeue: false);
            }
        };

        _channel!.BasicConsume(_opts.QueueName, autoAck: false, consumer);
        return Task.CompletedTask;
    }
}

Queue topology

Exchange: notifications (topic)
    │
    ├── notification.critical ──► Queue: notifications.main
    ├── notification.high     ──► Queue: notifications.main
    ├── notification.normal   ──► Queue: notifications.main
    └── notification.low      ──► Queue: notifications.main
                                           │
                                     (nack, no requeue)
                                           │
                                           ▼
                                  Queue: notifications.dlq

Part 3 — Template Service (Scriban)

Scriban is a fast, sandboxed templating engine for .NET. Templates are stored per (name, channel, part) — so welcome:email:body and welcome:sms:body can have completely different content. Compiled templates are cached in a ConcurrentDictionary — parsing happens once per unique key, never again.

// Templates/Services/ScribanTemplateService.cs

public class ScribanTemplateService(
    ITemplateRepository repository,
    ILogger<ScribanTemplateService> logger) : ITemplateService
{
    private static readonly ConcurrentDictionary<string, Template> _cache = new();

    public async Task<RenderedNotification> RenderAsync(
        string templateName, Dictionary<string, object> data,
        string channel, string recipient)
    {
        var subject = await RenderPartAsync(templateName, channel, "subject", data);
        var body    = await RenderPartAsync(templateName, channel, "body",    data);

        return new RenderedNotification
        {
            Recipient = recipient,
            Subject   = subject,
            Body      = body
        };
    }

    private async Task<string> RenderPartAsync(
        string name, string channel, string part,
        Dictionary<string, object> data)
    {
        var key = $"{name}:{channel}:{part}";

        var compiled = _cache.GetOrAdd(key, _ =>
        {
            var source = repository.GetTemplateAsync(name, channel, part)
                .GetAwaiter().GetResult()
                ?? throw new InvalidOperationException($"Template not found: {key}");
            return Template.Parse(source);
        });

        var ctx   = new TemplateContext { StrictVariables = false };
        var model = new ScriptObject();
        foreach (var (k, v) in data) model.Add(k, v);
        ctx.PushGlobal(model);

        return await compiled.RenderAsync(ctx);
    }
}

Seeded templates (ready out of the box)

Template	Channel	What it sends
`welcome`	email	Full welcome with verification link
`welcome`	sms	Short text with verification link
`welcome`	push	Tap-to-verify push notification
`password-reset`	email / sms / push	Reset link + expiry notice
`order-confirmation`	all	Order ID, total, delivery date, tracking link

Part 4 — Rate Limiter (Sliding Window)

The rate limiter sits inside the Dispatcher — not at the API layer — so limits apply regardless of how notifications enter the system.

// Dispatcher/RateLimiting/SlidingWindowRateLimiter.cs

public class SlidingWindowRateLimiter(
    IMemoryCache cache,
    IOptions<RateLimitOptions> options) : IRateLimiter
{
    public bool TryAcquire(string recipientId, string channel)
    {
        var key    = $"rl:{channel}:{recipientId}";
        var window = cache.GetOrCreate(key, entry =>
        {
            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(_opts.WindowSeconds);
            return new WindowCounter(_opts.MaxPerWindow);
        })!;

        return window.TryConsume();
    }

    private sealed class WindowCounter(int max)
    {
        private int _count;
        public bool TryConsume() => Interlocked.Increment(ref _count) <= max;
    }
}

Each (recipientId, channel) pair has its own independent window. Configure via appsettings.json:

"RateLimit": {
  "MaxPerWindow": 10,
  "WindowSeconds": 3600
}

For distributed deployments: replace IMemoryCache with a Redis-backed implementation using INCR + EXPIRE per key.

Part 5 — Dispatcher (Orchestration)

The Dispatcher wires together template rendering, rate limiting, and channel delivery — all in parallel.

// Dispatcher/Services/NotificationDispatcher.cs

public class NotificationDispatcher(
    ITemplateService templateService,
    IEnumerable<INotificationChannel> channels,
    IRateLimiter rateLimiter,
    IRecipientResolver recipientResolver,
    ILogger<NotificationDispatcher> logger) : IDispatcher
{
    public async Task DispatchAsync(NotificationRequest request, CancellationToken ct = default)
    {
        var recipient = await recipientResolver.ResolveAsync(request.RecipientId, ct);
        if (recipient is null)
        {
            logger.LogWarning("Recipient {Id} not found", request.RecipientId);
            return;
        }

        var targets = channels
            .Where(c => request.Channels.Contains(c.ChannelName, StringComparer.OrdinalIgnoreCase))
            .ToList();

        // Fan-out to all channels IN PARALLEL
        var tasks = targets.Select(ch => SendToChannelAsync(ch, request, recipient, ct));
        await Task.WhenAll(tasks);
    }

    private async Task SendToChannelAsync(
        INotificationChannel channel, NotificationRequest request,
        RecipientInfo recipient, CancellationToken ct)
    {
        if (!await rateLimiter.TryAcquireAsync(request.RecipientId, channel.ChannelName, ct))
        {
            logger.LogWarning("Rate limited: {Recipient} on {Channel}",
                request.RecipientId, channel.ChannelName);
            return;
        }

        var address = channel.ChannelName.ToLower() switch
        {
            "email" => recipient.Email,
            "sms"   => recipient.PhoneNumber,
            "push"  => recipient.DevicePushToken,
            _       => null
        };

        if (address is null) return;

        var rendered = await templateService.RenderAsync(
            request.TemplateName, request.Data, channel.ChannelName, address);

        var result = await channel.SendAsync(rendered, ct);

        if (result.IsSuccess)
            logger.LogInformation("✓ {Channel} → {Recipient}", channel.ChannelName, request.RecipientId);
        else
            logger.LogError("✗ {Channel} failed → {Error}", channel.ChannelName, result.ErrorMessage);
    }
}

Task.WhenAll means an ["email", "sms", "push"] request sends all three concurrently. One channel throwing never blocks the others.

Part 6 — Channel Workers

Email — MailKit

public class EmailChannel(IOptions<SmtpOptions> opts, ILogger<EmailChannel> logger) : INotificationChannel
{
    public string ChannelName => "email";

    public async Task<DeliveryResult> SendAsync(RenderedNotification n, CancellationToken ct = default)
    {
        try
        {
            var message = new MimeMessage();
            message.From.Add(new MailboxAddress(opts.Value.FromName, opts.Value.FromAddress));
            message.To.Add(MailboxAddress.Parse(n.Recipient));
            message.Subject = n.Subject;

            var builder = new BodyBuilder();
            if (n.HtmlBody is not null) { builder.HtmlBody = n.HtmlBody; builder.TextBody = n.Body; }
            else builder.TextBody = n.Body;
            message.Body = builder.ToMessageBody();

            using var client = new SmtpClient();
            await client.ConnectAsync(opts.Value.Host, opts.Value.Port,
                SecureSocketOptions.StartTlsWhenAvailable, ct);
            await client.AuthenticateAsync(opts.Value.User, opts.Value.Password, ct);
            await client.SendAsync(message, ct);
            await client.DisconnectAsync(quit: true, ct);

            return DeliveryResult.Success(message.MessageId);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Email failed to {Recipient}", n.Recipient);
            return DeliveryResult.Failure(ex.Message);
        }
    }
}

SMS — Twilio

public class SmsChannel(IOptions<TwilioOptions> opts, ILogger<SmsChannel> logger) : INotificationChannel
{
    public string ChannelName => "sms";

    public async Task<DeliveryResult> SendAsync(RenderedNotification n, CancellationToken ct = default)
    {
        EnsureInitialized();

        try
        {
            var message = await MessageResource.CreateAsync(
                to:   new PhoneNumber(n.Recipient),
                from: new PhoneNumber(opts.Value.FromNumber),
                body: n.Body);

            return message.ErrorCode is null
                ? DeliveryResult.Success(message.Sid)
                : DeliveryResult.Failure($"[{message.ErrorCode}] {message.ErrorMessage}");
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "SMS failed to {Recipient}", n.Recipient);
            return DeliveryResult.Failure(ex.Message);
        }
    }
}

Push — Firebase FCM

public class PushChannel(IOptions<FirebaseOptions> opts, ILogger<PushChannel> logger) : INotificationChannel
{
    public string ChannelName => "push";

    public async Task<DeliveryResult> SendAsync(RenderedNotification n, CancellationToken ct = default)
    {
        await EnsureInitializedAsync();

        try
        {
            var message = new Message
            {
                Token        = n.Recipient,
                Notification = new FirebaseAdmin.Messaging.Notification
                    { Title = n.Subject, Body = n.Body },
                Android = new AndroidConfig { Priority = Priority.High },
                Apns    = new ApnsConfig { Aps = new Aps { Sound = "default" } },
                Data    = n.Metadata
            };

            var messageId = await FirebaseMessaging.GetMessaging(_app!).SendAsync(message, ct);
            return DeliveryResult.Success(messageId);
        }
        catch (FirebaseMessagingException ex)
            when (ex.MessagingErrorCode == MessagingErrorCode.Unregistered)
        {
            return DeliveryResult.Failure("FCM token is no longer valid");
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Push failed to {Recipient}", n.Recipient);
            return DeliveryResult.Failure(ex.Message);
        }
    }
}

Part 7 — API Layer

The controller is intentionally thin — validate, publish, return 202 Accepted. No business logic.

[ApiController]
[Route("api/[controller]")]
public class NotificationsController(
    INotificationPublisher publisher,
    ILogger<NotificationsController> logger) : ControllerBase
{
    [HttpPost]
    [ProducesResponseType(typeof(NotificationResponse), StatusCodes.Status202Accepted)]
    public async Task<IActionResult> Send(
        [FromBody] SendNotificationRequest request, CancellationToken ct)
    {
        if (request.Channels.Length == 0)
            return BadRequest(new { error = "At least one channel is required" });

        var notification = new NotificationRequest
        {
            RecipientId  = request.RecipientId,
            Channels     = request.Channels,
            TemplateName = request.TemplateName,
            Data         = request.Data,
            Priority     = request.Priority
        };

        await publisher.PublishAsync(notification, ct);
        return Accepted(new NotificationResponse(notification.Id, "Queued", DateTimeOffset.UtcNow));
    }
}

Example request

POST /api/notifications
Content-Type: application/json

{
  "recipientId": "user-123",
  "channels": ["email", "sms", "push"],
  "templateName": "welcome",
  "data": {
    "firstName": "Alice",
    "verificationLink": "https://app.example.com/verify?token=abc123"
  },
  "priority": "High"
}

Response

{
  "notificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Queued",
  "queuedAt": "2024-01-15T10:30:00Z"
}

Part 8 — DI Wiring (Program.cs)

builder.Services.AddSingleton<ITemplateRepository, InMemoryTemplateRepository>();
builder.Services.AddScoped<ITemplateService, ScribanTemplateService>();

builder.Services.AddMemoryCache();
builder.Services.Configure<RateLimitOptions>(builder.Configuration.GetSection("RateLimit"));
builder.Services.AddSingleton<IRateLimiter, SlidingWindowRateLimiter>();

builder.Services.Configure<SmtpOptions>(builder.Configuration.GetSection("Smtp"));
builder.Services.Configure<TwilioOptions>(builder.Configuration.GetSection("Twilio"));
builder.Services.Configure<FirebaseOptions>(builder.Configuration.GetSection("Firebase"));
builder.Services.AddScoped<INotificationChannel, EmailChannel>();
builder.Services.AddScoped<INotificationChannel, SmsChannel>();
builder.Services.AddScoped<INotificationChannel, PushChannel>();

builder.Services.AddScoped<IDispatcher, NotificationDispatcher>();

builder.Services.AddRabbitMq(builder.Configuration);
builder.Services.AddInfrastructure(builder.Configuration);

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddAspNetCoreInstrumentation().AddConsoleExporter());

builder.Services.AddHealthChecks()
    .AddRabbitMQ(rabbitConnectionString: "amqp://guest:guest@localhost/");

app.MapHealthChecks("/health");

Part 9 — Unit Tests

[Fact]
public void TryAcquire_AtLimit_ReturnsFalse()
{
    var limiter = CreateLimiter(max: 2);
    limiter.TryAcquire("user-1", "sms").Should().BeTrue();
    limiter.TryAcquire("user-1", "sms").Should().BeTrue();
    limiter.TryAcquire("user-1", "sms").Should().BeFalse(); // blocked
}

[Fact]
public void TryAcquire_DifferentChannels_TrackSeparately()
{
    var limiter = CreateLimiter(max: 1);
    limiter.TryAcquire("user-2", "email").Should().BeTrue();
    limiter.TryAcquire("user-2", "email").Should().BeFalse();
    limiter.TryAcquire("user-2", "sms").Should().BeTrue();  // sms is independent
}

[Fact]
public async Task DispatchAsync_WhenRateLimited_SkipsChannel()
{
    _rateLimiter.Setup(r => r.TryAcquireAsync("u1", "email", default))
        .ReturnsAsync(false);

    await dispatcher.DispatchAsync(request);

    _emailChannel.Verify(
        c => c.SendAsync(It.IsAny<RenderedNotification>(), default), Times.Never);
}

[Fact]
public async Task RenderAsync_InterpolatesVariables()
{
    var service = CreateService("Hello, {{ name }}!");
    var result  = await service.RenderAsync("tpl", new() { ["name"] = "Alice" }, "email", "a@b.com");
    result.Body.Should().Be("Hello, Alice!");
}

Run the full suite:

dotnet test

Part 10 — Docker Compose

services:
  api:
    build:
      context: .
      dockerfile: src/NotificationService.Api/Dockerfile
    ports:
      - "5000:8080"
    environment:
      - RabbitMq__Host=rabbitmq
    depends_on:
      rabbitmq:
        condition: service_healthy

  rabbitmq:
    image: rabbitmq:3.13-management-alpine
    ports:
      - "5672:5672"
      - "15672:15672"
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      interval: 10s
      retries: 5

  redis:
    image: redis:7.4-alpine
    ports:
      - "6379:6379"

Start everything:

docker-compose up -d

API → http://localhost:5000 · Swagger → http://localhost:5000/swagger · RabbitMQ UI → http://localhost:15672

Part 11 — GitHub Actions CI

name: CI
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    services:
      rabbitmq:
        image: rabbitmq:3.13-alpine
        ports: [ 5672:5672 ]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 8.0.x
      - run: dotnet restore
      - run: dotnet build --no-restore -c Release
      - run: dotnet test tests/NotificationService.UnitTests -c Release --logger trx

  docker:
    runs-on: ubuntu-latest
    needs: build-and-test
    steps:
      - uses: actions/checkout@v4
      - run: docker build -f src/NotificationService.Api/Dockerfile -t notification-service:${{ github.sha }} .

Extending the Service

Add a new channel (e.g. Slack) — 3 steps

Step 1 — Implement INotificationChannel:

public class SlackChannel(IOptions<SlackOptions> opts) : INotificationChannel
{
    public string ChannelName => "slack";

    public async Task<DeliveryResult> SendAsync(RenderedNotification n, CancellationToken ct)
    {
        var payload  = new { text = $"*{n.Subject}*\n{n.Body}" };
        var response = await _httpClient.PostAsJsonAsync(opts.Value.WebhookUrl, payload, ct);

        return response.IsSuccessStatusCode
            ? DeliveryResult.Success()
            : DeliveryResult.Failure(response.ReasonPhrase!);
    }
}

Step 2 — Register it:

builder.Services.AddScoped<INotificationChannel, SlackChannel>();

Step 3 — Add templates for slack:subject and slack:body. The Dispatcher discovers it automatically. Zero changes to existing code.

Distributed rate limiting (Redis)

public async Task<bool> TryAcquireAsync(string recipientId, string channel, CancellationToken ct)
{
    var key   = $"rl:{channel}:{recipientId}";
    var count = await _db.StringIncrementAsync(key);
    if (count == 1)
        await _db.KeyExpireAsync(key, TimeSpan.FromSeconds(_opts.WindowSeconds));
    return count <= _opts.MaxPerWindow;
}

Key Design Decisions

Message queue over direct delivery — The API never waits on SMTP, Twilio, or FCM. Response time is constant regardless of provider latency. Dead-letter queuing means no silent message loss during outages.

Scriban over Razor — Scriban compiles to a sandboxed AST. It cannot execute arbitrary C# code — important when templates might be user-editable. It also benchmarks significantly faster for pure string interpolation at scale.

Rate limiting in the Dispatcher, not the API — Notifications can enter from multiple sources. Placing rate limiting in the Dispatcher guarantees it applies everywhere, not just the HTTP path.

Task.WhenAll fan-out — One slow provider doesn't delay others. Email taking 800ms doesn't block push from delivering in 50ms. Failures are isolated — one channel exception never affects the others.

IEnumerable<INotificationChannel> in the Dispatcher — ASP.NET Core's DI resolves all registered implementations automatically. Adding a channel is one AddScoped call with zero changes to the Dispatcher.

What's Next

Delivery receipts — webhook callbacks from Twilio/FCM to track delivery status in your DB
User preferences — let recipients opt out of channels or specific notification types
Scheduled notifications — Hangfire or Quartz.NET for delayed delivery
Template management API — CRUD endpoints to edit templates without redeploying
Redis rate limiter — for multi-instance deployments
End-to-end OpenTelemetry traces — trace a notification from API call through queue through dispatcher through provider

Source Code

The complete, production-ready source code is on GitHub — includes all the code shown in this post, Docker Compose setup, GitHub Actions CI pipeline, full test suite (xUnit + Moq + FluentAssertions), and architecture documentation.

🔗 github.com/naimulkarim/NotificationService

Built with .NET 8 · RabbitMQ · MailKit · Twilio · Firebase FCM · Scriban · OpenTelemetry

Building a Cloud-Native Event Ticketing System with DDD, Event-Driven Architecture & CQRS in .NET 8

Naimul Karim — Thu, 07 May 2026 05:35:39 +0000

Full source code: github.com/naimulkarim/TicketingSystem

Stack: .NET 8 · Angular 17 · SQL Server · RabbitMQ · Redis · MassTransit · MediatR · YARP · Docker · GitHub Actions

When you buy a concert ticket online, a deceptively large amount happens in the few seconds between clicking "Purchase" and receiving your confirmation email. Seats must be reserved atomically before payment is taken. Payment can fail — in which case the seat must be released so another customer can buy it. A confirmation email must fire. An admin dashboard must stay consistent. None of this can be lost, even if a service crashes mid-workflow.

This article walks through how I designed and built a production-grade online ticketing platform for concerts, sports, and live shows — from domain modelling through to Docker Compose and CI. Every code snippet comes from the real repository at github.com/naimulkarim/TicketingSystem with direct file links.

The three patterns at the heart of the design:

Domain-Driven Design (DDD) — keeps business logic in the domain, not scattered across controllers or services
Event-Driven Architecture (EDA) — decouples services through asynchronous messages and a saga for distributed workflows
CQRS — separates the write model (commands) from the read model (queries) for clarity and independent scalability

The Problem Domain & Why These Patterns
Architecture Overview — The 30,000 ft View
Solution Structure & Full File Map
The Shared Kernel — DDD Building Blocks
Bounded Context 1: Identity Service
Bounded Context 2: Event Catalog Service
Bounded Context 3: Booking Service — DDD + CQRS + Saga
Bounded Context 4: Payment Service
Bounded Context 5: Notification Service
The API Gateway — YARP
Event-Driven Architecture Deep Dive
The Booking Saga — Distributed Workflow
The Outbox Pattern — Guaranteed Delivery
Redis Seat Locking — Preventing Overselling
The Angular Frontend — NgRx Architecture
All Features & Use Cases — End to End
Infrastructure: Docker Compose & SQL Server
CI/CD: GitHub Actions Pipeline
Unit Tests
What to Build Next
Conclusion & GitHub Link

1. The Problem Domain & Why These Patterns

An event ticketing system exposes several genuinely hard problems:

Problem	Why it's hard	Pattern that solves it
Two users booking the last seat simultaneously	Race condition — DB locks don't scale	Redis distributed lock (SET NX)
Payment fails after seat is reserved	Must release seat as compensation	Saga with compensating transactions
Service crashes between saving booking and publishing event	Message lost — booking stuck	Outbox pattern (atomic write + publish)
High read traffic for event search vs. low-frequency writes	Write complexity pollutes read performance	CQRS — separate read/write paths
Notification service needs to react to bookings	Tight coupling if called directly	Integration events on RabbitMQ
Business rules scattered across controllers	Impossible to test, easy to break	Aggregates with invariant enforcement

These are not hypothetical edge cases. They are the daily reality of any system that handles money and inventory under concurrent load.

2. Architecture Overview

┌────────────────────────────────────────────────────────────────────┐
│                         CLIENT TIER                                │
│              Angular 17 SPA (NgRx · OIDC PKCE · Signals)          │
└─────────────────────────────┬──────────────────────────────────────┘
                              │ HTTPS / JWT
                              ▼
┌────────────────────────────────────────────────────────────────────┐
│                      API GATEWAY (YARP)                            │
│           Auth · Rate Limiting (300 req/min) · Routing             │
│                     localhost:5000                                  │
└──────┬──────────────┬────────────────┬────────────────┬────────────┘
       │              │                │                │
       ▼              ▼                ▼                ▼
┌──────────┐  ┌──────────────┐  ┌──────────┐  ┌──────────────┐
│ Identity │  │ EventCatalog │  │ Booking  │  │   Payment    │
│ :5001    │  │ :5002        │  │ :5003    │  │   :5004      │
│          │  │              │  │ ◄── SAGA │  │              │
│ OAuth2   │  │ Events       │  │ Aggreg.  │  │ Stripe PSP   │
│ OIDC     │  │ Venues       │  │ CQRS     │  │ Refunds      │
│ JWT      │  │ Seat Maps    │  │ Outbox   │  │              │
└──────────┘  └──────────────┘  └────┬─────┘  └──────┬───────┘
                                     │               │
                    ┌────────────────▼───────────────▼──────────┐
                    │         RabbitMQ Message Bus               │
                    │   Domain Events · Integration Events       │
                    │   Dead-Letter Queues · Saga State          │
                    └───────────┬────────────────┬──────────────┘
                                │                │
                    ┌───────────▼──┐  ┌──────────▼──────────┐
                    │ Notification │  │  Read Model          │
                    │ :5005        │  │  Projectors          │
                    │ Email/SMS    │  │  (future)            │
                    └──────────────┘  └─────────────────────┘

DATA TIER
┌──────────────┐  ┌────────────────────────────────────────────┐
│    Redis     │  │  SQL Server (one database per service)      │
│  Seat locks  │  │  Booking_DB · EventCatalog_DB · Payment_DB  │
│  TTL: 10min  │  │  Identity_DB                                │
└──────────────┘  └────────────────────────────────────────────┘

OBSERVABILITY
┌────────────────────────────────────────────────────────────────┐
│  OpenTelemetry → Jaeger (tracing) · Prometheus → Grafana       │
│  Serilog (structured logs) · /health endpoints per service     │
└────────────────────────────────────────────────────────────────┘

Key architectural decisions:

One database per service — no shared schema, no cross-service joins. Queries that need data from multiple services use the read model or a BFF.
RabbitMQ as the only cross-service channel — services never call each other's HTTP APIs directly. All integration happens through published events and commands on the bus.
Saga in Booking — the Booking service owns the checkout workflow and coordinates Payment via commands on RabbitMQ.
Outbox in every write service — domain events are atomically persisted to an outbox table in the same DB transaction as aggregate state, guaranteeing no message is lost.

3. Solution Structure & Full File Map

TicketingSystem/                              ← github.com/naimulkarim/TicketingSystem
│
├── TicketingSystem.sln
├── docker-compose.yml
├── .env.example
├── setup-github.sh
├── GITHUB_SETUP.md
│
├── src/
│   ├── SharedKernel/
│   │   ├── SharedKernel.csproj
│   │   ├── Domain/
│   │   │   ├── AggregateRoot.cs
│   │   │   ├── Primitives.cs               ← DomainEvent, ValueObject, Entity<T>
│   │   │   └── Result.cs                   ← Result<T> error pattern
│   │   ├── Application/Behaviours/
│   │   │   └── PipelineBehaviours.cs       ← ValidationBehaviour, LoggingBehaviour
│   │   └── Infrastructure/
│   │       └── OutboxMessage.cs
│   │
│   ├── Services/
│   │   ├── Identity/
│   │   │   ├── Api/Program.cs
│   │   │   ├── Api/IdentityConfig.cs       ← OAuth2 clients, scopes, resources
│   │   │   ├── Identity.csproj
│   │   │   └── Dockerfile
│   │   │
│   │   ├── EventCatalog/
│   │   │   ├── Domain/Aggregates/Event.cs  ← Event + SeatMap aggregates
│   │   │   ├── Application/EventHandlers.cs← Commands, Queries, Validators
│   │   │   ├── Infrastructure/Persistence/EventCatalogDbContext.cs
│   │   │   ├── Api/Controllers/EventsController.cs
│   │   │   ├── Api/Program.cs
│   │   │   ├── EventCatalog.csproj
│   │   │   └── Dockerfile
│   │   │
│   │   ├── Booking/
│   │   │   ├── Domain/
│   │   │   │   ├── Aggregates/Booking.cs   ← Booking aggregate root
│   │   │   │   ├── Events/BookingEvents.cs ← Domain + integration events
│   │   │   │   └── Repositories/IBookingRepository.cs
│   │   │   ├── Application/
│   │   │   │   ├── Commands/CreateBookingCommand.cs
│   │   │   │   ├── Queries/GetBookingQuery.cs
│   │   │   │   └── Sagas/BookingSagaStateMachine.cs
│   │   │   ├── Infrastructure/
│   │   │   │   ├── Persistence/BookingDbContext.cs
│   │   │   │   ├── Persistence/BookingRepository.cs
│   │   │   │   └── RedisSeatLockService.cs
│   │   │   ├── Api/Controllers/BookingsController.cs
│   │   │   ├── Api/Program.cs
│   │   │   ├── Booking.csproj
│   │   │   └── Dockerfile
│   │   │
│   │   ├── Payment/
│   │   │   ├── Domain/Aggregates/Payment.cs
│   │   │   ├── Infrastructure/Messaging/ProcessPaymentConsumer.cs
│   │   │   ├── Infrastructure/Persistence/PaymentDbContext.cs
│   │   │   ├── Api/Program.cs
│   │   │   ├── Payment.csproj
│   │   │   └── Dockerfile
│   │   │
│   │   └── Notification/
│   │       ├── Application/Consumers/BookingConsumers.cs
│   │       ├── Api/Program.cs
│   │       ├── Notification.csproj
│   │       └── Dockerfile
│   │
│   └── ApiGateway/
│       ├── Program.cs
│       ├── appsettings.json                ← YARP routes + clusters
│       ├── ApiGateway.csproj
│       └── Dockerfile
│
├── frontend/
│   ├── src/app/
│   │   ├── app.component.ts               ← root shell + nav
│   │   ├── app.config.ts                  ← NgRx, router, OAuth providers
│   │   ├── app.routes.ts                  ← lazy-loaded feature modules
│   │   ├── core/
│   │   │   ├── guards/auth.guard.ts
│   │   │   ├── interceptors/auth.interceptor.ts
│   │   │   └── services/auth.service.ts
│   │   ├── features/
│   │   │   ├── events/event-list.component.ts
│   │   │   ├── events/event-detail.component.ts
│   │   │   ├── account/my-bookings.component.ts
│   │   │   └── admin/admin-events.component.ts
│   │   └── store/
│   │       ├── auth/auth.reducer.ts
│   │       ├── booking/booking.reducer.ts
│   │       └── events/events.reducer.ts
│   ├── Dockerfile
│   └── nginx.conf
│
├── tests/
│   └── Unit/
│       ├── Booking/BookingAggregateTests.cs
│       ├── Booking/CreateBookingCommandHandlerTests.cs
│       └── SharedKernel/ValueObjectTests.cs
│
└── .github/workflows/ci.yml

4. The Shared Kernel — DDD Building Blocks

📁 src/SharedKernel/

The Shared Kernel has no business logic and no external dependencies beyond FluentValidation and MediatR abstractions. It defines the DDD primitives that every service inherits.

AggregateRoot

// src/SharedKernel/Domain/AggregateRoot.cs

public abstract class AggregateRoot<TId> where TId : notnull
{
    public TId Id { get; protected set; } = default!;

    private readonly List<DomainEvent> _domainEvents = new();
    public IReadOnlyList<DomainEvent> DomainEvents => _domainEvents.AsReadOnly();

    protected void RaiseDomainEvent(DomainEvent domainEvent) =>
        _domainEvents.Add(domainEvent);

    public void ClearDomainEvents() => _domainEvents.Clear();
}

The aggregate collects domain events in memory during a business operation. The infrastructure layer (DbContext's SaveChangesAsync override) reads them, writes them to the outbox table, and clears them — all in one atomic transaction. This is the core of reliable event publishing.

DomainEvent, ValueObject, Entity

// src/SharedKernel/Domain/Primitives.cs

public abstract record DomainEvent
{
    public Guid Id { get; init; } = Guid.NewGuid();
    public DateTime OccurredOnUtc { get; init; } = DateTime.UtcNow;
}

public abstract class ValueObject
{
    protected abstract IEnumerable<object?> GetEqualityComponents();

    public override bool Equals(object? obj)
    {
        if (obj is null || obj.GetType() != GetType()) return false;
        return ((ValueObject)obj).GetEqualityComponents()
            .SequenceEqual(GetEqualityComponents());
    }

    public override int GetHashCode() =>
        GetEqualityComponents()
            .Select(x => x?.GetHashCode() ?? 0)
            .Aggregate((x, y) => x ^ y);

    public static bool operator ==(ValueObject? left, ValueObject? right) =>
        left?.Equals(right) ?? right is null;

    public static bool operator !=(ValueObject? left, ValueObject? right) =>
        !(left == right);
}

Value objects are immutable and identity-free. Two Money instances with the same amount and currency are equal regardless of reference — the equality is structural, not referential. This models real-world concepts like prices, seat numbers, and currency codes correctly.

Result Pattern

// src/SharedKernel/Domain/Result.cs

public class Result<T>
{
    public T? Value { get; }
    public string? Error { get; }
    public bool IsSuccess { get; }
    public bool IsFailure => !IsSuccess;

    private Result(T value)      { Value = value; IsSuccess = true; }
    private Result(string error) { Error = error; IsSuccess = false; }

    public static Result<T> Success(T value) => new(value);
    public static Result<T> Failure(string error) => new(error);
}

Commands return Result<T> rather than throwing exceptions for expected failures. This forces the caller to handle both paths explicitly.

MediatR Pipeline Behaviours

// src/SharedKernel/Application/Behaviours/PipelineBehaviours.cs

// Runs before every Command and Query — validates the request first
public class ValidationBehaviour<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse> where TRequest : notnull
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;
    public ValidationBehaviour(IEnumerable<IValidator<TRequest>> validators) =>
        _validators = validators;

    public async Task<TResponse> Handle(
        TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken ct)
    {
        if (!_validators.Any()) return await next();

        var context = new ValidationContext<TRequest>(request);
        var failures = _validators
            .Select(v => v.Validate(context))
            .SelectMany(r => r.Errors)
            .Where(f => f != null)
            .ToList();

        if (failures.Count != 0)
            throw new ValidationException(failures);

        return await next();
    }
}

// Structured logging for every request — zero boilerplate in handlers
public class LoggingBehaviour<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse> where TRequest : notnull
{
    private readonly ILogger<LoggingBehaviour<TRequest, TResponse>> _logger;
    public LoggingBehaviour(ILogger<LoggingBehaviour<TRequest, TResponse>> logger) =>
        _logger = logger;

    public async Task<TResponse> Handle(
        TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken ct)
    {
        var name = typeof(TRequest).Name;
        _logger.LogInformation("Handling {RequestName}", name);
        var response = await next();
        _logger.LogInformation("Handled {RequestName}", name);
        return response;
    }
}

Both behaviours are registered as open generics — they automatically apply to every Command and Query in every service without any per-handler wiring:

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssemblyContaining<CreateBookingCommand>();
    cfg.AddOpenBehavior(typeof(ValidationBehaviour<,>));
    cfg.AddOpenBehavior(typeof(LoggingBehaviour<,>));
});

5. Bounded Context 1: Identity Service

📁 src/Services/Identity/

The Identity service is the single source of truth for authentication. It runs Duende IdentityServer and issues JWTs. All other services validate tokens against its discovery document — they never call it at runtime beyond token validation.

OAuth2 Client Configuration

// src/Services/Identity/Api/IdentityConfig.cs

public static class IdentityConfig
{
    public static IEnumerable<ApiScope> ApiScopes => new[]
    {
        new ApiScope("booking-api",      "Booking Service"),
        new ApiScope("eventcatalog-api", "Event Catalog Service"),
        new ApiScope("payment-api",      "Payment Service"),
    };

    public static IEnumerable<Client> Clients => new[]
    {
        // Angular SPA — Authorization Code + PKCE (no client secret in the browser)
        new Client
        {
            ClientId = "angular-spa",
            ClientName = "TicketingSystem Angular App",
            AllowedGrantTypes = GrantTypes.Code,
            RequirePkce = true,
            RequireClientSecret = false,                   // public client
            RedirectUris           = { "http://localhost:4200/auth/callback" },
            PostLogoutRedirectUris = { "http://localhost:4200" },
            AllowedCorsOrigins     = { "http://localhost:4200" },
            AllowedScopes = {
                "openid", "profile", "email",
                "booking-api", "eventcatalog-api"
            },
            AccessTokenLifetime = 3600,                    // 1 hour
        },

        // Machine-to-machine: services calling each other
        new Client
        {
            ClientId = "m2m-client",
            ClientSecrets = { new Secret("m2m-secret".Sha256()) },
            AllowedGrantTypes = GrantTypes.ClientCredentials,
            AllowedScopes = { "booking-api", "payment-api", "eventcatalog-api" }
        }
    };
}

Program.cs

// src/Services/Identity/Api/Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddIdentityServer(opts =>
{
    opts.Events.RaiseErrorEvents   = true;
    opts.Events.RaiseSuccessEvents = true;
})
.AddInMemoryApiScopes(IdentityConfig.ApiScopes)
.AddInMemoryClients(IdentityConfig.Clients)
.AddInMemoryApiResources(IdentityConfig.ApiResources)
.AddDeveloperSigningCredential(); // ← swap for X.509 cert in production

var app = builder.Build();
app.UseIdentityServer();
app.MapHealthChecks("/health");
app.Run();

Feature delivered: UC-00 — all authenticated flows. The Angular frontend connects via PKCE; backend services use client credentials for M2M calls.

6. Bounded Context 2: Event Catalog Service

📁 src/Services/EventCatalog/

The Event Catalog owns everything about live events: their details, venues, seat maps, and availability. It is the source of truth for what can be booked.

The Event Aggregate

// src/Services/EventCatalog/Domain/Aggregates/Event.cs

public class Event : AggregateRoot<Guid>
{
    public string Title { get; private set; } = null!;
    public string Description { get; private set; } = null!;
    public string Category { get; private set; } = null!;  // Concert | Sports | Theater
    public string Venue { get; private set; } = null!;
    public string City { get; private set; } = null!;
    public DateTime StartsAtUtc { get; private set; }
    public decimal BasePrice { get; private set; }
    public string Currency { get; private set; } = null!;
    public int TotalSeats { get; private set; }
    public int AvailableSeats { get; private set; }
    public bool IsPublished { get; private set; }           // draft until published

    private readonly List<SeatMap> _seats = new();
    public IReadOnlyList<SeatMap> Seats => _seats.AsReadOnly();

    private Event() { }  // EF Core

    public static Event Create(string title, string description, string category,
        string venue, string city, DateTime startsAt,
        decimal basePrice, string currency, int totalSeats)
    {
        var ev = new Event
        {
            Id = Guid.NewGuid(),
            Title = title, Description = description,
            Category = category, Venue = venue, City = city,
            StartsAtUtc = startsAt, BasePrice = basePrice,
            Currency = currency, TotalSeats = totalSeats,
            AvailableSeats = totalSeats,  // starts fully available
            IsPublished = false           // always created as draft
        };

        ev.RaiseDomainEvent(new EventCreatedDomainEvent(ev.Id, title, startsAt));
        return ev;
    }

    public void Publish()
    {
        IsPublished = true;
        RaiseDomainEvent(new EventPublishedDomainEvent(Id, Title));
    }

    // Called when the Booking saga confirms a reservation
    public void ReserveSeat(string seatNumber)
    {
        if (AvailableSeats <= 0)
            throw new InvalidOperationException("No seats available");
        AvailableSeats--;  // invariant: cannot go below 0
    }

    // Called when the Booking saga compensates on payment failure
    public void ReleaseSeat(string seatNumber)
    {
        AvailableSeats++;
    }
}

CQRS — Commands and Queries

// src/Services/EventCatalog/Application/EventHandlers.cs

// ── Create Event Command ──────────────────────────────────────────────────────
public record CreateEventCommand(
    string Title, string Description, string Category,
    string Venue, string City, DateTime StartsAtUtc,
    decimal BasePrice, string Currency, int TotalSeats) : IRequest<Guid>;

public class CreateEventValidator : AbstractValidator<CreateEventCommand>
{
    public CreateEventValidator()
    {
        RuleFor(x => x.Title).NotEmpty().MaximumLength(200);
        RuleFor(x => x.Category).NotEmpty();
        RuleFor(x => x.StartsAtUtc).GreaterThan(DateTime.UtcNow);
        RuleFor(x => x.BasePrice).GreaterThanOrEqualTo(0);
        RuleFor(x => x.TotalSeats).GreaterThan(0);
    }
}

public class CreateEventHandler : IRequestHandler<CreateEventCommand, Guid>
{
    private readonly EventCatalogDbContext _ctx;
    public CreateEventHandler(EventCatalogDbContext ctx) => _ctx = ctx;

    public async Task<Guid> Handle(CreateEventCommand cmd, CancellationToken ct)
    {
        var ev = Event.Create(cmd.Title, cmd.Description, cmd.Category,
            cmd.Venue, cmd.City, cmd.StartsAtUtc,
            cmd.BasePrice, cmd.Currency, cmd.TotalSeats);
        _ctx.Events.Add(ev);
        await _ctx.SaveChangesAsync(ct);
        return ev.Id;
    }
}

// ── Search Events Query (read side — AsNoTracking for performance) ───────────
public record SearchEventsQuery(
    string? City, string? Category, DateTime? From,
    int Page = 1, int PageSize = 20) : IRequest<List<EventDto>>;

public class SearchEventsHandler : IRequestHandler<SearchEventsQuery, List<EventDto>>
{
    private readonly EventCatalogDbContext _ctx;
    public SearchEventsHandler(EventCatalogDbContext ctx) => _ctx = ctx;

    public async Task<List<EventDto>> Handle(SearchEventsQuery q, CancellationToken ct)
    {
        var query = _ctx.Events.AsNoTracking()  // read-only: no change tracking overhead
            .Where(e => e.IsPublished);

        if (!string.IsNullOrEmpty(q.City))     query = query.Where(e => e.City == q.City);
        if (!string.IsNullOrEmpty(q.Category)) query = query.Where(e => e.Category == q.Category);
        if (q.From.HasValue)                   query = query.Where(e => e.StartsAtUtc >= q.From);

        return await query
            .OrderBy(e => e.StartsAtUtc)
            .Skip((q.Page - 1) * q.PageSize)
            .Take(q.PageSize)
            .Select(e => new EventDto(e.Id, e.Title, e.Description, e.Category,
                e.Venue, e.City, e.StartsAtUtc, e.BasePrice, e.Currency,
                e.TotalSeats, e.AvailableSeats, e.IsPublished))
            .ToListAsync(ct);
    }
}

REST Controller

// src/Services/EventCatalog/Api/Controllers/EventsController.cs

[ApiController]
[Route("api/[controller]")]
public class EventsController : ControllerBase
{
    private readonly IMediator _mediator;
    public EventsController(IMediator mediator) => _mediator = mediator;

    // Public — no auth required for browsing
    [HttpGet]
    public async Task<IActionResult> Search(
        [FromQuery] string? city, [FromQuery] string? category,
        [FromQuery] DateTime? from, [FromQuery] int page = 1,
        CancellationToken ct = default)
    {
        var results = await _mediator.Send(new SearchEventsQuery(city, category, from, page), ct);
        return Ok(results);
    }

    [HttpGet("{id:guid}")]
    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
    {
        var ev = await _mediator.Send(new GetEventByIdQuery(id), ct);
        return ev is null ? NotFound() : Ok(ev);
    }

    // Admin only — requires JWT with Admin role
    [HttpPost]
    [Authorize(Roles = "Admin")]
    public async Task<IActionResult> Create([FromBody] CreateEventCommand cmd, CancellationToken ct)
    {
        var id = await _mediator.Send(cmd, ct);
        return CreatedAtAction(nameof(GetById), new { id }, new { id });
    }

    [HttpPost("{id:guid}/publish")]
    [Authorize(Roles = "Admin")]
    public async Task<IActionResult> Publish(Guid id, CancellationToken ct)
    {
        await _mediator.Send(new PublishEventCommand(id), ct);
        return NoContent();
    }
}

Features delivered: UC-01 Browse Events, UC-02 View Event Details, UC-08 Admin Creates Event, UC-09 Admin Publishes Event.

7. Bounded Context 3: Booking Service — DDD + CQRS + Saga

📁 src/Services/Booking/

The Booking service is the most complex. It owns the checkout workflow, acts as the saga orchestrator, enforces seat locking, and publishes all booking-related events.

The Booking Aggregate

// src/Services/Booking/Domain/Aggregates/Booking.cs

public enum BookingStatus { Pending, Confirmed, Cancelled, Refunded }

public class Booking : AggregateRoot<Guid>
{
    public Guid EventId { get; private set; }
    public Guid UserId { get; private set; }
    public string SeatNumber { get; private set; } = null!;
    public decimal TotalAmount { get; private set; }
    public string Currency { get; private set; } = null!;
    public BookingStatus Status { get; private set; }
    public DateTime CreatedAtUtc { get; private set; }
    public DateTime? ConfirmedAtUtc { get; private set; }
    public string? PaymentReference { get; private set; }

    private Booking() { }  // EF Core

    public static Booking Create(Guid eventId, Guid userId, string seatNumber,
        decimal totalAmount, string currency = "USD")
    {
        var booking = new Booking
        {
            Id = Guid.NewGuid(),
            EventId = eventId,
            UserId = userId,
            SeatNumber = seatNumber,
            TotalAmount = totalAmount,
            Currency = currency,
            Status = BookingStatus.Pending,
            CreatedAtUtc = DateTime.UtcNow
        };

        // Raises event — captured by DbContext and written to Outbox
        booking.RaiseDomainEvent(new BookingCreatedEvent(
            booking.Id, eventId, userId, seatNumber, totalAmount, currency));

        return booking;
    }

    public void Confirm(string paymentReference)
    {
        // Guard the invariant — cannot confirm a non-pending booking
        if (Status != BookingStatus.Pending)
            throw new InvalidOperationException(
                $"Cannot confirm booking in status {Status}");

        Status = BookingStatus.Confirmed;
        PaymentReference = paymentReference;
        ConfirmedAtUtc = DateTime.UtcNow;

        RaiseDomainEvent(new BookingConfirmedEvent(Id, EventId, UserId, paymentReference));
    }

    public void Cancel(string reason)
    {
        if (Status == BookingStatus.Cancelled)
            throw new InvalidOperationException("Booking already cancelled");

        Status = BookingStatus.Cancelled;
        RaiseDomainEvent(new BookingCancelledEvent(Id, EventId, UserId, SeatNumber, reason));
    }
}

Domain Events vs Integration Events

// src/Services/Booking/Domain/Events/BookingEvents.cs

// ── Domain Events (in-process, raised by the aggregate) ──────────────────────
public record BookingCreatedEvent(
    Guid BookingId, Guid EventId, Guid UserId,
    string SeatNumber, decimal TotalAmount, string Currency) : DomainEvent;

public record BookingConfirmedEvent(
    Guid BookingId, Guid EventId, Guid UserId,
    string PaymentReference) : DomainEvent;

public record BookingCancelledEvent(
    Guid BookingId, Guid EventId, Guid UserId,
    string SeatNumber, string Reason) : DomainEvent;

// ── Integration Events (cross-service contracts on RabbitMQ) ─────────────────
// These are the PUBLIC API of the Booking bounded context.
// Other services depend on these types — never on domain events directly.

public record BookingCreatedIntegrationEvent(
    Guid BookingId, Guid EventId, Guid UserId,
    string SeatNumber, decimal TotalAmount, string Currency);

public record BookingConfirmedIntegrationEvent(
    Guid BookingId, Guid UserId, string PaymentReference);

public record BookingCancelledIntegrationEvent(
    Guid BookingId, Guid EventId, string SeatNumber, string Reason);

// ── Commands sent to other services ──────────────────────────────────────────
public record ProcessPaymentCommand(
    Guid BookingId, Guid UserId, decimal Amount, string Currency);

public record ReleaseSeatsCommand(Guid EventId, string SeatNumber);
public record IssueTicketCommand(
    Guid BookingId, Guid EventId, Guid UserId, string SeatNumber);

// ── Result event received from Payment service ────────────────────────────────
public record PaymentProcessedEvent(
    Guid BookingId, bool Success,
    string? PaymentReference, string? FailureReason);

CreateBooking Command + Handler

// src/Services/Booking/Application/Commands/CreateBookingCommand.cs

public record CreateBookingCommand(
    Guid EventId, Guid UserId, string SeatNumber,
    decimal TotalAmount, string Currency = "USD") : IRequest<Guid>;

public class CreateBookingCommandValidator : AbstractValidator<CreateBookingCommand>
{
    public CreateBookingCommandValidator()
    {
        RuleFor(x => x.EventId).NotEmpty();
        RuleFor(x => x.UserId).NotEmpty();
        RuleFor(x => x.SeatNumber).NotEmpty().MaximumLength(20);
        RuleFor(x => x.TotalAmount).GreaterThan(0);
        RuleFor(x => x.Currency).NotEmpty().Length(3);
    }
}

public class CreateBookingCommandHandler : IRequestHandler<CreateBookingCommand, Guid>
{
    private readonly IBookingRepository _repo;
    private readonly IUnitOfWork _uow;
    private readonly ISeatLockService _seatLock;

    public CreateBookingCommandHandler(
        IBookingRepository repo, IUnitOfWork uow, ISeatLockService seatLock)
    {
        _repo = repo;
        _uow = uow;
        _seatLock = seatLock;
    }

    public async Task<Guid> Handle(CreateBookingCommand cmd, CancellationToken ct)
    {
        // Step 1 — Acquire Redis distributed lock for this seat
        var locked = await _seatLock.TryLockAsync(
            cmd.EventId, cmd.SeatNumber, TimeSpan.FromMinutes(10), ct);

        if (!locked)
            throw new InvalidOperationException(
                $"Seat {cmd.SeatNumber} is currently held by another user.");

        // Step 2 — Create the aggregate (raises BookingCreatedEvent internally)
        var booking = Booking.Create(
            cmd.EventId, cmd.UserId, cmd.SeatNumber, cmd.TotalAmount, cmd.Currency);

        // Step 3 — Persist aggregate + outbox message in ONE transaction
        _repo.Add(booking);
        await _uow.SaveChangesAsync(ct);
        // ↑ BookingCreatedEvent → OutboxMessage written atomically here

        return booking.Id;
    }
}

Queries — Read Side

// src/Services/Booking/Application/Queries/GetBookingQuery.cs

public record BookingDto(
    Guid Id, Guid EventId, Guid UserId,
    string SeatNumber, decimal TotalAmount, string Currency,
    string Status, DateTime CreatedAtUtc, DateTime? ConfirmedAtUtc);

public record GetBookingByIdQuery(Guid BookingId) : IRequest<BookingDto?>;
public record GetBookingsByUserQuery(Guid UserId) : IRequest<List<BookingDto>>;

public class GetBookingByIdHandler : IRequestHandler<GetBookingByIdQuery, BookingDto?>
{
    private readonly IBookingRepository _repo;
    public GetBookingByIdHandler(IBookingRepository repo) => _repo = repo;

    public async Task<BookingDto?> Handle(GetBookingByIdQuery query, CancellationToken ct)
    {
        var b = await _repo.GetByIdAsync(query.BookingId, ct);
        return b is null ? null : new BookingDto(
            b.Id, b.EventId, b.UserId, b.SeatNumber,
            b.TotalAmount, b.Currency, b.Status.ToString(),
            b.CreatedAtUtc, b.ConfirmedAtUtc);
    }
}

Repository and Unit of Work

// src/Services/Booking/Infrastructure/Persistence/BookingRepository.cs

public class BookingRepository : IBookingRepository
{
    private readonly BookingDbContext _ctx;
    public BookingRepository(BookingDbContext ctx) => _ctx = ctx;

    public async Task<Booking?> GetByIdAsync(Guid id, CancellationToken ct = default) =>
        await _ctx.Bookings.FirstOrDefaultAsync(b => b.Id == id, ct);

    public async Task<List<Booking>> GetByUserIdAsync(Guid userId, CancellationToken ct = default) =>
        await _ctx.Bookings.Where(b => b.UserId == userId).ToListAsync(ct);

    public void Add(Booking booking)    => _ctx.Bookings.Add(booking);
    public void Update(Booking booking) => _ctx.Bookings.Update(booking);
}

public class UnitOfWork : IUnitOfWork
{
    private readonly BookingDbContext _ctx;
    public UnitOfWork(BookingDbContext ctx) => _ctx = ctx;

    public async Task<int> SaveChangesAsync(CancellationToken ct = default) =>
        await _ctx.SaveChangesAsync(ct);
}

DbContext with Outbox Support

// src/Services/Booking/Infrastructure/Persistence/BookingDbContext.cs

public class BookingDbContext : DbContext
{
    public BookingDbContext(DbContextOptions<BookingDbContext> options) : base(options) { }

    public DbSet<Booking> Bookings => Set<Booking>();
    public DbSet<OutboxMessage> OutboxMessages => Set<OutboxMessage>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Booking>(b =>
        {
            b.HasKey(x => x.Id);
            b.Property(x => x.SeatNumber).HasMaxLength(20).IsRequired();
            b.Property(x => x.Currency).HasMaxLength(3).IsRequired();
            b.Property(x => x.TotalAmount).HasColumnType("decimal(18,2)");
            b.Property(x => x.Status).HasConversion<string>();
        });

        modelBuilder.Entity<OutboxMessage>(b =>
        {
            b.HasKey(x => x.Id);
            b.Property(x => x.EventType).HasMaxLength(300);
            b.Property(x => x.RowVersion).IsRowVersion(); // SQL Server ROWVERSION
        });

        // MassTransit saga persistence tables (auto-created by EF migrations)
        modelBuilder.AddInboxStateEntity();
        modelBuilder.AddOutboxMessageEntity();
        modelBuilder.AddOutboxStateEntity();
    }
}

Full DI Wiring in Program.cs

// src/Services/Booking/Api/Program.cs

var builder = WebApplication.CreateBuilder(args);

// ── SQL Server ────────────────────────────────────────────────────────────────
builder.Services.AddDbContext<BookingDbContext>(opts =>
    opts.UseSqlServer(builder.Configuration.GetConnectionString("SqlServer"),
        sql => sql
            .MigrationsAssembly("Booking")
            .EnableRetryOnFailure(5)));          // retries on transient failures

// ── Repositories ──────────────────────────────────────────────────────────────
builder.Services.AddScoped<IBookingRepository, BookingRepository>();
builder.Services.AddScoped<IUnitOfWork, UnitOfWork>();

// ── Redis ─────────────────────────────────────────────────────────────────────
builder.Services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect(builder.Configuration.GetConnectionString("Redis")!));
builder.Services.AddScoped<ISeatLockService, RedisSeatLockService>();

// ── MediatR + pipeline behaviours ─────────────────────────────────────────────
builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssemblyContaining<CreateBookingCommand>();
    cfg.AddOpenBehavior(typeof(ValidationBehaviour<,>));
    cfg.AddOpenBehavior(typeof(LoggingBehaviour<,>));
});
builder.Services.AddValidatorsFromAssemblyContaining<CreateBookingCommandValidator>();

// ── MassTransit + RabbitMQ + Saga ─────────────────────────────────────────────
builder.Services.AddMassTransit(x =>
{
    x.AddSagaStateMachine<BookingSagaStateMachine, BookingSagaState>()
        .EntityFrameworkRepository(r =>
        {
            r.ExistingDbContext<BookingDbContext>();
            r.UseSqlServer();  // saga state persisted in SQL Server
        });

    x.SetKebabCaseEndpointNameFormatter();

    x.UsingRabbitMq((ctx, cfg) =>
    {
        cfg.Host(builder.Configuration["RabbitMQ:Host"], "/", h =>
        {
            h.Username(builder.Configuration["RabbitMQ:Username"]!);
            h.Password(builder.Configuration["RabbitMQ:Password"]!);
        });
        cfg.ConfigureEndpoints(ctx);
    });
});

// ── JWT Auth ──────────────────────────────────────────────────────────────────
builder.Services.AddAuthentication("Bearer")
    .AddJwtBearer("Bearer", opts =>
    {
        opts.Authority = builder.Configuration["Identity:Authority"];
        opts.Audience  = "booking-api";
    });

builder.Services.AddControllers();
builder.Services.AddHealthChecks()
    .AddSqlServer(builder.Configuration.GetConnectionString("SqlServer")!)
    .AddRedis(builder.Configuration.GetConnectionString("Redis")!);

var app = builder.Build();

// Auto-migrate on startup — idempotent
using (var scope = app.Services.CreateScope())
    await scope.ServiceProvider
        .GetRequiredService<BookingDbContext>().Database.MigrateAsync();

app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.MapHealthChecks("/health");
app.Run();

Features delivered: UC-03 Reserve Seat, UC-05 Confirm Booking, UC-06 Cancel on Failure, UC-07 View My Bookings, UC-10 Session Abandonment.

8. Bounded Context 4: Payment Service

📁 src/Services/Payment/

The Payment service has no HTTP endpoints exposed to users. It is a pure event consumer — it listens for ProcessPaymentCommand from the Booking saga, charges the customer, and publishes PaymentProcessedEvent back.

The Payment Aggregate

// src/Services/Payment/Domain/Aggregates/Payment.cs

public enum PaymentStatus { Pending, Succeeded, Failed, Refunded }

public class Payment : AggregateRoot<Guid>
{
    public Guid BookingId { get; private set; }
    public decimal Amount { get; private set; }
    public string Currency { get; private set; } = null!;
    public PaymentStatus Status { get; private set; }
    public string? PspReference { get; private set; }   // Stripe PaymentIntent ID
    public string? FailureReason { get; private set; }

    private Payment() { }

    public static Payment Create(Guid bookingId, Guid userId, decimal amount, string currency)
    {
        var p = new Payment
        {
            Id = Guid.NewGuid(), BookingId = bookingId,
            Amount = amount, Currency = currency,
            Status = PaymentStatus.Pending, CreatedAtUtc = DateTime.UtcNow
        };
        p.RaiseDomainEvent(new PaymentInitiatedEvent(p.Id, bookingId, amount));
        return p;
    }

    public void Succeed(string pspReference)
    {
        Status = PaymentStatus.Succeeded;
        PspReference = pspReference;
        RaiseDomainEvent(new PaymentSucceededEvent(Id, BookingId, pspReference));
    }

    public void Fail(string reason)
    {
        Status = PaymentStatus.Failed;
        FailureReason = reason;
        RaiseDomainEvent(new PaymentFailedEvent(Id, BookingId, reason));
    }
}

RabbitMQ Consumer

// src/Services/Payment/Infrastructure/Messaging/ProcessPaymentConsumer.cs

public class ProcessPaymentConsumer : IConsumer<ProcessPaymentCommand>
{
    private readonly PaymentDbContext _ctx;
    private readonly IStripeService _stripe;

    public ProcessPaymentConsumer(PaymentDbContext ctx, IStripeService stripe)
    {
        _ctx = ctx;
        _stripe = stripe;
    }

    public async Task Consume(ConsumeContext<ProcessPaymentCommand> context)
    {
        var cmd = context.Message;

        // Create the payment aggregate
        var payment = Payment.Create(cmd.BookingId, cmd.UserId, cmd.Amount, cmd.Currency);
        _ctx.Payments.Add(payment);

        try
        {
            // Call PSP — swap IStripeService for real Stripe SDK in production
            var pspRef = await _stripe.ChargeAsync(cmd.Amount, cmd.Currency);
            payment.Succeed(pspRef);
        }
        catch (Exception ex)
        {
            payment.Fail(ex.Message);
        }

        await _ctx.SaveChangesAsync(context.CancellationToken);

        // Publish result back — the Booking saga is waiting for this
        await context.Publish(new PaymentProcessedEvent(
            cmd.BookingId,
            payment.Status == PaymentStatus.Succeeded,
            payment.PspReference,
            payment.FailureReason));
    }
}

// Stripe adapter — swap for real Stripe.net SDK in production
public class StripeService : IStripeService
{
    public async Task<string> ChargeAsync(decimal amount, string currency)
    {
        await Task.Delay(100); // simulate PSP round-trip
        return $"pi_{Guid.NewGuid():N}";
    }
}

Features delivered: UC-04 Process Payment, UC-06 Payment Failure Compensation.

9. Bounded Context 5: Notification Service

📁 src/Services/Notification/

The Notification service is the simplest — a pure event consumer with no domain logic and no database. It reacts to integration events and dispatches messages to users.

// src/Services/Notification/Application/Consumers/BookingConsumers.cs

public class BookingConfirmedConsumer : IConsumer<BookingConfirmedIntegrationEvent>
{
    private readonly IEmailService _email;
    private readonly ILogger<BookingConfirmedConsumer> _logger;

    public BookingConfirmedConsumer(IEmailService email,
        ILogger<BookingConfirmedConsumer> logger)
    { _email = email; _logger = logger; }

    public async Task Consume(ConsumeContext<BookingConfirmedIntegrationEvent> ctx)
    {
        _logger.LogInformation("Sending confirmation for booking {BookingId}",
            ctx.Message.BookingId);

        await _email.SendAsync(
            to:      $"user-{ctx.Message.UserId}@example.com",
            subject: "Your ticket is confirmed! 🎟️",
            body:    $"Booking {ctx.Message.BookingId} confirmed. " +
                     $"Payment reference: {ctx.Message.PaymentReference}");
    }
}

public class BookingCancelledConsumer : IConsumer<BookingCancelledIntegrationEvent>
{
    private readonly IEmailService _email;
    public BookingCancelledConsumer(IEmailService email) => _email = email;

    public async Task Consume(ConsumeContext<BookingCancelledIntegrationEvent> ctx)
    {
        await _email.SendAsync(
            to:      $"user-{ctx.Message.BookingId}@example.com",
            subject: "Booking cancelled",
            body:    $"Your booking {ctx.Message.BookingId} was cancelled. " +
                     $"Reason: {ctx.Message.Reason}. " +
                     $"Your seat {ctx.Message.SeatNumber} has been released.");
    }
}

// Swap for SendGrid / SMTP / AWS SES in production
public class SmtpEmailService : IEmailService
{
    private readonly ILogger<SmtpEmailService> _logger;
    public SmtpEmailService(ILogger<SmtpEmailService> logger) => _logger = logger;

    public Task SendAsync(string to, string subject, string body)
    {
        _logger.LogInformation("EMAIL → {To} | {Subject}", to, subject);
        return Task.CompletedTask;
    }
}

Features delivered: UC-05 Confirmation Email, UC-06 Cancellation Email.

10. The API Gateway — YARP

📁 src/ApiGateway/

YARP (Yet Another Reverse Proxy) acts as the single entry point for all client traffic. It validates JWTs, applies rate limiting, and routes to the correct downstream service — with zero business logic.

// src/ApiGateway/Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

// Validate JWTs at the gateway edge — downstream services trust forwarded tokens
builder.Services.AddAuthentication("Bearer")
    .AddJwtBearer("Bearer", opts =>
    {
        opts.Authority = builder.Configuration["Identity:Authority"];
        opts.RequireHttpsMetadata = false;
    });

builder.Services.AddAuthorization(opts =>
    opts.AddPolicy("default", p => p.RequireAuthenticatedUser()));

// 300 requests/minute per client — protects downstream services
builder.Services.AddRateLimiter(opts =>
    opts.AddFixedWindowLimiter("api", cfg =>
    {
        cfg.Window      = TimeSpan.FromMinutes(1);
        cfg.PermitLimit = 300;
        cfg.QueueLimit  = 0;
    }));

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.MapReverseProxy();
app.MapHealthChecks("/health");
app.Run();

// src/ApiGateway/appsettings.json — declarative routing, no code changes needed

{
  "ReverseProxy": {
    "Routes": {
      "events-route": {
        "ClusterId": "eventcatalog",
        "Match": { "Path": "/api/events/{**catch-all}" }
      },
      "bookings-route": {
        "ClusterId": "booking",
        "Match": { "Path": "/api/bookings/{**catch-all}" },
        "AuthorizationPolicy": "default"
      },
      "payments-route": {
        "ClusterId": "payment",
        "Match": { "Path": "/api/payments/{**catch-all}" },
        "AuthorizationPolicy": "default"
      }
    },
    "Clusters": {
      "eventcatalog": {
        "Destinations": { "d1": { "Address": "http://eventcatalog:8080/" } }
      },
      "booking": {
        "Destinations": { "d1": { "Address": "http://booking:8080/" } }
      },
      "payment": {
        "Destinations": { "d1": { "Address": "http://payment:8080/" } }
      }
    }
  }
}

11. Event-Driven Architecture Deep Dive

Why Two Kinds of Events?

The system uses two distinct event types with very different concerns:

Domain Event                          Integration Event
─────────────────────────────────     ──────────────────────────────────
In-process only                       Cross-service, via RabbitMQ
Synchronous, raised during tx         Asynchronous, published after tx
Rich domain type                      Minimal DTO (only what others need)
Cleared after SaveChanges             Persisted in outbox until delivered
Never leaves the aggregate's context  Public API of the bounded context

Event Flow Diagram

┌────────────────────────────────────────────────────────────────────┐
│  Booking Service                                                   │
│                                                                    │
│  booking.Create() ──raises──▶ BookingCreatedEvent (domain)        │
│                                        │                           │
│  DbContext.SaveChangesAsync()          │                           │
│    ├── writes Booking row              │                           │
│    ├── converts domain event ──────────┘                           │
│    └── writes OutboxMessage row                                    │
│                    │ (same transaction — atomic)                   │
│                    │                                               │
│  OutboxProcessor   │                                               │
│    polls every 5s  │                                               │
│    reads unprocessed OutboxMessages                                │
│    publishes ──────▶ RabbitMQ ──▶ BookingCreatedIntegrationEvent  │
│    marks ProcessedOnUtc                                            │
└────────────────────────────────────────────────────────────────────┘

RabbitMQ
  Exchange: booking-created-integration-event
  Queue:    booking-saga (BookingSagaStateMachine)
  Queue:    notification (BookingConfirmedConsumer)

MassTransit Consumer Registration

All consumers and sagas are auto-registered by endpoint name formatter — no manual queue configuration:

x.SetKebabCaseEndpointNameFormatter();
// BookingConfirmedConsumer → queue: booking-confirmed-consumer
// BookingSagaStateMachine  → queue: booking-saga-state-machine

x.UsingRabbitMq((ctx, cfg) =>
{
    cfg.Host("rabbitmq", "/", h =>
    {
        h.Username("ticketing");
        h.Password("ticketing_pass");
    });
    cfg.ConfigureEndpoints(ctx); // ← auto-creates all queues + bindings
});

12. The Booking Saga — Distributed Workflow

📁 src/Services/Booking/Application/Sagas/BookingSagaStateMachine.cs

The saga orchestrates the multi-service checkout workflow. Its state is persisted to SQL Server so it survives process restarts.

State Machine Diagram

                    ┌─────────────────────────────────┐
                    │         BookingSagaState         │
                    │                                  │
  BookingCreated ──▶│  Initial ──▶ AwaitingPayment    │
                    │                 │                │
  PaymentProcessed  │        Success ─┤                │
  (Success = true) ▶│                 │──▶ Completed  │
                    │                 │                │
  PaymentProcessed  │        Failure ─┤                │
  (Success = false)▶│                 │──▶ Failed     │
                    └─────────────────────────────────┘

  On Completed: Publish IssueTicketCommand
                Publish BookingConfirmedIntegrationEvent

  On Failed:    Publish ReleaseSeatsCommand (compensate)
                Publish BookingCancelledIntegrationEvent

// src/Services/Booking/Application/Sagas/BookingSagaStateMachine.cs

public class BookingSagaState : SagaStateMachineInstance
{
    public Guid CorrelationId { get; set; }   // = BookingId — ties all messages together
    public string CurrentState { get; set; } = null!;
    public Guid EventId { get; set; }
    public Guid UserId { get; set; }
    public string SeatNumber { get; set; } = null!;
    public decimal TotalAmount { get; set; }
    public string Currency { get; set; } = null!;
    public string? PaymentReference { get; set; }
    public string? FailureReason { get; set; }
    public DateTime CreatedAt { get; set; }
}

public class BookingSagaStateMachine : MassTransitStateMachine<BookingSagaState>
{
    public State AwaitingPayment { get; private set; } = null!;
    public State Completed { get; private set; } = null!;
    public State Failed { get; private set; } = null!;

    public Event<BookingCreatedIntegrationEvent> BookingCreated { get; private set; } = null!;
    public Event<PaymentProcessedEvent> PaymentCompleted { get; private set; } = null!;

    public BookingSagaStateMachine()
    {
        InstanceState(x => x.CurrentState);

        // Correlation: all events for one booking share the same BookingId
        Event(() => BookingCreated,
            x => x.CorrelateById(ctx => ctx.Message.BookingId));
        Event(() => PaymentCompleted,
            x => x.CorrelateById(ctx => ctx.Message.BookingId));

        Initially(
            When(BookingCreated)
                .Then(ctx =>
                {
                    // Store all data we'll need later in the saga state
                    ctx.Saga.EventId     = ctx.Message.EventId;
                    ctx.Saga.UserId      = ctx.Message.UserId;
                    ctx.Saga.SeatNumber  = ctx.Message.SeatNumber;
                    ctx.Saga.TotalAmount = ctx.Message.TotalAmount;
                    ctx.Saga.Currency    = ctx.Message.Currency;
                    ctx.Saga.CreatedAt   = DateTime.UtcNow;
                })
                // Command the Payment service to charge the customer
                .Publish(ctx => new ProcessPaymentCommand(
                    ctx.Saga.CorrelationId,
                    ctx.Saga.UserId,
                    ctx.Saga.TotalAmount,
                    ctx.Saga.Currency))
                .TransitionTo(AwaitingPayment));

        During(AwaitingPayment,

            // ── Happy path ─────────────────────────────────────────────────────
            When(PaymentCompleted, ctx => ctx.Message.Success)
                .Then(ctx => ctx.Saga.PaymentReference = ctx.Message.PaymentReference)
                // Tell EventCatalog to decrement available seats permanently
                .Publish(ctx => new IssueTicketCommand(
                    ctx.Saga.CorrelationId,
                    ctx.Saga.EventId,
                    ctx.Saga.UserId,
                    ctx.Saga.SeatNumber))
                // Notify all subscribers (Notification service sends email)
                .Publish(ctx => new BookingConfirmedIntegrationEvent(
                    ctx.Saga.CorrelationId,
                    ctx.Saga.UserId,
                    ctx.Saga.PaymentReference!))
                .TransitionTo(Completed)
                .Finalize(),

            // ── Compensating path — payment failed ─────────────────────────────
            When(PaymentCompleted, ctx => !ctx.Message.Success)
                .Then(ctx => ctx.Saga.FailureReason = ctx.Message.FailureReason)
                // Release the Redis seat lock so others can book
                .Publish(ctx => new ReleaseSeatsCommand(
                    ctx.Saga.EventId, ctx.Saga.SeatNumber))
                // Notify all subscribers (Notification sends failure email)
                .Publish(ctx => new BookingCancelledIntegrationEvent(
                    ctx.Saga.CorrelationId,
                    ctx.Saga.EventId,
                    ctx.Saga.SeatNumber,
                    ctx.Saga.FailureReason ?? "Payment failed"))
                .TransitionTo(Failed)
                .Finalize());

        SetCompletedWhenFinalized();
    }
}

13. The Outbox Pattern — Guaranteed Delivery

Without the outbox, there is a window between saving the booking to the database and publishing the event to RabbitMQ where a crash loses the message permanently. The outbox closes that window.

// src/SharedKernel/Infrastructure/OutboxMessage.cs

public class OutboxMessage
{
    public Guid Id { get; set; } = Guid.NewGuid();
    public string EventType { get; set; } = null!;     // full CLR type name
    public string Payload { get; set; } = null!;       // JSON-serialised event
    public DateTime OccurredOnUtc { get; set; } = DateTime.UtcNow;
    public DateTime? ProcessedOnUtc { get; set; }      // null = not yet published
    public string? Error { get; set; }

    [Timestamp]   // SQL Server ROWVERSION — optimistic concurrency for processor
    public byte[] RowVersion { get; set; } = null!;
}

The flow in sequence:

1. Command handler calls _uow.SaveChangesAsync()
        │
        ├── EF writes Booking row          ─┐
        └── EF writes OutboxMessage row    ─┘  one ACID transaction

2. OutboxProcessor (IHostedService) polls every 5 seconds:
        SELECT TOP 10 * FROM OutboxMessages
        WHERE ProcessedOnUtc IS NULL
        ORDER BY OccurredOnUtc

3. For each message:
        a. Deserialize Payload to the event type
        b. Publish to RabbitMQ via IPublishEndpoint
        c. UPDATE OutboxMessages SET ProcessedOnUtc = GETUTCDATE()
               WHERE Id = @id AND RowVersion = @rowVersion
           (optimistic concurrency — prevents double-publish if two instances race)

4. If RabbitMQ is down:
        OutboxProcessor retries on next poll cycle
        Booking data is safe — it was committed in step 1

This pattern guarantees at-least-once delivery. Consumers must be idempotent (or use an inbox table to deduplicate).

14. Redis Seat Locking — Preventing Overselling

// src/Services/Booking/Infrastructure/RedisSeatLockService.cs

public class RedisSeatLockService : ISeatLockService
{
    private readonly IDatabase _redis;
    public RedisSeatLockService(IConnectionMultiplexer redis) =>
        _redis = redis.GetDatabase();

    public async Task<bool> TryLockAsync(
        Guid eventId, string seat, TimeSpan ttl, CancellationToken ct = default)
    {
        // Redis SET key value NX EX seconds
        // NX = only set if key does NOT exist (atomic test-and-set)
        // Returns true  = lock acquired (key was not present)
        // Returns false = lock NOT acquired (another user holds it)
        var key = $"seat-lock:{eventId}:{seat}";
        return await _redis.StringSetAsync(key, "locked", ttl, When.NotExists);
    }

    public async Task ReleaseAsync(Guid eventId, string seat, CancellationToken ct = default)
    {
        var key = $"seat-lock:{eventId}:{seat}";
        await _redis.KeyDeleteAsync(key);
    }
}

Why Redis instead of a database lock?

Approach	Throughput	Scope	TTL support
SQL `SELECT FOR UPDATE`	Low (row lock, connection held)	Single DB	No
Optimistic concurrency	Medium (retries on conflict)	Single DB	No
Redis SET NX	Very high (microsecond op, connection pool)	Distributed	✅ Yes

The TTL (10 minutes) acts as a safety valve — if a user abandons checkout or their browser crashes, the seat is automatically available again after 10 minutes. No scheduled cleanup job needed.

15. The Angular Frontend — NgRx Architecture

📁 frontend/src/app/

The frontend follows the Redux pattern via NgRx: all state is in the store, all side effects (HTTP calls, navigation) are in Effects, all views are driven by Selectors.

Application Bootstrap

// frontend/src/app/app.config.ts

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient(withInterceptors([authInterceptor, errorInterceptor])),
    // NgRx store slices
    provideStore({
      events:  eventsReducer,
      booking: bookingReducer,
      auth:    authReducer
    }),
    provideEffects([EventsEffects, BookingEffects, AuthEffects]),
    provideRouterStore(),
    provideStoreDevtools({ maxAge: 25 }),
    importProvidersFrom(OAuthModule.forRoot()),
  ]
};

Lazy-Loaded Feature Routes

// frontend/src/app/app.routes.ts

export const routes: Routes = [
  { path: '',       redirectTo: 'events', pathMatch: 'full' },
  {
    path: 'events',
    loadChildren: () => import('./features/events/events.routes')
      .then(m => m.EVENTS_ROUTES)
    // No auth required — browse without login
  },
  {
    path: 'booking',
    loadChildren: () => import('./features/booking/booking.routes')
      .then(m => m.BOOKING_ROUTES),
    canActivate: [authGuard]  // JWT required
  },
  {
    path: 'account',
    loadChildren: () => import('./features/account/account.routes')
      .then(m => m.ACCOUNT_ROUTES),
    canActivate: [authGuard]
  },
  {
    path: 'admin',
    loadChildren: () => import('./features/admin/admin.routes')
      .then(m => m.ADMIN_ROUTES),
    canActivate: [authGuard],
    data: { roles: ['Admin'] }
  },
];

NgRx Booking Store

// frontend/src/app/store/booking/booking.reducer.ts

export interface BookingState {
  currentBookingId: string | null;
  myBookings: Booking[];
  loading: boolean;
  error: string | null;
}

export const BookingActions = {
  createBooking: createAction('[Booking] Create',
    props<{ eventId: string; seatNumber: string; totalAmount: number }>()),
  createBookingSuccess: createAction('[Booking] Create Success',
    props<{ bookingId: string }>()),
  createBookingFailure: createAction('[Booking] Create Failure',
    props<{ error: string }>()),
  loadMyBookings: createAction('[Booking] Load My Bookings',
    props<{ userId: string }>()),
  loadMyBookingsSuccess: createAction('[Booking] Load My Bookings Success',
    props<{ bookings: Booking[] }>()),
};

// Pure reducer — no side effects, easy to test
export const bookingReducer = createReducer(initialState,
  on(BookingActions.createBooking,
    s => ({ ...s, loading: true, error: null })),
  on(BookingActions.createBookingSuccess,
    (s, { bookingId }) => ({ ...s, currentBookingId: bookingId, loading: false })),
  on(BookingActions.createBookingFailure,
    (s, { error }) => ({ ...s, loading: false, error })),
  on(BookingActions.loadMyBookingsSuccess,
    (s, { bookings }) => ({ ...s, myBookings: bookings })),
);

Effects — HTTP Side Effects

@Injectable()
export class BookingEffects {

  createBooking$ = createEffect(() => this.actions$.pipe(
    ofType(BookingActions.createBooking),
    switchMap(({ eventId, seatNumber, totalAmount }) =>
      this.http.post<{ id: string }>(`${environment.apiUrl}/api/bookings`, {
        eventId, seatNumber, totalAmount, currency: 'USD'
      }).pipe(
        map(res  => BookingActions.createBookingSuccess({ bookingId: res.id })),
        catchError(err => of(BookingActions.createBookingFailure({ error: err.message })))
      )
    )
  ));

  loadMyBookings$ = createEffect(() => this.actions$.pipe(
    ofType(BookingActions.loadMyBookings),
    switchMap(({ userId }) =>
      this.http.get<Booking[]>(`${environment.apiUrl}/api/bookings/user/${userId}`).pipe(
        map(bookings => BookingActions.loadMyBookingsSuccess({ bookings })),
        catchError(() => of(BookingActions.loadMyBookingsSuccess({ bookings: [] })))
      )
    )
  ));

  constructor(private actions$: Actions, private http: HttpClient) {}
}

Auth Guard & Interceptor

// frontend/src/app/core/guards/auth.guard.ts

export const authGuard: CanActivateFn = () => {
  const auth   = inject(AuthService);
  const router = inject(Router);
  if (auth.isLoggedIn) return true;
  auth.login();   // redirect to IdentityServer PKCE flow
  return false;
};

// frontend/src/app/core/interceptors/auth.interceptor.ts

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const auth = inject(AuthService);
  if (auth.accessToken) {
    req = req.clone({
      setHeaders: { Authorization: `Bearer ${auth.accessToken}` }
    });
  }
  return next(req);
};

export const errorInterceptor: HttpInterceptorFn = (req, next) =>
  next(req).pipe(
    catchError(err => {
      if (err.status === 401) inject(AuthService).login();
      return throwError(() => err);
    })
  );

Event List Component — Search & Browse

// frontend/src/app/features/events/event-list.component.ts

@Component({
  selector: 'app-event-list',
  standalone: true,
  imports: [CommonModule, ReactiveFormsModule, RouterModule],
  template: `
    <div class="events-container">
      <h1>Upcoming Events</h1>

      <form [formGroup]="filterForm" (ngSubmit)="search()" class="filters">
        <input formControlName="city"     placeholder="City" />
        <select formControlName="category">
          <option value="">All categories</option>
          <option value="Concert">Concert</option>
          <option value="Sports">Sports</option>
          <option value="Theater">Theater</option>
        </select>
        <input formControlName="from" type="date" />
        <button type="submit">Search</button>
      </form>

      <div *ngIf="loading$ | async" class="loading">Loading events...</div>

      <div class="event-grid">
        <div *ngFor="let event of events$ | async" class="event-card">
          <div class="event-category">{{ event.category }}</div>
          <h2>{{ event.title }}</h2>
          <p class="event-meta">
              {{ event.venue }}, {{ event.city }}<br/>
              {{ event.startsAtUtc | date:'medium' }}
          </p>
          <div class="event-footer">
            <span class="price">
              From {{ event.basePrice | currency:event.currency }}
            </span>
            <span class="seats">{{ event.availableSeats }} seats left</span>
            <a [routerLink]="['/events', event.id]" class="btn-primary">
              View Tickets
            </a>
          </div>
        </div>
      </div>
    </div>
  `
})
export class EventListComponent implements OnInit {
  events$  = this.store.select(selectAllEvents);
  loading$ = this.store.select(selectEventsLoading);
  filterForm = this.fb.group({ city: [''], category: [''], from: [''] });

  constructor(private store: Store, private fb: FormBuilder) {}

  ngOnInit() { this.search(); }

  search() {
    const { city, category, from } = this.filterForm.value;
    this.store.dispatch(EventActions.search({
      city:     city     || undefined,
      category: category || undefined,
      from:     from     || undefined,
    }));
  }
}

Admin Event Management Component

// frontend/src/app/features/admin/admin-events.component.ts (excerpt)

export class AdminEventsComponent implements OnInit {
  createForm = this.fb.group({
    title:       ['', [Validators.required, Validators.maxLength(200)]],
    description: ['', Validators.required],
    category:    ['Concert', Validators.required],
    venue:       ['', Validators.required],
    city:        ['', Validators.required],
    startsAtUtc: ['', Validators.required],
    basePrice:   [0,  [Validators.required, Validators.min(0)]],
    currency:    ['USD', [Validators.required, Validators.minLength(3)]],
    totalSeats:  [100, [Validators.required, Validators.min(1)]],
  });

  createEvent() {
    if (this.createForm.invalid) return;
    this.saving = true;
    this.http.post(`${environment.apiUrl}/api/events`, this.createForm.value)
      .subscribe({
        next: () => {
          this.successMessage = 'Event created!';
          this.loadEvents();
          this.saving = false;
        },
        error: err => {
          this.errorMessage = err.error?.message ?? 'Failed to create event';
          this.saving = false;
        }
      });
  }

  publishEvent(id: string) {
    this.http.post(`${environment.apiUrl}/api/events/${id}/publish`, {})
      .subscribe({ next: () => this.loadEvents() });
  }
}

16. All Features & Use Cases — End to End

Feature Matrix

#	Feature	Actor	Services involved	Pattern
UC-01	Browse & search events	Anonymous	EventCatalog	Query
UC-02	View event details & seat map	Anonymous	EventCatalog	Query
UC-03	Reserve a seat	User	Booking, Redis	Command + Redis Lock
UC-04	Process payment	System	Payment → Booking	Event Consumer
UC-05	Confirm booking & issue ticket	System	Booking, Notification	Saga + Event
UC-06	Cancel on payment failure	System	Booking, EventCatalog, Notification	Saga + Compensation
UC-07	View my ticket history	User	Booking	Query
UC-08	Admin create event (draft)	Admin	EventCatalog	Command
UC-09	Admin publish event	Admin	EventCatalog	Command
UC-10	Session abandonment / timeout	System	Redis	TTL auto-release
UC-11	Rate limiting	System	ApiGateway	Fixed window 300/min
UC-12	Token refresh	User	Identity, Angular	Silent refresh OIDC

UC-01 & UC-02: Browse & View Events

GET /api/events?city=London&category=Concert&page=1
          │
API Gateway (no auth required for this route)
          │
EventCatalog: SearchEventsQuery dispatched via MediatR
          │
ValidationBehaviour → LoggingBehaviour → SearchEventsHandler
          │
EF Core: SELECT * FROM Events WHERE IsPublished=1
         AND City='London' AND Category='Concert'
         ORDER BY StartsAtUtc
         OFFSET 0 ROWS FETCH NEXT 20 ROWS ONLY
          │
Returns List<EventDto> → 200 OK

UC-03: Reserve a Seat (Full Journey)

POST /api/bookings
{ "eventId": "...", "seatNumber": "A12", "totalAmount": 99.99 }
          │
API Gateway: JWT validated → route to Booking:8080
          │
BookingsController.Create()
          │
MediatR: CreateBookingCommand dispatched
          │
ValidationBehaviour: all fields validated
LoggingBehaviour: "Handling CreateBookingCommand" logged
          │
CreateBookingCommandHandler:
  1. Redis: SETNX seat-lock:{eventId}:A12 "locked" EX 600
       → true: lock acquired, continue
       → false: throw "Seat held by another user" → 409 Conflict
  2. Booking.Create() → Status=Pending, raises BookingCreatedEvent
  3. _repo.Add(booking)
  4. _uow.SaveChangesAsync():
       ├── INSERT INTO Bookings ...
       └── INSERT INTO OutboxMessages (EventType, Payload, OccurredOnUtc)
           (same transaction)
  5. Return booking.Id → 201 Created

Background (OutboxProcessor polls every 5 seconds):
  SELECT TOP 10 FROM OutboxMessages WHERE ProcessedOnUtc IS NULL
  → Deserialize BookingCreatedEvent
  → Publish BookingCreatedIntegrationEvent to RabbitMQ
  → UPDATE OutboxMessages SET ProcessedOnUtc = NOW()

RabbitMQ → BookingSagaStateMachine:
  Initially: receives BookingCreated
  → stores saga state to SQL Server
  → publishes ProcessPaymentCommand
  → transitions to AwaitingPayment

UC-04 & UC-05: Payment Processing & Confirmation

RabbitMQ → ProcessPaymentConsumer (Payment Service):
  Payment.Create(bookingId, userId, amount, currency)
  → StripeService.ChargeAsync(99.99, "USD")
  → payment.Succeed("pi_3Nxxxx")
  → INSERT INTO Payments ...
  → Publish PaymentProcessedEvent(Success=true, PspReference="pi_3Nxxxx")

RabbitMQ → BookingSagaStateMachine:
  During AwaitingPayment, PaymentCompleted(Success=true):
  → saga.PaymentReference = "pi_3Nxxxx"
  → Publish IssueTicketCommand (EventCatalog decrements AvailableSeats)
  → Publish BookingConfirmedIntegrationEvent
  → Transition to Completed → Finalize

RabbitMQ → BookingConfirmedConsumer (Notification Service):
  Receive BookingConfirmedIntegrationEvent
  → IEmailService.SendAsync(
       to: "user@example.com",
       subject: "Your ticket is confirmed! 🎟️",
       body: "Booking abc123 confirmed. Payment: pi_3Nxxxx")

UC-06: Payment Failure & Compensation

RabbitMQ → ProcessPaymentConsumer (Payment Service):
  payment.Fail("Insufficient funds")
  → INSERT INTO Payments (Status='Failed', FailureReason='...')
  → Publish PaymentProcessedEvent(Success=false, FailureReason="Insufficient funds")

RabbitMQ → BookingSagaStateMachine:
  During AwaitingPayment, PaymentCompleted(Success=false):
  → Publish ReleaseSeatsCommand:
       Redis DEL seat-lock:{eventId}:A12  ← seat available again
       EventCatalog: event.ReleaseSeat()   ← AvailableSeats++
  → Publish BookingCancelledIntegrationEvent
  → Transition to Failed → Finalize

RabbitMQ → BookingCancelledConsumer (Notification Service):
  Receive BookingCancelledIntegrationEvent
  → IEmailService.SendAsync(
       subject: "Booking cancelled",
       body: "Your booking was cancelled. Reason: Insufficient funds.
              Seat A12 has been released.")

UC-07: View My Ticket History

GET /api/bookings/user/{userId}
          │
API Gateway: JWT validated
          │
BookingsController.GetByUser()
          │
MediatR: GetBookingsByUserQuery
          │
GetBookingsByUserHandler:
  EF Core: SELECT * FROM Bookings WHERE UserId = @userId
          │
Returns List<BookingDto> with status, seat, amount, timestamps

UC-08 & UC-09: Admin Creates & Publishes Event

POST /api/events (requires Admin role in JWT)
{ "title": "Coldplay Live", "category": "Concert", "totalSeats": 500 ... }
          │
EventsController: [Authorize(Roles = "Admin")]
          │
MediatR: CreateEventCommand
          │
CreateEventValidator: all fields validated
          │
CreateEventHandler:
  Event.Create(...)  → IsPublished=false (always draft)
  → INSERT INTO Events ...
          │
Returns 201 Created with event.Id

POST /api/events/{id}/publish (Admin only)
          │
PublishEventCommand
          │
event.Publish() → IsPublished=true
          │
Event now appears in search results (WHERE IsPublished=1)

UC-10: Session Abandonment / Timeout

User starts checkout → seat locked in Redis (TTL: 10 minutes)
User closes browser / session expires
          │
Redis TTL expires automatically after 10 minutes:
  DEL seat-lock:{eventId}:{seat}
          │
No cleanup job needed.
Seat becomes available again for the next customer.

If payment was already initiated (saga in AwaitingPayment):
  → Saga timeout (configurable) triggers compensation
  → ReleaseSeatsCommand published
  → BookingCancelledIntegrationEvent published

UC-11: Rate Limiting (Gateway)

Client sends >300 requests/minute to any /api/** route
          │
YARP RateLimiter middleware:
  AddFixedWindowLimiter("api", window=1min, permitLimit=300)
          │
→ 429 Too Many Requests returned immediately
  Downstream services are protected — they never see the request

UC-12: Token Refresh (Silent OIDC)

Angular SPA: access token approaching expiry
          │
angular-oauth2-oidc: setupAutomaticSilentRefresh()
  → silent iframe to Identity service
  → Identity issues new access token via refresh flow
  → OAuthService.accessToken updated
          │
Next HTTP request automatically carries fresh token via authInterceptor
No user interaction required

17. Infrastructure: Docker Compose & SQL Server

📁 docker-compose.yml

name: ticketing-system

services:
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "${SA_PASSWORD}"
    ports: ["1433:1433"]
    volumes: [sqlserver_data:/var/opt/mssql]
    healthcheck:
      test: ["CMD", "/opt/mssql-tools18/bin/sqlcmd",
             "-S", "localhost", "-U", "sa", "-P", "${SA_PASSWORD}",
             "-Q", "SELECT 1", "-No"]
      interval: 15s
      retries: 10
      start_period: 30s    # MSSQL needs time to initialise

  rabbitmq:
    image: rabbitmq:3.13-management-alpine
    environment:
      RABBITMQ_DEFAULT_USER: "${RABBITMQ_USER}"
      RABBITMQ_DEFAULT_PASS: "${RABBITMQ_PASS}"
    ports:
      - "5672:5672"
      - "15672:15672"      # Management UI → http://localhost:15672
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      interval: 15s
      retries: 10

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    ports: ["6379:6379"]

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"      # Jaeger UI → http://localhost:16686
      - "4317:4317"        # OTLP gRPC

  booking:
    build:
      context: .
      dockerfile: src/Services/Booking/Dockerfile
    environment:
      ASPNETCORE_URLS: http://+:8080
      ConnectionStrings__SqlServer: >
        Server=sqlserver,1433;Database=TicketingSystem_Booking;
        User Id=sa;Password=${SA_PASSWORD};TrustServerCertificate=true
      ConnectionStrings__Redis: "redis:6379,password=${REDIS_PASSWORD}"
      RabbitMQ__Host: rabbitmq
      RabbitMQ__Username: "${RABBITMQ_USER}"
      RabbitMQ__Password: "${RABBITMQ_PASS}"
    ports: ["5003:8080"]
    depends_on:
      sqlserver: { condition: service_healthy }
      rabbitmq:  { condition: service_healthy }
      redis:     { condition: service_healthy }

  # ... identity, eventcatalog, payment, notification, gateway, frontend
  # Full file: https://github.com/naimulkarim/TicketingSystem/blob/main/docker-compose.yml

volumes:
  sqlserver_data:
  rabbitmq_data:
  redis_data:

Local endpoint reference:

Service	URL	Notes
Frontend SPA	http://localhost:4200	Angular
API Gateway	http://localhost:5000	All API calls go here
Identity	http://localhost:5001	OIDC discovery at /.well-known/openid-configuration
Event Catalog	http://localhost:5002	Swagger at /swagger
Booking	http://localhost:5003	Swagger at /swagger
Payment	http://localhost:5004	Internal only
Notification	http://localhost:5005	Internal only
RabbitMQ UI	http://localhost:15672	user: ticketing / ticketing_pass
Jaeger UI	http://localhost:16686	Distributed traces

18. CI/CD: GitHub Actions Pipeline

📁 .github/workflows/ci.yml

name: CI

on:
  push:         { branches: [main, develop] }
  pull_request: { branches: [main] }

jobs:
  dotnet:
    name: .NET Build & Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: "8.0.x" }
      - run: dotnet restore TicketingSystem.sln
      - run: dotnet build TicketingSystem.sln --no-restore -c Release
      - run: |
          dotnet test tests/Unit/ -c Release \
            --logger "trx;LogFileName=unit-results.trx" \
            --collect:"XPlat Code Coverage"
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: unit-test-results, path: "**/*.trx" }

  angular:
    name: Angular Build
    runs-on: ubuntu-latest
    defaults: { run: { working-directory: frontend } }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20.x", cache: npm,
                cache-dependency-path: frontend/package-lock.json }
      - run: npm ci
      - run: npm run lint || true
      - run: npm run build      # production build: tree-shaking + strict types

  docker:
    name: Docker Image Build
    needs: [dotnet, angular]
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service:
          - { name: identity,     dockerfile: src/Services/Identity/Dockerfile }
          - { name: eventcatalog, dockerfile: src/Services/EventCatalog/Dockerfile }
          - { name: booking,      dockerfile: src/Services/Booking/Dockerfile }
          - { name: payment,      dockerfile: src/Services/Payment/Dockerfile }
          - { name: notification, dockerfile: src/Services/Notification/Dockerfile }
          - { name: gateway,      dockerfile: src/ApiGateway/Dockerfile }
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v5
        with:
          context: .
          file: ${{ matrix.service.dockerfile }}
          push: false
          tags: ticketing/${{ matrix.service.name }}:ci
          cache-from: type=gha    # GitHub Actions layer cache
          cache-to: type=gha,mode=max

The pipeline runs 3 parallel jobs. docker waits for both dotnet and angular to pass. All 6 service images are built simultaneously in the matrix — if any Dockerfile is broken, the pipeline fails before anything reaches production.

19. Unit Tests

📁 tests/Unit/

Stack: xunit · FluentAssertions · NSubstitute

Aggregate Invariant Tests

// tests/Unit/Booking/BookingAggregateTests.cs

public class BookingAggregateTests
{
    [Fact]
    public void Create_ShouldSetPendingStatus()
    {
        var booking = MakeBooking();
        booking.Status.Should().Be(BookingStatus.Pending);
    }

    [Fact]
    public void Create_ShouldRaiseBookingCreatedEvent()
    {
        var booking = MakeBooking();
        booking.DomainEvents.Should().ContainSingle()
            .Which.Should().BeOfType<BookingCreatedEvent>();
    }

    [Fact]
    public void Confirm_WhenPending_ShouldSetConfirmedStatus()
    {
        var booking = MakeBooking();
        booking.Confirm("pi_123");
        booking.Status.Should().Be(BookingStatus.Confirmed);
    }

    [Fact]
    public void Confirm_WhenAlreadyConfirmed_ShouldThrow()
    {
        var booking = MakeBooking();
        booking.Confirm("pi_123");
        var act = () => booking.Confirm("pi_456");
        act.Should().Throw<InvalidOperationException>();
    }

    [Fact]
    public void Cancel_WhenPending_ShouldRaiseBookingCancelledEvent()
    {
        var booking = MakeBooking();
        booking.Cancel("Payment failed");
        booking.DomainEvents.Should()
            .Contain(e => e is BookingCancelledEvent);
    }

    [Fact]
    public void Cancel_WhenAlreadyCancelled_ShouldThrow()
    {
        var booking = MakeBooking();
        booking.Cancel("first");
        var act = () => booking.Cancel("second");
        act.Should().Throw<InvalidOperationException>();
    }

    [Fact]
    public void ClearDomainEvents_ShouldRemoveAll()
    {
        var booking = MakeBooking();
        booking.Confirm("pi_x");
        booking.ClearDomainEvents();
        booking.DomainEvents.Should().BeEmpty();
    }

    private static Booking MakeBooking() =>
        Booking.Create(Guid.NewGuid(), Guid.NewGuid(), "A1", 99.99m, "USD");
}

Command Handler Tests with Mocks

// tests/Unit/Booking/CreateBookingCommandHandlerTests.cs

public class CreateBookingCommandHandlerTests
{
    private readonly IBookingRepository _repo    = Substitute.For<IBookingRepository>();
    private readonly IUnitOfWork        _uow     = Substitute.For<IUnitOfWork>();
    private readonly ISeatLockService   _lock    = Substitute.For<ISeatLockService>();

    [Fact]
    public async Task Handle_WhenSeatAvailable_ShouldAddBookingAndReturnId()
    {
        _lock.TryLockAsync(Arg.Any<Guid>(), Arg.Any<string>(),
            Arg.Any<TimeSpan>(), Arg.Any<CancellationToken>())
            .Returns(true);

        var handler = new CreateBookingCommandHandler(_repo, _uow, _lock);
        var cmd = new CreateBookingCommand(Guid.NewGuid(), Guid.NewGuid(), "B5", 50m);

        var id = await handler.Handle(cmd, CancellationToken.None);

        id.Should().NotBeEmpty();
        _repo.Received(1).Add(Arg.Any<Booking>());
        await _uow.Received(1).SaveChangesAsync(Arg.Any<CancellationToken>());
    }

    [Fact]
    public async Task Handle_WhenSeatLocked_ShouldThrowAndNotPersist()
    {
        _lock.TryLockAsync(Arg.Any<Guid>(), Arg.Any<string>(),
            Arg.Any<TimeSpan>(), Arg.Any<CancellationToken>())
            .Returns(false);

        var handler = new CreateBookingCommandHandler(_repo, _uow, _lock);
        var cmd = new CreateBookingCommand(Guid.NewGuid(), Guid.NewGuid(), "C3", 75m);

        var act = async () => await handler.Handle(cmd, CancellationToken.None);

        await act.Should().ThrowAsync<InvalidOperationException>()
            .WithMessage("*held by another user*");

        _repo.DidNotReceive().Add(Arg.Any<Booking>());
        await _uow.DidNotReceive().SaveChangesAsync(Arg.Any<CancellationToken>());
    }
}

Value Object Tests

// tests/Unit/SharedKernel/ValueObjectTests.cs

public class ValueObjectTests
{
    [Fact]
    public void TwoMoneyObjects_WithSameValues_ShouldBeEqual()
    {
        var a = new Money(99.99m, "USD");
        var b = new Money(99.99m, "USD");
        a.Should().Be(b);
        (a == b).Should().BeTrue();
    }

    [Fact]
    public void TwoMoneyObjects_WithDifferentAmounts_ShouldNotBeEqual()
    {
        var a = new Money(10m, "USD");
        var b = new Money(20m, "USD");
        a.Should().NotBe(b);
    }

    [Fact]
    public void Money_WithNegativeAmount_ShouldThrow()
    {
        var act = () => new Money(-1m, "USD");
        act.Should().Throw<ArgumentException>();
    }
}

20. What to Build Next

Event Sourcing on the Booking aggregate — instead of storing current state, store every domain event that led to it (BookingCreated, BookingConfirmed, etc.). This provides a complete immutable audit log and the ability to replay history to any point in time.

Dedicated read model — currently queries hit the same SQL Server write database. For high read traffic (event search, seat availability), a separate read store updated by RabbitMQ projectors would scale reads independently of writes.

Kubernetes Helm charts — the Docker Compose configuration translates directly to Helm. Each service gets a Deployment, HorizontalPodAutoscaler, Service, and Ingress. Cert-manager handles TLS automatically.

Pact contract tests — integration events are the public API between services. Pact consumer-driven contract tests verify that producer events always satisfy what consumers expect, catching breaking changes before they reach the main branch.

Inbox deduplication — the outbox guarantees at-least-once delivery. The natural complement is an Inbox table per consumer that records received message IDs and skips duplicates, achieving exactly-once processing semantics.

Real Stripe integration — replace StripeService stub with Stripe.net SDK, add webhook endpoint for async payment confirmation, handle 3DS authentication flows.

21. Conclusion & GitHub Link

DDD, Event-Driven Architecture, and CQRS answer three distinct problems that every non-trivial distributed system eventually faces:

DDD answers: where does business logic live, and how do we stop it from rotting? — in aggregates, expressed in the language of the domain, protected by invariants that can never be violated regardless of which service or layer calls into them.

CQRS answers: how do we decouple the complexity of writes from the performance demands of reads? — commands own the write path with full domain model validation; queries own the read path with optimised projections, neither touching the other.

Event-Driven Architecture answers: how do loosely-coupled services coordinate without becoming entangled? — through immutable events on a message bus, with the booking saga orchestrating multi-service workflows, the outbox pattern ensuring zero message loss, and Redis seat locking preventing the fundamental overselling race condition.

Together these patterns produce a system where:

Each service can be deployed, scaled, and tested independently
Business invariants are impossible to violate by accident
Failures are handled by design, not by hope
The codebase reads like the domain it models

🚀 Get the Full Source Code

GitHub Repository: github.com/naimulkarim/TicketingSystem

# Clone and run the full stack locally
git clone https://github.com/naimulkarim/TicketingSystem.git
cd TicketingSystem
cp .env.example .env       # add your secrets
docker compose up --build  # starts everything
# Open http://localhost:4200

Direct file links referenced in this article:

File	Link
SharedKernel — AggregateRoot	`src/SharedKernel/Domain/AggregateRoot.cs`
SharedKernel — Primitives	`src/SharedKernel/Domain/Primitives.cs`
SharedKernel — Pipeline Behaviours	`src/SharedKernel/Application/Behaviours/PipelineBehaviours.cs`
Identity Config	`src/Services/Identity/Api/IdentityConfig.cs`
Event Aggregate	`src/Services/EventCatalog/Domain/Aggregates/Event.cs`
Booking Aggregate	`src/Services/Booking/Domain/Aggregates/Booking.cs`
Booking Events	`src/Services/Booking/Domain/Events/BookingEvents.cs`
CreateBooking Command	`src/Services/Booking/Application/Commands/CreateBookingCommand.cs`
Booking Queries	`src/Services/Booking/Application/Queries/GetBookingQuery.cs`
Booking Saga	`src/Services/Booking/Application/Sagas/BookingSagaStateMachine.cs`
Booking DbContext	`src/Services/Booking/Infrastructure/Persistence/BookingDbContext.cs`
Redis Seat Lock	`src/Services/Booking/Infrastructure/RedisSeatLockService.cs`
Booking Controller	`src/Services/Booking/Api/Controllers/BookingsController.cs`
Payment Aggregate	`src/Services/Payment/Domain/Aggregates/Payment.cs`
Payment Consumer	`src/Services/Payment/Infrastructure/Messaging/ProcessPaymentConsumer.cs`
Notification Consumers	`src/Services/Notification/Application/Consumers/BookingConsumers.cs`
API Gateway Program	`src/ApiGateway/Program.cs`
Outbox Message	`src/SharedKernel/Infrastructure/OutboxMessage.cs`
Auth Service (Angular)	`frontend/src/app/core/services/auth.service.ts`
NgRx Booking Store	`frontend/src/app/store/booking/booking.reducer.ts`
Docker Compose	`docker-compose.yml`
GitHub Actions CI	`.github/workflows/ci.yml`
Booking Aggregate Tests	`tests/Unit/Booking/BookingAggregateTests.cs`

If this article helped you, leave a comment — I'm happy to go deeper on any section.

Tags: dotnet csharp architecture ddd eventdriven cqrs angular microservices rabbitmq masstransit designpatterns cleanarchitecture

Running Local AI Models for Free: A Step-by-Step Guide with Python

Naimul Karim — Fri, 01 May 2026 03:45:24 +0000

Large language models are no longer locked behind expensive APIs. Today, you can run powerful AI models locally on your own machine, often for free, while keeping full control over data, latency, and cost.

In this guide, we’ll walk through how to run local models step by step using:

Ollama (CLI + API approach)
LM Studio (GUI approach)
Python integration for automation

Why Run AI Models Locally?

Running LLMs locally is becoming increasingly practical. Here’s why developers are doing it:

Privacy: Data stays on your machine
Zero API costs
Low latency for repeated tasks
Offline usage
Full control over models and prompts

Popular Free Local Models

Some of the best open models you can run locally today:

Llama 3 (Meta)
Mistral / Mixtral
Qwen2 / Qwen2.5 (Alibaba)
Gemma (Google)

These models come in different sizes (7B, 8B, 13B, etc.), allowing you to choose based on your hardware.

Method 1: Running Models with Ollama (Recommended)

Ollama is the easiest way to run local LLMs.

Step 1: Install Ollama

Download it from:

https://ollama.com

Install it like any normal application.

Supported platforms:

Windows
macOS
Linux

Step 2: Run Your First Model

Open your terminal and run:

bash ollama run llama3

Step 3: Chat with the Model

Just type:
Explain machine learning in simple terms

METHOD 2: Ollama with Python API

Ollama runs a local API server at:

http://localhost:11434

Basic Python Example

import requests
url = "http://localhost:11434/api/generate"

payload = {
    "model": "llama3",
    "prompt": "Explain recursion in simple terms",
    "stream": False
}
response = requests.post(url, json=payload)
print(response.json()["response"])

SecretVault: One Interface to Rule All Your Cloud Secrets in .NET 9

Naimul Karim — Wed, 29 Apr 2026 01:40:39 +0000

Every .NET project that touches the cloud eventually runs into the same problem: secret sprawl.

You start with AWS Secrets Manager. Then a new service needs Azure Key Vault. Someone spins up a HashiCorp Vault. Before long, your codebase is littered with provider-specific SDKs, inconsistent error handling, and zero ability to swap providers without rewriting half your infrastructure code.

I built SecretVault to fix this. One interface. Four providers. Zero lock-in.

The Problem in Plain Code

Here's what most codebases look like today:

// Somewhere in your AWS service
var awsClient = new AmazonSecretsManagerClient();
var response = await awsClient.GetSecretValueAsync(new GetSecretValueRequest
{
    SecretId = "prod/db-password"
});
var secret = response.SecretString;

// Somewhere else, for Azure
var kvClient = new SecretClient(vaultUri, new DefaultAzureCredential());
var azureSecret = await kvClient.GetSecretAsync("db-password");
var value = azureSecret.Value.Value;

Different SDKs. Different error types. Different mental models. And when you want to add caching or rotate secrets? You wire it up manually — for each provider — every time.

The SecretVault Way

// That's it. Same line. Any provider.
var password = await secrets.GetSecretAsync("db-password");

ISecretManager is the only interface your application code ever sees. Swap AWS for Azure in one line of DI configuration — your business logic never changes.

What's in the Box

SecretVault ships as 6 focused NuGet packages — install only what you need:

Package	What it does
`SecretVault.Core`	The `ISecretManager` interface + caching + chaining
`SecretVault.Aws`	AWS Secrets Manager provider
`SecretVault.Azure`	Azure Key Vault provider
`SecretVault.HashiCorp`	HashiCorp Vault KV v2 provider
`SecretVault.Gcp`	Google Cloud Secret Manager provider
`SecretVault.Extensions.Hosting`	ASP.NET Core DI + `IConfiguration` + health checks

dotnet add package SecretVault.Core
dotnet add package SecretVault.Aws
dotnet add package SecretVault.Extensions.Hosting

Quick Start: AWS

using Amazon.SecretsManager;
using SecretVault.Aws;

var client = new AmazonSecretsManagerClient();
ISecretManager secrets = new AwsSecretManager(client, logger);

// Fetch a raw string
var apiKey = await secrets.GetSecretAsync("prod/api-key");

// Fetch and deserialize JSON directly into a typed object
var dbConfig = await secrets.GetSecretAsync<DatabaseConfig>("prod/db-config");

Switching to Azure? One line changes:

// Before
ISecretManager secrets = new AwsSecretManager(client, logger);

// After
ISecretManager secrets = new AzureKeyVaultSecretManager(kvClient, logger);

Your application code above stays identical.

Built-in Caching

Cloud secret APIs have rate limits and latency. Fetching the same secret on every request is wasteful. Wrap any provider with CachedSecretManager:

var cached = new CachedSecretManager(
    inner: secrets,
    cache: memoryCache,
    logger: logger,
    options: new CachedSecretManagerOptions
    {
        AbsoluteExpiration = TimeSpan.FromMinutes(10)
    });

The cache is automatically invalidated on writes and deletes — so you never serve stale secrets after a rotation.

Fallback Chaining

Running a hybrid cloud? Or want a local fallback for development? ChainedSecretManager tries providers in order and returns the first successful result:

var chained = new ChainedSecretManager(
    [awsSecrets, localSecrets],
    logger);

// Tries AWS first, falls back to local dev secrets if not found
var value = await chained.GetSecretAsync("api-key");

This is great for local development too — point your fallback at environment variables or a local JSON file without touching your production code path.

Secret Rotation

All provider implementations also implement ISecretRotationManager, giving you first-class rotation support:

ISecretRotationManager rotatable = new AwsSecretManager(client, logger);

var result = await rotatable.RotateSecretAsync(
    secretName: "prod/db-password",
    newValue: GenerateSecurePassword(),
    gracePeriod: TimeSpan.FromHours(1)  // old version stays accessible during rollover
);

Console.WriteLine($"Rotated to version {result.NewVersion} at {result.RotatedAt}");
// Optionally: notify dependent services, invalidate connection pools, etc.

You can also list all versions and retrieve a specific one:

var versions = await rotatable.ListVersionsAsync("prod/db-password");
var oldValue = await rotatable.GetSecretVersionAsync("prod/db-password", versions[1].Version);

ASP.NET Core Integration

Load secrets into `IConfiguration` at startup

Pull secrets directly into the config pipeline so they're accessible via IConfiguration just like appsettings.json:

// Program.cs
builder.Configuration.AddSecretVault(secretManager, [
    "db-connection-string",
    "stripe-api-key",
    "sendgrid-api-key"
]);

// Then use them as normal config
var connStr = builder.Configuration["db-connection-string"];

Register via Dependency Injection

builder.Services.AddSecretVault(secretManager, options =>
{
    options.AbsoluteExpiration = TimeSpan.FromMinutes(5);
});

Inject at runtime

public class PaymentService(ISecretManager secrets)
{
    public async Task ProcessPayment(decimal amount)
    {
        var stripeKey = await secrets.GetSecretAsync("stripe-api-key");
        // use it
    }
}

Health checks

builder.Services.AddHealthChecks()
    .AddSecretVaultHealthCheck("__probe__", name: "secrets");

This adds a /health endpoint entry that pings your secret provider on every health check — giving you early warning if credentials expire or network access is lost.

Error Handling

SecretVault normalizes provider-specific exceptions into a clean hierarchy so you never have to catch Amazon.Runtime.AmazonServiceException or Azure.RequestFailedException in your business logic:

try
{
    var secret = await secrets.GetSecretAsync("my-secret");
}
catch (SecretNotFoundException ex)
{
    // Secret doesn't exist in the provider
    logger.LogWarning("Secret {Name} not found", ex.SecretName);
}
catch (SecretAccessDeniedException)
{
    // IAM / RBAC permissions issue
    logger.LogError("Access denied — check your IAM role");
}
catch (SecretProviderUnavailableException)
{
    // Network or service outage
    logger.LogCritical("Secret provider is down");
}

CI/CD — Automated NuGet Publishing

The repo ships with two GitHub Actions workflows out of the box.

ci.yml — runs on every push and PR:

Restores dependencies
Builds in Release mode
Runs all tests with code coverage

publish.yml — triggered by a version tag:

git tag v1.0.0
git push origin v1.0.0

This automatically:

Runs the full test suite
Packs all 6 NuGet packages with the correct version
Pushes them to nuget.org
Creates a GitHub Release with auto-generated changelog

Zero manual steps after tagging.

Design Decisions Worth Knowing

Why separate packages instead of one big one?
If you only use AWS, you shouldn't have the Azure and GCP SDKs in your dependency tree. Each provider package is independent — install exactly what you need.

Why not just use IConfiguration directly?
IConfiguration is great for startup binding, but it doesn't support on-demand fetching, rotation, versioning, or cache invalidation. SecretVault gives you both — startup binding and a runtime API through the same abstraction.

Why .NET 9 only?
To keep the codebase lean and take advantage of modern C# features (primary constructors, collection expressions, nullable reference types). A netstandard2.0 target may come in a future release if there's demand.

Get Started

# Clone
git clone https://github.com/YourUsername/SecretVault.git
cd SecretVault

# Build
dotnet build SecretVault.sln

# Test
dotnet test SecretVault.sln

Or grab it straight from NuGet:

dotnet add package SecretVault.Core
dotnet add package SecretVault.Aws        # or .Azure / .HashiCorp / .Gcp
dotnet add package SecretVault.Extensions.Hosting

What's Next

A few things on the roadmap:

SecretVault.Local — a file/environment variable provider for local development
Automatic rotation scheduling — background IHostedService that rotates on a cron
Encryption at rest layer — wrap any provider with AES encryption before storing
.NET Standard 2.0 target — for broader framework compatibility

PRs and issues welcome. If you're using a provider not listed here, opening an issue with your use case is the fastest path to getting it supported.

Built with .NET 9, xUnit, FluentAssertions, and NSubstitute. MIT licensed.

⭐ If SecretVault saves you some boilerplate, a star on GitHub goes a long way.

View on GitHub · NuGet Packages

A Unified View of AI Evolution: From Machine Learning to LLMs, RAG, and Fine-Tuning

Naimul Karim — Tue, 28 Apr 2026 03:34:24 +0000

Artificial Intelligence has progressed far beyond its early rule-based origins. What once depended on predefined logic has evolved into systems that can learn from data, reason through problems, and even generate entirely new content. This transformation is largely driven by Machine Learning (ML), where algorithms improve their performance by identifying patterns in large datasets rather than following hard-coded instructions.

Building on ML, Deep Learning introduces neural networks—layered computational structures inspired by the human brain. These networks excel at processing complex data such as images, speech, and text. The next leap in this evolution is Generative AI, which shifts the focus from analyzing data to creating it. Whether producing text, images, or audio, generative systems mimic human creativity in increasingly sophisticated ways.

Large Language Models: The Core of Modern GenAI

At the center of today’s generative revolution are Large Language Models (LLMs). These models are designed to interpret and produce human-like language, enabling natural conversations, content generation, and problem-solving.

Most modern LLMs are built on the Transformer architecture, introduced in the landmark concept “Attention Is All You Need.” This architecture uses attention mechanisms to understand how words relate to each other in context, making it far more effective than earlier sequence models.

Some prominent LLM families include:

OpenAI models such as GPT-4.5, GPT-4o, and smaller optimized variants
Anthropic’s Claude series (e.g., Claude 3.5 Sonnet, Claude 3 Opus)
Meta’s Llama models (e.g., Llama 3.x series)
Google’s Gemini models

These models power a wide range of applications, from chatbots and virtual assistants to marketing content generation, document summarization, and even software development tasks like debugging and code generation.

How LLMs Work in Practice

Accessing LLMs

Users can interact with LLMs through intuitive interfaces (chat-based systems) or integrate them into applications using APIs.

Prompting and Instructions

To guide an LLM toward the desired output, users provide structured inputs—this process is known as prompt engineering. The clarity and design of prompts significantly influence the quality of responses.

Understanding Language via Embeddings

LLMs convert text into numerical representations called embeddings. These vectors capture semantic meaning, enabling the model to understand relationships between words, phrases, and broader contexts.

Controlling Output with Temperature

LLMs do not always produce the same answer. A parameter called temperature controls how deterministic or creative the output is. Lower values lead to predictable responses, while higher values increase variability and creativity.

Grounding LLMs with Real-World Knowledge

Despite their capabilities, LLMs are inherently general-purpose. They do not automatically know company-specific or real-time information. To make them useful in practical settings, additional context must be provided. Two key approaches enable this: Retrieval-Augmented Generation (RAG) and Fine-Tuning.

Tokenization: How Models Read Language

Computers don’t interpret language the way humans do. Instead of understanding full words or sentences directly, Large Language Models break text into smaller units called tokens. These tokens are then converted into numbers so the model can process them mathematically.

A token isn’t always a whole word—it can be:

A complete word (“river”)
A fragment of a word (“run” + “ning”)
Symbols or punctuation (like “?” or “.”)

Different AI models use different methods to split text into tokens. Some rely on frequently occurring patterns, while others use statistical approaches to segment text.

On average, in English:

1 token is roughly equal to 4 characters
Or about ¾ of a word

Why this matters:

Efficiency: Breaking text into tokens allows models to process language in a structured way.
Flexibility: Even unfamiliar words can be understood by splitting them into smaller parts.
Cost impact: More tokens directly increase usage costs.

Example:
Sentence: “Learning AI is fun.”
Possible tokens: “Learn”, “ing”, “ AI”, “ is”, “ fun”, “.”
Each of these is internally mapped to a numeric ID for computation.

Context Windows: The Model’s Working Memory

LLMs don’t have unlimited memory. Instead, they operate within a fixed limit called a context window, which defines how many tokens the model can consider at one time.

Think of it as short-term memory:

Smaller models handle a few thousand tokens
Advanced models can process very large inputs, even entire books

If the input exceeds this limit, older parts are removed from consideration. The model then loses access to that earlier information.

Why this matters:

Conversations: Important details from earlier messages can disappear in long chats.
Large files: Long reports or documents must often be split into sections.
Cost vs capability: Larger windows provide more context but require more resources.

Example:
Imagine summarizing a long report. If the report is longer than the model’s context window, only the most recent sections might be considered unless special techniques are used.

Token-Based Pricing: Why Usage Adds Up

Most AI platforms charge based on token usage. This includes both:

Input tokens: The text you send
Output tokens: The text generated in response

The total cost depends on the combined number of tokens processed.

Simple breakdown:

Total tokens = input + output
Pricing is typically calculated per 1,000 tokens

Why this matters:

Efficiency saves money: Shorter prompts reduce cost
Control output: Limiting response length prevents unnecessary usage
Planning: Developers often estimate token usage before sending requests

Example:

Input: 300 tokens (a short question with context)
Output: 450 tokens (a detailed answer)
Total: 750 tokens

This total determines the cost of that interaction.

Retrieval-Augmented Generation (RAG)

RAG enhances LLMs by connecting them to external knowledge sources such as databases, documents, or APIs.

How It Works

A user submits a query
Relevant information is retrieved from a knowledge source
This information is added to the model’s input
The LLM generates a response grounded in both its training and the retrieved data

Benefits

Produces more accurate, fact-based responses
Keeps information up to date without retraining
Cost-efficient since the base model remains unchanged

Trade-offs

Slightly slower due to the retrieval step

Fine-Tuning: Customizing Intelligence

Fine-tuning takes a pre-trained LLM and further trains it on domain-specific data. This process embeds specialized knowledge directly into the model.

How It Works

A base model is trained further on curated datasets
It learns domain terminology, patterns, and workflows

Benefits

Faster responses (no external lookup required)
Highly tailored outputs aligned with specific use cases

Trade-offs

Expensive in terms of compute and maintenance
Requires retraining to incorporate new information

RAG vs Fine-Tuning

RAG and fine-tuning serve different but complementary purposes:

RAG is ideal for dynamic, frequently changing knowledge
Fine-tuning is best for consistent, domain-specific expertise

In real-world systems, combining both often yields the best results—fine-tuning for behavior and tone, and RAG for factual accuracy and freshness.

Understanding LLM Performance

The effectiveness of an LLM is closely tied to its size, typically measured by the number of parameters (often in billions). Larger models tend to perform better on complex tasks but require significant computational resources to train and deploy.

This trade-off has led to the rise of smaller, efficient models—sometimes called “mini-giants”—which aim to deliver strong performance with lower cost and latency.

DEV Community: Naimul Karim

Stop Prompt Engineering, Start Context Engineering

Chat vs. Agent

The Agent Loop

The Stack, in Layers

A Quick Example

Starter Checklist

AI Agentic Workflow Explained: A Quick Tour of Harness, Tools, Skills, MCP, and Memory

Understanding the AI Agent Workflow

1. Agent Harness: The Runtime Behind the Agent

2. Tools: Giving Agents the Ability to Act

3. Model Context Protocol (MCP): Standardizing Tool Connections

4. AGENTS.md: The Agent's Always-Loaded Instructions

5. Skills: Dynamic Agent Capabilities

AGENTS.md vs Skills: Why Both Matter

6. Memory: Giving Agents Continuity

Short-Term Memory

Working Memory

Long-Term Memory

Complete AI Agent Workflow Example

Step 1: Load Agent Instructions

Step 2: Load Relevant Skills

Step 3: Retrieve Memory

Step 4: Discover Tools Through MCP

Step 5: Execute the Task

Step 6: Verify and Complete

Why Agentic Workflows Matter

Final Thoughts

What is an AI Agent Harness?

What Does an AI Agent Harness Provide?

Tools

Memory

Workspace

Guardrails

Why Do AI Agents Need Both a Model and a Harness?

The Reason → Act → Observe Loop

1. Reason

2. Act

3. Observe

4. Repeat

Model vs Harness vs Agent

Core Building Blocks of an AI Agent Harness

System Prompts

Tool Execution

Execution Environments (Sandboxes)

Filesystem and Storage

Memory and Context Management

Feedback and Self-Verification

Guardrails and Human-in-the-Loop Controls

Observability and Logging

Why Harness Design Matters

Harness Engineering: The Next Evolution

Final Thoughts

How I Fixed Windows 11 Sleep Not Working by Tracking Down a Hidden WebView2 Video Wake Lock

🖥️ The Problem

🔍 Step 1: Check for Power Requests

🔎 Step 2: Find Which Application Owns WebView2

🧪 Step 3: Eliminate Processes One by One

💻 Step 4: Verify Sleep Support

✅ Step 5: Fix the Root Cause

🔐 Bonus: Require a PIN After Sleep

🛠 Useful Commands

Check what's preventing sleep

View supported sleep states

Generate an energy report

Generate a Sleep Study report

Show devices allowed to wake the PC

💡 Lessons Learned

Final Thoughts

Have you encountered a similar issue?

Windows #Windows11 #PowerManagement #Troubleshooting #WebView2 #PowerShell #Dell #ModernStandby #DeveloperTips

Building a Secure Real-Time Messaging App with .NET 8 and Angular 18

Introduction

Architecture Overview

Part 1 — The .NET 8 Backend

Setting up Program.cs

Authentication Service — JWT + BCrypt + Refresh Tokens

Encryption Service — AES-256-GCM

SignalR Hub

Part 2 — The Angular 18 Frontend

Setting up `Program.cs`

`ISecretManager` — The Unified Interface

`ISecretRotationManager` — Rotation on Top

`AddSecretVault` — The DI Extension Method

`IConfiguration` Integration

CI (`ci.yml`) — Every push and PR

Publish (`publish.yml`) — Tag a version, ship everything