The question is how well you capture and use that information.

What if every call could be turned into structured data and used by agentic AI systems where agents actively handle tasks, fix issues, and support decision-making?

There are many ways to do it, but here’s a simple architecture on Azure:

𝗜𝗻𝗴𝗲𝘀𝘁𝗶𝗼𝗻 & 𝗣𝗿𝗼𝗰𝗲𝘀𝘀𝗶𝗻𝗴

Audio → Blob → Event Grid → Queue → Worker

𝗨𝗻𝗱𝗲𝗿𝘀𝘁𝗮𝗻𝗱𝗶𝗻𝗴

- Content Understanding (turns audio into structured data)

𝗗𝗮𝘁𝗮 & 𝗥𝗲𝘁𝗿𝗶𝗲𝘃𝗮𝗹

- PostgreSQL (chat history, other structured data)

- Azure AI Search (RAG)

𝗔𝗜

- Microsoft Foundry + LangGraph (multi-agent orchestration)

𝗨𝗜 / 𝗔𝗣𝗜

- Container Apps (exposes the system to users / clients)

Nothing fancy individually, but together, it turns raw calls into something agents can query, analyze, and act on in real workflows.

Full walkthrough + POC app:

Lately, a big part of my job has been figuring out how to leverage AI’s benefits without compromising the overall solution architecture and turning the system into unreliable, hard to maintain mess. Many teams are being pushed to deliver faster using AI, often under tighter deadlines. If this isn’t handled carefully, it can quickly lead to architectural erosion, growing complexity, and systems that you want to stay away from.

Teams are already feeling the impact. When guardrails are missing, structure erodes and boundaries blur. We’re even seeing large systems struggle under constant rushed changes with AI. Frequent Windows update issues are a reminder of how fragile complex software (especially written with AI) can become when complexity grows faster than control.

The challenge isn’t speed versus quality. It’s learning how to move fast without weakening the architecture that keeps the system stable.

In today’s post, I’m focusing specifically on greenfield projects. I’m going to walk through a few practical steps you can follow to ensure AI accelerates your development without slowly destroying your solution and making it unmaintainable.

I will cover brownfield systems separately, because the strategy there is different and deserves its own discussion.

Build Good Architecture from the Start (Greenfield)

If you’re working on a greenfield project, you have a rare advantage as you control the foundation. There’s no legacy, no accidental complexity, no historical shortcuts. That also means the responsibility is entirely yours.

Start with clear understanding of functional and non-functional requirements. Design system boundaries intentionally. Define coding standards, layering rules, and architectural principles before the first large batch of AI-generated code enters the repository.

AI can help you build and move faster but only when you have stable foundations.

In greenfield projects, the discipline you apply at the beginning determines maintainability years later.

We’ve Got the Architecture… Now It’s Time to Protect It

Designing a solid architecture is only the first step. Once development begins and AI starts generating code at scale, protection becomes critical.

Architecture should not live only in your head or in a diagram. It needs to be documented, enforced, and protected with automated checks, review processes, and clear boundaries.

Now let’s see some basic steps that will help us protect the solution from architectural erosion.

Use GitHub Copilot to Protect the Architecture

AI should not only generate code. It should help enforce the architecture you designed. Instead of treating AI as a shortcut to write tons of code, treat it as an extension of your governance model as well.

If you give AI clear rules, boundaries, and responsibilities, it can become part of your quality control system rather than a source of entropy.

A recent 2025 study (https://arxiv.org/pdf/2507.11538) showed that as the number of instructions increases, AI models start missing requirements and skipping constraints. In other words, the more rules you throw at them, the more likely they are to ignore some of them. You should always keep this in mind.

This has direct implications for how we document architecture and even how we use the tools that I am about to show you in a second.

If your repository contains hundreds of loosely structured rules, long narrative explanations, and scattered constraints, the model will not reliably follow all of them. Overloading it with instructions reduces compliance.

That is why architectural guidance for AI must be:

• Short

• Explicit

• Structured

• Prioritized

Concise, well-organized rules outperform long, dense documents. If we want AI to protect the architecture, we must write instructions that it can realistically follow.

Now let’s look at some easy-to-follow steps that will help us protect the architectural integrity of our solution.

Custom Instructions

Start with a copilot-instructions.md file. This document defines your project’s coding standards and architectural rules in a concise format.

Include things like:

• Folder structure expectations

• Layering rules

• Dependency constraints

• Naming conventions

• Required patterns

When Copilot reads this before generating code, it aligns with your architecture instead of inventing its own structure.

Keep it short. If it’s too long, it won’t be followed consistently.

Here’s an example of such a document.

# Project: Protect Arch Demo

This project follows **Clean Architecture** principles. All contributions — human or AI — must respect the layered dependency rules.

## Architecture Layers (innermost → outermost)

1. **Domain** (`src/Domain`) — Entities and repository interfaces. Zero dependencies on other project layers.
2. **Application** (`src/Application`) — Use cases / business logic. Depends only on Domain.
3. **Infrastructure** (`src/Infrastructure`) — Data access, external services. Depends on Domain and Application.
4. **Api** (`src/Api`) — HTTP layer, DI composition root. Depends on Application and Infrastructure.

## Dependency Rules — NEVER violate these

| Layer          | May reference               | Must NEVER reference             |
| -------------- | --------------------------- | -------------------------------- |
| Domain         | (nothing)                   | Application, Infrastructure, Api |
| Application    | Domain                      | Infrastructure, Api              |
| Infrastructure | Domain, Application         | Api                              |
| Api            | Application, Infrastructure | —                                |

## Coding Guidelines

- Use **C# 12** with file-scoped namespaces.
- Keep Domain entities as plain POCOs — no framework dependencies.
- Repository **interfaces** live in `Domain/Interfaces`; **implementations** live in `Infrastructure/Repositories`.
- Use cases live in `Application/UseCases` and accept interfaces via constructor injection.
- The Api project is the only place that configures DI and middleware — never register services elsewhere.
- All new code must pass the architecture tests in `tests/ArchitectureTests` (run with `dotnet test`).

Agent Skills

Agent Skills let you package reusable capabilities, like instructions, scripts, templates, and supporting resources that Copilot can load when needed. Only the skill’s name and description are available by default. The full instructions and resources are loaded on demand, when the task matches the skill’s purpose.

This is critical for two reasons:

1. It keeps context clean and lightweight.

2. It prevents instruction overload, which reduces model reliability.

A skill can encapsulate workflows such as:

• Architecture validation

• Test generation

• Refactoring checks

• Security review

• Deployment validation

Unlike custom instructions, which are always applied and define your structural rules, Agent Skills are task-specific. They activate only when relevant.

Here’s an example of a skill for clean architecture review:

---
name: clean-architecture-review
description: 'Reviews .NET code for Clean Architecture dependency violations. Use when reviewing code changes, pull requests, or validating that new code respects layer boundaries in a Clean Architecture project.'
---

# Clean Architecture Review

You are a specialist in Clean Architecture for .NET projects. When this skill is activated, perform a thorough review of the code for dependency rule violations.

## Architecture Layers

The project uses four layers (innermost → outermost):

1. **Domain** (`src/Domain`) — Entities, value objects, repository interfaces. **Zero** dependencies on other layers.
2. **Application** (`src/Application`) — Use cases and business logic. Depends only on Domain.
3. **Infrastructure** (`src/Infrastructure`) — Data access, external services. Depends on Domain and Application.
4. **Api** (`src/Api`) — HTTP endpoints, DI composition root. Depends on Application and Infrastructure.

## Review Checklist

For each source file, check the following:

### 1. Layer Identification

Determine which layer a file belongs to based on its path prefix:

- `src/Domain/` → Domain
- `src/Application/` → Application
- `src/Infrastructure/` → Infrastructure
- `src/Api/` → Api

### 2. Forbidden Dependencies

Check all `using` directives and type references:

| Layer          | Forbidden Dependencies           |
| -------------- | -------------------------------- |
| Domain         | Application, Infrastructure, Api |
| Application    | Infrastructure, Api              |
| Infrastructure | Api                              |
| Api            | (no restrictions)                |

### 3. Structural Rules

- Interfaces in `Domain/Interfaces/` must **only** be interfaces
- Repository implementations must live in `Infrastructure/Repositories/`
- Use cases must live in `Application/UseCases/`
- DI registration must only happen in `src/Api/Program.cs`

## How to Run Verification

Use the [architecture test script](./run-arch-tests.ps1) to execute automated verification:

```powershell
.\run-arch-tests.ps1
```

Or run directly:

```
dotnet test tests/ArchitectureTests --verbosity normal
```

## Output Format

Report findings as:

```
✅ PASS — No architecture violations found
```

or

```
❌ VIOLATION in [file path]
   Layer: [layer name]
   References: [forbidden namespace]
   Rule: [which rule is broken]
   Fix: [how to fix it]
```

Custom Agents

Custom agents let you define AI roles with clear responsibilities.

Instead of one generic assistant, you can create:

• A Developer Agent

• An Architecture Review Agent

• A Testing Agent

• A Documentation Agent

You can generate code with one agent and hand it off to another for validation.

That handoff mirrors real engineering teams. Responsibilities are separated. Validation is intentional. AI becomes structured, not improvisational.

Here’s an example of an Architecture Guardian agent:

---
name: arch-guardian
description: 'Architecture Guardian — reviews code for Clean Architecture violations'
tools:
  - search
  - read/readFile
---

# Architecture Guardian

You are the **Architecture Guardian** for this project. Your sole purpose is to protect the Clean Architecture boundaries.

## Your Personality

You are a vigilant castle guard. The architecture is your castle, and each layer is a wall. You never let a dependency sneak through the wrong gate.

## What You Do

When asked to review code or validate the architecture:

1. **Identify the layer** each file belongs to based on its path:
   - `src/Domain/` → Domain layer
   - `src/Application/` → Application layer
   - `src/Infrastructure/` → Infrastructure layer
   - `src/Api/` → Api layer

2. **Check `using` statements and references** for forbidden dependencies:
   - Domain → must NOT reference Application, Infrastructure, or Api
   - Application → must NOT reference Infrastructure or Api
   - Infrastructure → must NOT reference Api

3. **Check structural rules**:
   - Interfaces in `Domain/Interfaces/` must be interfaces (not classes)
   - Repository implementations must live in `Infrastructure/Repositories/`
   - Use cases must live in `Application/UseCases/`
   - DI registration must only happen in `src/Api/`

4. **Run the architecture tests** to confirm:

   ```
   dotnet test tests/ArchitectureTests --verbosity normal
   ```

5. **Report findings** clearly — list each violation with the file, line, and which rule was broken.

## Important

- NEVER suggest code that violates these rules.
- If asked to write code, always place it in the correct layer.
- If you find violations, provide corrected code that moves the logic to the proper layer.

Hooks (Preview)

Hooks allow you to execute custom logic automatically when specific events occur during AI-assisted workflows. This feature is currently in preview, but it introduces an important architectural capability.

Instead of relying only on instructions, you can attach enforcement mechanisms to lifecycle events inside the development flow.

Hooks can trigger scripts or commands at defined moments — for example before or after AI generates code.

You can use hooks to:

• Validate that required architectural patterns are present after generation

• Run boundary-check scripts when a new file is created

• Enforce dependency direction rules automatically

• Trigger linting or architectural validation commands

• Block unsafe patterns before changes are finalized

Hooks turn architecture from documentation into execution.

Instead of trusting that AI follows your rules, you verify compliance programmatically.

Even though the feature is still in preview, it represents a major step toward embedding architectural governance directly into AI-assisted development workflows.

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "bash .github/hooks/scripts/arch-test.sh",
        "windows": "powershell -ExecutionPolicy Bypass -File .github/hooks/scripts/arch-test.ps1",
        "timeout": 60
      }
    ]
  }
}

#!/usr/bin/env pwsh
# PostToolUse hook — runs architecture tests after Copilot edits files
# Only triggers when the tool is "editFiles" (i.e. Copilot wrote code)

$input_json = [Console]::In.ReadToEnd() | ConvertFrom-Json

$tool = $input_json.tool_name

# Only run after file-editing tools
if ($tool -notin @("editFiles", "create_file", "replace_string_in_file", "write_to_file", "insert_edit")) {
    # Not a file edit — skip silently
    @{ continue = $true } | ConvertTo-Json
    exit 0
}

# Run architecture tests
$testResult = dotnet test tests/ArchitectureTests --no-restore --verbosity quiet 2>&1

if ($LASTEXITCODE -ne 0) {
    $output = @{
        continue           = $true
        hookSpecificOutput = @{
            hookEventName     = "PostToolUse"
            additionalContext = "ARCHITECTURE VIOLATION DETECTED! The architecture tests failed after your edit. Please review and fix the dependency rule violation. Test output: $($testResult -join "`n")"
        }
    }
    $output | ConvertTo-Json -Depth 3
    exit 0
}

@{ continue = $true } | ConvertTo-Json
exit 0

GitHub Copilot Code Review Agent

Generating code is only half of the equation. The real protection happens during review.

GitHub Copilot’s code review agent brings AI into the pull request workflow. Instead of using AI only at the moment of creation, you can use it as an automated reviewer that analyzes changes before they reach your main branch.

From an architectural perspective, this is critical.

The review agent can:

• Detect violations of architectural boundaries

• Flag missing required patterns

• Identify risky dependency changes

• Suggest improvements aligned with project conventions

• Surface potential security or maintainability issues

This transforms AI from a code accelerator into a quality gate participant.

When combined with branch protection rules and required status checks, the Copilot review agent becomes part of your governance layer. Every pull request passes through automated architectural scrutiny before human approval.

This mirrors how mature engineering organizations operate:

• Developer writes code

• Automated systems validate it

• Reviewers enforce standards

• Only then does it reach production

In a greenfield project, integrating AI into the review stage is one of the most effective ways to prevent architectural erosion while still benefiting from rapid generation.

AI-Governed Systems in 2026 and Onward

This is what a modern solution should start to look like.

Not just src and tests, but explicit architectural guardrails built into the repository itself. Dedicated folders for agents, skills, hooks, prompts, and enforcement scripts. Architecture is not something we design at the beginning and then forget — it needs mechanisms that continuously enforce boundaries as the system evolves. And what better way to achieve that than a well-structured AI governance process with a human in the loop?

Final Thoughts

None of the steps discussed here are complex or exotic. They are practical, easy to follow, and accessible to any team starting a greenfield project.

• Define your architecture clearly in the beginning.

• Document it concisely.

• Use custom instructions to encode your standards.

• Leverage Agent Skills and Custom Agents to structure AI behavior.

• Add hooks to automatically validate architectural rules when different AI agent events occur.

• Enforce everything through pull requests, automated tests, and quality gates.

If a team wants to move fast with AI while still building a system that remains understandable, maintainable, and scalable years from now, these steps are a great starting point.

DNS Lookup

Domain names exist so humans can remember websites more easily. It’s much easier to remember chat.com than 104.18.41.60, right? But since every computer on the internet communicates using IP addresses, we need a way to translate a domain name into an IP address. That’s where DNS comes in.

Your browser first asks a simple question:
“What’s the IP address of chat.com?”

It checks caches (browser, OS, router, ISP).

If there’s no cached answer, it queries DNS by traversing the DNS hierarchy: first the root servers, then the top-level domain servers (.com), and finally the authoritative name server, which contains the IP address for chat.com.

This IP is Anycast, meaning the same IP is advertised from many locations globally.

What is Anycast?

Anycast is a network addressing and routing method in which incoming requests can be routed to multiple different locations, or “nodes.” With Anycast, the same IP address is advertised from servers in multiple geographic locations. This approach is commonly used by CDNs, such as Cloudflare, and provides benefits related to security, reliability, and performance.

For example, a hacker performing a DDoS attack would require significantly more resources to have a meaningful impact, because the traffic is distributed across many servers and locations rather than concentrated on a single endpoint (Unicast).

And of course, another benefit of CDNs in general is also enabled by Anycast. You are routed as close as possible to resources such as images, videos, and text. Basically, Anycast routes your traffic (via BGP, as explained later) to the nearest server that can handle your request. So, if you open chat.com, you will hit a server that is closest to you and therefore experience lower latency and overall good performance. For example, if you are in France, your request will not be routed to the US, but rather to a nearby location, such as Paris.

So, at the end of the DNS lookup process, we get an IP address such as 104.18.41.60, which belongs to Cloudflare, and not directly to OpenAI (ChatGPT).

Border Gateway Protocol (BGP)

BGP is the routing protocol of the internet. A hero almost no one talks about, yet it is the protocol that keeps the internet reliable by selecting paths between networks based on routing policies. To better understand how this works, let’s briefly talk about autonomous systems.

Autonomous systems

The internet is a network of hundreds of thousands of smaller networks called autonomous systems (ASes), each operated by a single organization (e.g., Cloudflare) and consisting of its own set of routers.

Basically, what BGP does is select a route from source to destination based on routing policies between autonomous systems, rather than simply choosing the path with the fewest hops. In practice, these policies can include factors such as business relationships, costs, and traffic agreements between ASes. But at a high level, the idea is simple: BGP determines how traffic moves between networks on the internet.

TCP

Once we have the source IP, destination IP, and port (443 in our case, because that’s what TLS uses), we are ready to start a TCP connection. This is handled underneath by the operating system (OS). The OS creates a TCP connection by adding the required headers—such as source IP, destination IP, and ports—and sending the packets over the network.

The process is a three-step procedure (commonly called the three-way handshake), where the client and the server acknowledge each other and establish an ongoing connection between them.

TLS

Since we don’t want our chat messages to be visible to third parties, we establish an encrypted channel over TCP. This is done using TLS, which relies on symmetric encryption algorithms such as AES to encrypt all data exchanged between the client and the server, including the chat messages. This works by negotiating a symmetric session key that is then used by both parties for encryption and decryption.

HTTP

Now that we have a secure (TLS) and ongoing (TCP) session, we are ready to start communicating with ChatGPT. To do that, we rely on the HTTP protocol. Since we want to load the ChatGPT page in our browser, we first send an HTTP GET request to chat.com.

All of this communication is encrypted using the negotiated symmetric key, and the request is sent not directly to ChatGPT’s infrastructure, but to Cloudflare, because Cloudflare sits in front of ChatGPT to protect its infrastructure, provide CDN capabilities, and handle traffic at the edge for the duration of the session. Remember, you never communicate directly with ChatGPT’s web servers.

Once the request is received and validated, it is forwarded to one of ChatGPT’s many web servers, which processes it. The web server then returns the website resources—such as HTML, CSS, JavaScript, and images—to Cloudflare’s servers, which in turn send the response back to your browser.

Browser

When the browser receives the response from Cloudflare, it parses the HTML, CSS, and JavaScript files and builds the DOM. The final step is rendering the page, where the browser renders the visual elements—that’s how you see ChatGPT in your browser.

Thank you

Now you know what happens when you open ChatGPT in your browser and all the steps that take place in milliseconds, almost like magic. If you found this post useful, please subscribe and share it with others.

THE BASICS…

Let’s start with the basics. A typical architecture usually has a Client for the user interface (UI), a Server for the business logic, and a Database to store state.

This is an architecture we still see today, and it was predominant in the early days of the internet. However, it has a major flaw — it lacks mechanisms that improve security and availability.

Since there’s nothing in front of your web server to protect it, your web server is publicly visible and an easy target for all kinds of attacks, most notably distributed denial-of-service (DDoS) attacks.

Another major issue is the lack of availability. What happens, for example, if your single web server goes down? Your clients won’t be happy, and your business might be at risk.

Of course, whether the lack of availability mechanisms is an issue or not depends entirely on the type of application you have. If this is just a simple web app containing your CV, for example, then this is okay. If this is banking software or a medical system, it is not.

Security, on the other hand, should never be a compromise when your system is exposed to the internet. Yes, a hacked banking system is far more damaging than someone hacking your CV website, but even a personal attack can affect you, your finances, and your reputation.

Let’s now fix these issues.

MEET THE REVERSE PROXY

There’s one service that helps mitigate the flaws of the architecture described above. Some call it a reverse proxy, others a load balancer or gateway. And while they are not always the same thing, they usually solve overlapping problems.

That’s it. One service that will improve your security tremendously and help you reach higher availability. But wait a minute, we now have two web servers, instead of one. Yes, that’s because we do want to utilize the load balancing feature of our reverse proxy.

Now, unlike in the first example above, if and when your server goes down, for example Server A, all the traffic will be automatically redirected to Server B. And just like that your business will no longer suffer and thus you’ve improved your overall availability.

And now you have protection from attacks, load balancing, caching, and TLS/SSL termination—features that usually come built in with these services in the cloud.

Internet Routing

And finally, I’m going to spend just a short amount of time on internet routing and try to answer the question of how a request reaches your load balancer in the first place.

Many people think it’s all thanks to the Domain Name System (DNS), and while the DNS is extremely important part, there’s another protocol, without which the internet simply won’t work and that’s the Border Gateway Protocol which basically finds the best route for your request based on latency, cost, geographic location, and others.

What we call “the internet” is a network of many large networks connected together, called autonomous systems. An autonomous system (AS) is a large network—or a group of networks—operated under a single routing policy, and every device connected to the internet ultimately connects through one of these systems.

Each autonomous system uses BGP to announce which IP address ranges it is responsible for and which other autonomous systems it connects to. BGP routers collect this information from ASes around the world and build routing tables that determine how traffic should flow from one AS to another. When a packet arrives, a router consults its routing table to decide which AS the packet should be forwarded to next.

Because there are so many autonomous systems globally, BGP routers constantly update their routing tables. As networks go offline, new networks come online, or ASes change the IP ranges they advertise, these changes are propagated via BGP so routers can continuously adjust their routing decisions.

I simplified the diagram above, but if you’ve read this far, I hope you now have a better idea of what happens when you visit a website—or your own app—and how and why it all happens so fast. I’m definitely going to make a video and a blog post on BGP and how it works, and I’ll write about it here as well, so I’ll keep you posted.

Thank you for reading this.

Each one of the microservice has its own SQL database (except for Cart, which uses Redis), all of which containerized. The idea of my experiment was to see how easy it really makes the life of a developer that’s been assigned to work on a distributed system with lots of moving parts.

Here’s what the solution structure looks like.

And here’s the architecture diagram that represents the action flow.

The flow starts with the user paying for the items they have in their shopping cart (Redis). Once the payment goes through, a call to Order microservice creates a new order with all the required information. Once the new order is created in the database the service pushes a new OrderCreated event to notify the whole system. Now, this is just a quick and dirty. In a real scenario we should consider something like The Saga Pattern to ensure that we don’t leave our system in a corrupt state (e.g., the insert in the order database failed, but we pushed an event for the new order)

To implement the event-based communication flow I used a library called NServiceBus. It is a paid solution, but available for free as long as your solution is not reaching a production environment (e.g., free for Dev, Test, QA, UAT).

Now, what exactly is Aspire?

Think of Aspire as a production-ready platform (from Microsoft) that allows you to build, test, deploy, debug, and run distributed applications. It provides built-in tooling for local development, containerization, orchestration, and observability, making it much easier to work with distributed systems.

Aspire really makes things so much easier. For example, see how easily I’ve added RabbitMQ as a messaging broker to my solution.

// RabbitMQ
var messaging = builder
    .AddRabbitMQ("messaging")
    .WithManagementPlugin(15672)
    .WithLifetime(ContainerLifetime.Persistent);

Here’s my SQL database.

// SQL Server
var sql = builder
    .AddSqlServer("sql")
    .WithLifetime(ContainerLifetime.Persistent);

And that’s my Redis cache.

// Redis
var cartcache = builder.AddRedis("cartcache")
    .WithLifetime(ContainerLifetime.Persistent);

And this is how I’m creating the Orders microservice, its own SQL database, and then injecting the RabbitMQ messaging that we declared above to be used in it for event-based communication.

// Catalog
var catalogDb = sql.AddDatabase("CatalogDb", "eCommerceDemo.Catalog");
var catalog = builder.AddProject<Projects.eCommerceDemo_Catalog>("catalog")
    .WithReference(catalogDb)
    .WaitFor(catalogDb)
    .WithReference(messaging)
    .WaitFor(messaging);

Tell me that isn’t easy!

If you’re curious about how this looks in action you should check my latest video where I give a detailed walkthrough. You’ll see how a single order creation triggers other services and we’ll even send an email.

If your app only needs server-to-browser notifications, then you really don’t need the heavy SignalR and all the packages, rules and protocols it comes with. You need Server-Sent events, and in .NET 10 they are extremely easy to implement.

In today’s blog post I’m going to show you how you can get started.

Today’s demo shows how to build real-time UI updates in .NET 10 without SignalR, using plain Server-Sent Events. An Azure Function simulates a weather sensor writing data to the database, while a Minimal API streams the updates live to a Blazor WASM frontend.

The solution consists of three projects:

• Blazor WASM (for UI)

• .NET 10 Web API (for SSE)

• .NET 10 Function App (for updating SQL database with fictious weather data)

• SQL Database (for storing sensor / weather data)

Required packages (for database manipulation):

• Microsoft.EntityFrameworkCore

• Microsoft.EntityFrameworkCore.SqlServer

I’m only going to share core code snippets here. See the full solution on GitHub here.

Database

Our database has only one table called WeatherForecasts with basic structure (Id for PK, CapturedAt, TemperatureC and Summary)

Function App (SSE.WeatherSensor)

Our Function App runs every 10 seconds and inserts weather data into the database, simulating a live sensor.

Here’s what the table looks like after it’s populated with weather data generated by the Function App.

API (SSE.API)

This is the API endpoint that implements SSE. It polls the database every 5 seconds and streams the latest weather data to connected clients (our Blazor WASM).

app.MapGet("api/weatherforecast", (HttpContext context, SSEDbContext dbContext) =>
{

    async IAsyncEnumerable<WeatherForecast> GetWeatherForecastStream([EnumeratorCancellation] CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            var latestForecast = await dbContext.WeatherForecasts
                .OrderByDescending(wf => wf.CapturedAt)
                .FirstOrDefaultAsync(cancellationToken);

            if (latestForecast != null)
            {
                yield return latestForecast;
            }

            await Task.Delay(5000, cancellationToken);
        }
    }

    if (context.Request.Headers["Accept"] == "text/event-stream")
    {
        return Results.ServerSentEvents(GetWeatherForecastStream(context.RequestAborted));
    }
    else
    {
        return Results.BadRequest("Unsupported Accept header. Use 'text/event-stream'.");
    }
});

UI (SSE.Web)

This is our client app that subscribes to the SSE endpoint and renders the live weather updates in real time.

@page "/weather"
@using System.Net.ServerSentEvents
@using System.Text.Json
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@inject HttpClient Http

<h3>Live Weather Sensor Feed</h3>

@if (forecast == null && string.IsNullOrEmpty(errorMessage))
{
    <p><em>Waiting for sensor data...</em></p>
}
else {
    <table class="table">
        <thead>
            <tr>
                <th>Time (Local)</th>
                <th>Temp (C)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>

            <tr style="border: 2px solid black;">
                <td>@forecast.CapturedAt.ToLocalTime().ToString("HH:mm:ss")</td>
                <td>@forecast.TemperatureC°C</td>
                <td>@forecast.Summary</td>
            </tr>
        </tbody>
    </table>
}


@if (!string.IsNullOrEmpty(errorMessage))
{
    <div class="alert alert-danger">@errorMessage</div>
}

@code {
    private WeatherForecast forecast;
    private string? errorMessage;

    public class WeatherForecast
    {
        public int Id { get; set; }
        public DateTimeOffset CapturedAt { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
    }

    protected override async Task OnInitializedAsync()
    {
        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Get, "https://localhost:7194/api/weatherforecast");
            request.Headers.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("text/event-stream"));

            using var response = await Http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
            using var stream = await response.Content.ReadAsStreamAsync();

            var options = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
            var parser = SseParser.Create(stream, (type, data) =>
                JsonSerializer.Deserialize<WeatherForecast>(data, options));

            await foreach (var item in parser.EnumerateAsync())
            {
                if (item.Data is not null)
                {
                    forecast = item.Data;

                    await InvokeAsync(StateHasChanged);
                }
            }
        }
        catch (Exception ex)
        {
            errorMessage = $"Connection lost: {ex.Message}";
            await InvokeAsync(StateHasChanged);
        }
    }
}

Demo

Here’s the whole solution in action.

TL;DR: If your use case is server-to-browser real-time updates only, you probably don’t need SignalR — SSE is simpler, cheaper, and easier to maintain. Make sure to consider it for your next project.

What is a Modular Monolith?

A Modular Monolith is a software architecture that runs as a single process, just like a traditional monolith. The difference is that instead of one large, tangled codebase, the application is explicitly split into well-defined modules.

Each module represents a separate domain and owns its own logic. The boundaries are clear, enforced in code, and intentional — not just folders pretending to be architecture, but separate class libraries.

What is a Module?

A module is a self-contained logical unit that represents a specific business capability (for example, Payments or Reviews). Its sole purpose is to model that specific business domain — exactly how you would design a microservice.

Each module behaves like a separate application focused on a single business use case. It has its own API layer and its own data store (a separate schema or even a separate database). In other words, it’s an independent application that happens to live inside the monolith, and it communicates with other modules only through its public API.

And this is the key point: even though all modules run inside a single process, they are designed so that, if needed, they can later be extracted into independent microservices with minimal friction.

Here’s how a typical module looks like.

Each module exposes its own public API, and that is the only way other modules are allowed to access its logic. This is extremely important because it enforces loose coupling, making modules easier to extract later — which is at the core of the Modular Monolith’s benefits.

In addition, every module owns its own data store — either a separate schema within a shared database or a completely separate database. Data ownership is strict and enforced at the module boundary.

In short, think of each module as an independent API that just happens to live inside the same application.

Why use Modular Monolith?

A Modular Monolith is powerful because it lets you start simple, while still enforcing clear boundaries that allow the system to scale later if — and only if — it actually becomes necessary.

You get the simplicity of a monolith today, but by designing proper modules, you’re deliberately preparing for a future where parts of the system may need to be distributed into microservices. If that time comes, the transition is far less painful than trying to break apart a traditional, tightly coupled monolith.

Yes, you can start directly with a microservices architecture. But in most cases, that’s a bad idea, even when you’re convinced you’ll eventually need it (this is exactly what Monolith First by Martin Fowler argues).

By building a Modular Monolith, you get several concrete benefits that help you ship faster and at lower cost — which, in today’s enterprise world, is non-negotiable (everyone wants it yesterday):

• Easy to start with — it’s still a monolith

• Simple CI/CD — a single deployable unit

• Clear boundaries — making future migration to microservices significantly easier

• Easier to scale when needed — both technically and organizationally

• Better maintainability and team ownership — teams work on modules without stepping on each other

Real Estate Platform

Let’s take a fictional real estate platform as an example — a place where people list their homes for others to buy. In this scenario, a Modular Monolith solution could look like this.

At this point, it’s important to understand what this diagram does not represent.

This is not a microservices architecture. All modules run inside a single process, are deployed together, and share the same runtime. There is no network communication between them, no service discovery, no distributed tracing, and no operational overhead.

Yet, from a design perspective, each module behaves as if it were a microservice.

Each module:

• Owns its business logic

• Exposes a public API

• Owns its data

• Has no direct access to other modules’ internals or databases

This is what gives the Modular Monolith its power: strong boundaries without distribution.

Module-to-Module Communication

So how do modules talk to each other? Let’s take Listings and Reviews as an example.

Imagine we’re building a page that needs to display a specific listing (for example, a house on XYZ Street) along with all the reviews people have left for it.

The Listings module should not reach directly into the Reviews database, and the Reviews module should not query Listings data directly. Instead, communication happens strictly through each module’s public API.

The application first calls the Listings module to fetch the listing data by listingId. Then, using the same identifier, it calls the Reviews module through its public API to retrieve all reviews associated with that listing.

Both modules:

• Access only their own database

• Expose explicit read models through their APIs

• Remain completely unaware of each other’s internal implementation

Even though these calls happen inside the same process, they are treated exactly like service-to-service calls. No shared repositories. No cross-module ORM access.

This discipline is what keeps the system modular.

If, at some point, the Reviews module needs to be extracted into a separate microservice, this flow remains largely unchanged — the in-process API call simply becomes a network call. The contract stays the same.

This is the core idea behind Modular Monolith communication: design for distribution, without paying the distribution cost upfront.

Modular Monolith Solution

To make this concrete, here’s how this looks in a real codebase.

The solution is structured around a Modules folders, where each module represents a distinct business capability — Accounts, Listings, Reviews, and so on.

Each module is fully self-contained and separate class library that follows the same internal structure built around Clean Architecture:

• API — the module’s public surface, exposed to other modules

• Application — use cases, orchestration, and business workflows

• Domain — core business logic and domain models

• Infrastructure — data access, external integrations, persistence

This is not accidental. Every module is treated as a mini application with clear ownership and explicit boundaries.

The Shared projects contain only truly cross-cutting concerns — things like the database abstraction, shared kernel primitives, or mediator implementation (a custom one I built since MediatR is now commercial). There is no shared business logic between modules.

At the top level, there’s a single API host that wires everything together and a single Web UI consuming the system — reinforcing the fact that this is still a single deployable unit, running in a single process.

This structure enforces discipline:

• Modules don’t reach into each other’s internals

• Data access stays inside module boundaries

• Communication happens only through public APIs

And most importantly, if one of these modules ever needs to become a standalone microservice, most of the work is already done — the boundaries, contracts, and responsibilities are already in place.

That’s the real power of a Modular Monolith: microservice-level design, without microservice-level complexity.

Lastly, let’s take a deeper look at one of the modules — the Listings module.

At first glance, you’ll notice that the module follows the same internal structure as the others: API, Application, Domain, and Infrastructure. This is intentional and consistent across all modules, reinforcing clear boundaries and ownership.

API

The API project is the module’s public entry point. It exposes endpoints (for example, ListingsEndpoints.cs) and defines how the outside world — including other modules — can interact with Listings. Nothing outside the module talks directly to its internals.

Application

The Application layer contains the use cases and orchestration logic. This is where the module’s behavior lives — not in controllers, not in infrastructure.

The important part here is the Features folder.

Each feature (like CreateListing, GetListingById, or GetUserListings) is implemented as a vertical slice — meaning everything related to that use case lives together. This follows Jimmy Bogard’s Vertical Slice Architecture.

Instead of grouping code by technical concerns (controllers, services, handlers), we group it by business intent.

Each feature typically contains:

• The request/command

• The handler

• Validation

• Any feature-specific logic

This makes features easy to understand, easy to modify, and easy to delete.

Domain

The Domain project contains the core business logic:

• Entities

• Value Objects

• Domain Events

This layer is pure business logic. It has no dependencies on infrastructure, frameworks, or external concerns. It represents the heart of the Listings domain.

Infrastructure

The Infrastructure project handles everything related to persistence and external systems — for example, database access and ORM configuration. This is the only place where the module touches technical details like EF Core.

Why this works so well

This combination — Modular Monolith + Clean boundaries + Vertical Slice Architecture — gives you:

• Strong separation between business domains

• Highly focused, readable features

• Minimal coupling between modules

• A structure that scales without becoming unmanageable

Each module is cohesive. Each feature is explicit. And the entire system remains a single, simple deployable unit.

Final Words

I hope this post helps you appreciate the Modular Monolith approach — and gives you a clear idea of how to build one.

I strongly believe you should always start small and avoid overengineering. Every large company started small, and they only scaled when it became necessary. Don’t start with expensive decisions. Build iteratively.

Don’t begin with the idea of building the next Netflix. Start with a basic streaming app, then add one feature, then another — but keep it simple. Once you see real demand, then you can justify adding complexity. Not before.

This is exactly why Modular Monolith fits my mindset so well. It keeps you on the right track: a single-process application, built with clear module boundaries around real business capabilities. And if your product succeeds and you truly need to scale out, you can evolve the right modules into microservices with far less pain.

And now we have Microsoft Agent Framework, which, according to Microsoft is… the best agentic framework that combines the strengths of Semantic Kernel and AutoGen.

I’ve heard that before. But as techies and architects, we need to be aware of what’s coming so we can prepare and make informed decisions about solutions at work.

In my newest YouTube video, I show a quick demo where we use the Microsoft Agent Framework and the A2A protocol to enable communication between agents, using tools to persist state in Cosmos DB.

Who knows if this is really the path forward for Microsoft? At the very least, it’s fun—and since it’s Sunday, why not give it a try?

It’s a lightweight local web app that looks like ChatGPT, but instead of relying on a single model, it lets multiple LLMs answer your question, critique each other, and then produce a final, consolidated result.

Here’s the core idea, quoting the repo:

Instead of asking a question to your favorite LLM provider (OpenAI GPT-5.1, Google Gemini, Anthropic Claude, xAI Grok, etc.), you can group them into your “LLM Council”.

Your query is sent to all of them through OpenRouter, they each give an answer, they review and rank each other’s work, and finally a Chairman LLM produces the final response.

And honestly — it’s brilliant.

Why This Is Cool

When you ask a single LLM a question, you’re trusting one model’s reasoning, training data, biases, and blind spots.

With LLM Council, a few things change:

• Multiple models answer the same question independently.

• They then evaluate each other’s responses.

• The system picks a “Chairman LLM” (you choose which) to read all answers and critiques, and then write a final, improved response.

It’s like having a panel of experts debate the prompt before speaking to you.

Why This is Cool?

LLMs behave differently:

• Some are great with code (Claude).

• Some are great coders and overall thinkers (GPT-5.1).

• Some are creative and fast (Gemini).

• Some are cheap and fast (Mixtral, Qwen, etc.).

Instead of guessing which one is best for each prompt, LLM Council lets them collaborate.

As models become more specialized, this “debate → critique → consolidate” pattern becomes extremely powerful.

It’s basically a tiny research lab running on your laptop.

Trying It Out

The repo is simple to clone and run. Basically, you just follow the README and you’re done. You’ll need an OpenRouter API key — everything else works out of the box.

Demo

Running It on Windows

If you’re on Windows, there’s one extra step: the repo uses a start.sh shell script.
Windows doesn’t run .sh files natively, so you need a shell environment.

I used Git Bash (included with Git for Windows) to run the script:

Mac and Linux users don’t need this — both platforms support shell scripts out of the box.

Here’s a quick demo of how this works with a prompt “How to become a great solution architect? I want to be able to build systems like Netflix and Uber.”

That’s why in today’s post, I’ll walk you through how I managed to make it work and, hopefully, help you apply it in your own projects.

The API

First, here’s how my API looks. It receives the file from Copilot Studio, performs basic validation, and uploads it to a storage account.

    [HttpPost(”upload”)]
    public async Task<IActionResult> Upload([FromBody] UploadFileRequest request)
    {
        if (string.IsNullOrWhiteSpace(request.ContentBytes))
            return BadRequest(”contentBytes is missing”);

        if (string.IsNullOrWhiteSpace(request.Name))
            return BadRequest(”name is missing”);

        // Handle possible data:image/png;base64,...
        var base64 = request.ContentBytes.Contains(’,’)
            ? request.ContentBytes.Split(’,’).Last()
            : request.ContentBytes;

        byte[] fileBytes;

        try
        {
            fileBytes = Convert.FromBase64String(base64);
        }
        catch
        {
            return BadRequest(”Invalid base64 content”);
        }

        var container = _blobServiceClient.GetBlobContainerClient(”uploadedfiles”);
        await container.CreateIfNotExistsAsync();

        var blob = container.GetBlobClient(request.Name);

        using var stream = new MemoryStream(fileBytes);
        await blob.UploadAsync(stream, overwrite: true);

        return Ok(new
        {
            FileName = request.Name,
            Size = fileBytes.Length,
            Status = “Uploaded”
        });
    }
}

Here’s my UploadFileRequest request model. This is the format I am sending from Copilot Studio, so it needs strictly match it.

public class UploadFileRequest
{
    public string ContentBytes { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
}

Copilot Studio Flow

Next, I created a flow for the whole file upload process. The flow expects a file, then it runs an HTTP post against my API, attaching the file content and the file name.

contentBytes: triggerBody()?[’file’][’content’]

To add it, use the F(x) icon on the right.

Then add it here and save it.

Do the same for the name below.

name: triggerBody()?[’file’]?[’name’]

In the end, I added a condition that checks the response from the file upload. If it returns 200, it uses the Respond to agent action to confirm the file was uploaded successfully. Otherwise, it uses the same action to indicate that the upload failed.

Agent

Now that we have the flow created, we need to create an agent. I named mine File Upload Agent.

Topic

The last step is to create a topic that gets triggered any time a person mentions that they want to upload a file.

Name it File Upload

Below is the topic setup. It defines what this topic is about — in our case, file uploads — and what will trigger it.
When the user asks for a file to be uploaded, the agent responds with a question prompting them to attach the file in the chat.
In the next step, we call the flow created earlier. As input, we set File content (Record) to First(System.Activity.Attachments), which grabs the first attached file. If you want to process all files, simply remove First.
For the output, we assign the response to a variable called OutputMsg and display it inside a Message element.

And that’s it. If you follow the same approach, you’ll be able to upload files from Copilot Studio (directly in the agent chat) to your own API.

While researching how to do this, I couldn’t find a single resource or piece of documentation on it, so I hope this helps others as well.

Azure Cosmos DB is a fully managed Platform as a Service (PaaS) and serves as Microsoft’s flagship distributed database solution.

How you design the partitioning strategy for your Cosmos DB is undoubtedly one of the most critical architectural decisions you’ll make when building a solution on Microsoft Azure’s highly scalable, globally distributed NoSQL database.

Request Units (RUs)

Each operation you perform in Cosmos DB — whether it’s a read, write, update, or query — consumes a certain number of Request Units (RUs).

RUs represent a normalized measure of system resources such as CPU, memory, and IOPS (input/output operations per second) required to perform a given operation. This abstraction makes performance predictable — instead of worrying about the underlying infrastructure, you only manage RUs.

The amount of RUs consumed depends on several factors:

• Item size – larger JSON documents consume more RUs.

• Operation type – writes and queries typically cost more than point reads.

• Query complexity – filters, cross-partition queries, and sorting increase RU consumption.

• Indexing – since Cosmos DB automatically indexes all properties by default, write operations cost more if you have large or deeply nested documents.

You provision throughput in RUs per second (e.g., 400 RU/s), which defines how much performance capacity your container or database can handle. If your workload exceeds that capacity, Cosmos DB starts to throttle requests, returning a 429 (Request Rate Too Large) response until throughput is available again.

You can monitor RU consumption using the Azure Portal, SDK, or query metrics to identify and optimize expensive operations.

Basic Database Structure

In the Azure Cosmos DB NoSQL API, the data model consists of three main components — database, container(s), and item(s) — as illustrated in the diagram below.

• A database is the top-level logical namespace that groups one or more containers.

• A container is the fundamental unit of scalability and throughput. It holds a collection of JSON documents (items) and defines the partition key used to distribute data across partitions.

• An item is a single JSON document stored within a container. Each item must include an id property and a value for the partition key.

What is Partitioning?

Partitioning literally means dividing into parts. In Azure Cosmos DB, partitioning is a core mechanism that enables your application to scale efficiently and maintain consistent performance at any size.

Whenever you create a container, you must define a partition key — a property within your JSON documents that determines how data is distributed across partitions. The partition key choice directly affects scalability, query performance, and cost efficiency.

Each partition key value creates a virtual bucket called a logical partition, which contains all items that share the same partition key value. Choosing the right partition key is critical to achieving balanced data distribution. Ideally, the partition key should contain a value that never changes and one that has high cardinality — meaning it should have many unique values to evenly distribute data and requests across multiple logical partitions.

Otherwise, you may end up with what’s known as a hot partition — a single logical partition that stores a disproportionately large share of your data or handles most of the requests. This can lead to uneven throughput consumption, throttling, and degraded performance as that single partition becomes a bottleneck for your workload.

A logical partition resides within a physical partition. Depending on your data volume and throughput, a container can span multiple physical partitions. Each physical partition hosts one or more logical partitions, and Azure Cosmos DB automatically manages this distribution behind the scenes to maintain performance and scalability.

Now, let’s dive a bit deeper into partitioning strategy and discuss how to choose an effective partition key.

Partitioning Strategy

Let’s imagine we’re building a simple e-commerce website, similar to Amazon, where we have products, categories, and reviews. When users visit the site, they see a list of categories, select one, and then browse the products that belong to it.

For the sake of simplicity, we won’t attempt to replicate Amazon’s full complexity here — instead, we’ll focus on a simplified example that helps illustrate the fundamentals of partitioning in Azure Cosmos DB.

So, based on the structure we just defined, we’ll have three containers — one for products, one for categories, and one for reviews.

Now comes the interesting (and often challenging) part: choosing the right partition key for each container. The partition key determines how data is distributed and accessed, so picking the right one is essential for achieving scalability, balanced throughput, and optimal query performance.

Application accessing patterns

Whenever you choose a partition key, your starting point should always be how your application accesses the data. The way users query and interact with your data model should guide your partitioning strategy.

For our fictitious e-commerce app, when a user visits the website, they first see a list of categories and select one. After choosing a category, they’re shown a list of products that belong to it. From there, they can click on a specific product to view its details, add it to the cart, or purchase it.

Now, based on this, let’s choose the right partition key for each container, starting with the simplest one - categories.

categories

This one is easy. Since we don’t have that many categories (tens and not thousands) we’ll use the id as a partition key for it. What this means is that for each category we’ll have a single logical partition.

products

You might be tempted to use the product’s ID as the partition key here as well — it offers high cardinality and would evenly distribute data across partitions. While that’s not necessarily wrong, remember that our partitioning strategy is driven by how the application accesses data, not just by distribution.

In our e-commerce example, users typically browse products by category, not by individual product ID. That’s why a better choice for the Products container is CategoryID as the partition key — it aligns with the most common access pattern (fetching all products within a category) while still providing good distribution and query performance.

This approach keeps queries efficient, since the data you need (all products in a given category) is co-located within the same logical partition. As a result, Cosmos DB doesn’t have to perform a cross-partition query, which improves latency, throughput efficiency (RUs), and overall performance.

reviews

This one should be straightforward. In any e-commerce platform, reviews naturally belong to the product they describe — users leave feedback directly under the product page for others to see.

To maintain high cardinality and maximize query efficiency, we’ll use the ProductID as the partition key for the Reviews container. This way, all reviews for a given product are stored within the same logical partition, allowing the application to retrieve them with a single, efficient query — no cross-partition scans, no unnecessary RU consumption, and minimal latency.

For example, whenever you’re fetching a product’s reviews, you’ll run a query like this:

SELECT * 
FROM r 
WHERE r.ProductId = "123"

This query retrieves all reviews for the product with ID 123. Since all reviews for a given product reside in the same logical partition, Cosmos DB executes this as a single-partition query, ensuring low latency and efficient RU consumption.

Thanks

That’s a quick overview of the Cosmos DB partitioning fundamentals and the practical approach I personally use when designing data models. These are the core concepts that, once mastered, make it much easier to build scalable, high-performing solutions in Azure.

YouTube

Here’s a 10-minute video where I explain all this + a code demo.

If you want to really go deep into this topic, here’s links that I recommend:

• Partitioning and horizontal scaling - Azure Cosmos DB | Microsoft Learn

• Model and Partition Data using a Real-World Example - Azure Cosmos DB for NoSQL | Microsoft Learn

Most of the tutorials out there concentrate on building and deploying public containers that can be accessed from everyone over the internet. This approach, however, is not ideal and is rarely used in real production environments.

That’s why today I will show you how you can deploy two containers, one accessible from the internet (the web app UI) and another one that’s only accessible by the first container (the backend).

Keep in mind that this is not a full-blown tutorial. You should clone the repo and study it on your own. You can find the source code of my demo here: kaldren/acr-private-demo

What is Azure Container Apps

Azure Container Apps is a serverless platform for deploying and running containers. It is built on top of Kubernetes, and it abstracts away most of its complexity for you. Basically, things like scaling, container orchestration, configuration and server updates are all done for you by Azure.

Bicep

For this demo I’ve decided to use Bicep to deploy my infrastructure. You can check the source code for a more detailed walkthrough.

Container Communication in Azure Container Apps

There are a few ways for containers to talk to each other in ACA.

• Default fully qualified domain name (FQDN)

• A custom domain name

• The container app name, for instance http://<APP_NAME> for internal requests

• A Dapr URL

Today I will show you how the third option above, connecting via the app name for internal requests.

Let’s take a look at the bicep files now.

Repo Walkthrough

Azure Container Registry

First, to be able to deploy containers in Azure via ACA you need to have Azure Container Registry (ACR). This service can build and store your container images. Once the image is in the ACR your Container App can pull from it and use the image to build and deploy a container instance.

@description(’Name of the Container Registry’)
param containerRegistryName string

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ = {
  name: containerRegistryName
  location: resourceGroup().location
  identity: {
    type: ‘SystemAssigned’
  }
  sku: {
    name: ‘Basic’
  }
  properties: {
    adminUserEnabled: true
  }
}

output containerRegistry object = {
  name: containerRegistry.name
  endpoint: containerRegistry.properties.loginServer
}

Managed Identity

Once we deploy the ACR we need to create another resource - a Managed identity. We will then assign the role AcrPull to it for the ACR that we created above. This will allow it to pull container images from the registry. We will then assign this identity to our container apps which would allow them to pull the images from the registry themselves.

param containerRegistryName string

resource managedIdentity ‘Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview’ = {
  location: resourceGroup().location
  name: ‘mi-containerapp’
}

// Set ArcPull role assignment for the managed identity on the ACR
resource acrPull ‘Microsoft.Authorization/roleAssignments@2022-04-01’ = {
  name: guid(managedIdentity.id, ‘AcrPull’)
  scope: containerRegistry
  properties: {
    roleDefinitionId: subscriptionResourceId(
      ‘Microsoft.Authorization/roleDefinitions’,
      ‘7f951dda-4ed3-4680-a7ca-43fe172d538d’ // AcrPull role ID
    )
    principalId: managedIdentity.properties.principalId
    principalType: ‘ServicePrincipal’
  }
}

output managedIdentityId string = managedIdentity.id

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ existing = {
  name: containerRegistryName
}

Azure Container Apps

We will deploy two containers - one for the frontend and one for the backend.

param location string = resourceGroup().location
param containerAppEnvironmentName string
param containerAppName string
param containerRegistryName string
param imageName string
param imageTag string

resource containerAppEnvironment ‘Microsoft.App/managedEnvironments@2025-02-02-preview’ = {
  name: containerAppEnvironmentName
  location: location
  properties: {}
}

resource containerApp ‘Microsoft.App/containerApps@2022-03-01’ ={
  name: containerAppName
  location: location
  identity: {
    type: ‘SystemAssigned, UserAssigned’
    userAssignedIdentities: {
      ‘${managedIdentity.id}’: {}
    }
  }
  properties:{
    managedEnvironmentId: containerAppEnvironment.id
    configuration: {
      ingress: {
        targetPort: 9696
        external: true
      }
      registries: [
        {
          server: ‘${containerRegistry.name}.azurecr.io’
          identity: managedIdentity.id
        }
      ]
    }
    template: {
      containers: [
        {
          image: ‘${containerRegistry.name}.azurecr.io/${imageName}:${imageTag}’
          name: imageName
        }
      ]
    }
  }
}

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ existing = {
  name: containerRegistryName
}

resource managedIdentity ‘Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview’ existing = {
  name: ‘mi-containerapp’
}

The most important sections (in bold) to note are:

• identity section: Here we assign the managed identity created above to the app

• registry section: We use the identity to authenticate with the ACR

• ingress section: We allow incoming external requests (from the internet) because the web app needs to be accessible from everyone

Here’s the deployed frontend container app.

Now, let’s take a look at the backend container app.

param location string = resourceGroup().location
param containerAppEnvironmentName string
param containerAppName string
param containerRegistryName string
param imageName string
param imageTag string

resource containerAppEnvironment ‘Microsoft.App/managedEnvironments@2025-02-02-preview’ = {
  name: containerAppEnvironmentName
  location: location
  properties: {}
}

resource containerApp ‘Microsoft.App/containerApps@2022-03-01’ ={
  name: containerAppName
  location: location
  identity: {
    type: ‘SystemAssigned, UserAssigned’
    userAssignedIdentities: {
      ‘${managedIdentity.id}’: {}
    }
  }
  properties:{
    managedEnvironmentId: containerAppEnvironment.id
    configuration: {
      ingress: {
        targetPort: 8686
        external: false
      }
      registries: [
        {
          server: ‘${containerRegistry.name}.azurecr.io’
          identity: managedIdentity.id
        }
      ]
    }
    template: {
      containers: [
        {
          image: ‘${containerRegistry.name}.azurecr.io/${imageName}:${imageTag}’
          name: imageName
        }
      ]
    }
  }
}

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ existing = {
  name: containerRegistryName
}

resource managedIdentity ‘Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview’ existing = {
  name: ‘mi-containerapp’
}

The only difference here is the external ingress is set to false. That’s because we don’t want this container to be accessible from the internet but only from the network inside the Azure Container App Environment.

Here’s how the backend container app looks like.

main.bicep

Here we add all bicep files as modules. For example:

module acr ‘modules/container-registry.bicep’ = {
  name: ‘acr-${randomSuffix}’
  params: {
    containerRegistryName: containerRegistryName
  }
  dependsOn: [
    rg
  ]
  scope: resourceGroup(resourceGroupName)
}

(Check the repo for the full file content)

deploy.sh

I’ve written a shell script that does the deployment for me. Here’s part of it.

# az login -- Might need to login first. Uncomment if needed.

az deployment sub create \
  --name rgDeployment \
  --location eastus \
  --parameters params/main.dev.bicepparam deployContainerApp=false

# # Login to ACR
ACR_LOGIN_SERVER=$(az acr show -n $ACR_NAME --query loginServer -o tsv)
az acr build --registry $ACR_NAME \
  --image $BACKEND_IMAGE:$BACKEND_TAG \
  --file ../backend/Dockerfile ../backend

ACR_LOGIN_SERVER=$(az acr show -n $ACR_NAME --query loginServer -o tsv)
az acr build --registry $ACR_NAME \
  --image $FRONTEND_IMAGE:$FRONTEND_TAG \
  --file ../frontend/Dockerfile ../frontend

az deployment sub create \
  --name rgDeployment \
  --location eastus \
  --parameters params/main.dev.bicepparam deployContainerApp=true

What this does is it is first deploying the ACR and managed identity resources without the container apps (see the deployContainerApp is set to false). That’s because I want to build and deploy the images for the frontend and backend first, so they are available for when we start deploying the container apps.

Dockerfile

Nothing fancy here. We just set the version to Python 3.13, install requirements.txt and run the apps on ports 8686 and 9696.

FROM python:3.13
WORKDIR /app
ENV HELLO_MESSAGE=”Hello from the backend!”
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8686
CMD [”uvicorn”, “main:app”, “--host”, “0.0.0.0”, “--port”, “8686”]

FROM python:3.13
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 9696
# Run streamlit app on container’s port 9696
CMD [”streamlit”, “run”, “main.py”, “--server.port=9696”, “--server.address=0.0.0.0”]

compose.yaml

This one I used for local development and testing.

Talking Containers

Let’s take a quick look at the frontend code to see how, once we deploy the infrastructure, we are able to connect to the backend container via the private network and not the public internet.

import streamlit as st
import requests

st.title(”Container Demo UI”)
st.text(”This text will change if the backend is called successfully.”)

API_URL = “http://app-backend-dev”

def call_hi_get():
    try:
        response = requests.get(f”{API_URL}/hi”)
        if response.status_code == 200:
            st.text(response.json().get(”message”, “No message in response”))
    except requests.RequestException as e:
        st.text(f”Error reaching backend: {e}”)
    
if st.button(”Call /hi endpoint!”):
    response = call_hi_get()

Here we’re using the app name, which in this case is app-backend-dev. We’re not using any FQDNs or FQDNs with internal in their url (e.g. https://app-frontend-dev.internal.alabala-xxx.eastus.azurecontainerapps.io) - I’ve seen this approach presented by folks, but I really, really hate it, because it is ugly and it requires you to figure out the actual FQDN first.

This approach is much cleaner - it relies on the service discovery system of ACA, which is much cleaner solution. We don’t have to care what the FQDN is.

Azure

Here’s our infrastructure in Azure.

If you want to learn more, then clone the repo, take a look and try it on your own.

Thanks.

What is MCP?

MCP stands for Model Context Protocol, and it is an open-source standard for connecting your AI applications to external systems.

Those systems can live on your own machine, like your filesystem, or be deployed thousands of kilometers away in some distant server, like the Azure MCP server.

In a nutshell, MCP allows you to easily integrate your AI application with other sources, like data stores, APIs, and etc.,

How MCP works?

MCP uses the client-server architecture that we are all familiar with. There are three main actors involved in the whole process:

1. MCP Host

   An AI application, powered by language model that supports MCP. Examples of such applications are Claude Desktop, Claude Code, GitHub Copilot.

   Keep in mind that for this to work the language model needs to support tool calling and not every model supports this. Also, I’m saying language model and not large language model (LLM), because nothing stops a small language model (SLM) from being able to use MCP, if the model supports it.

2. MCP Client

   An MCP Host creates a client, which then connects to an MCP Server. Each MCP Server has its own dedicated client.

3. MCP Server

   This is what provides the extended functionalities to your AI application. This is basically what we called “external system” earlier. Think of it as an API that your AI-powered application can call. And like we said, it can live on the same machine as your AI application or anywhere on the internet.

The following is a basic diagram of the whole process.

One thing to note is the two-way connection between the MCP Client and the MCP Server. That’s because the protocol allows for both the client AND the server to send messages to each other.

Features of MCP

So, what does MCP gives us? There are a few options available.

1. Tools

   These are functions provided by the MCP server that an LLM can call. You can think of them like API endpoints if you want. These functions could be calling a database, another API or executing any kind of business logic or integration. Tools are without question the most powerful feature of MCP.

2. Resources

   Read-only data sources that supply contextual information, such as file contents, database schemas, or API documentation.

3. Prompts

   Pre-built templates for guiding the model in using specific tools and resources.

These are all features that the MCP Server provides. There are also features that the MCP Client provides and that’s why the connection above is bidirectional. However, these are not that interesting for our understanding of MCP and for this demo, so if you want to learn more, please read the docs, which are really good.

Now, let’s build our remote MCP server.

requirements.txt

fastmcp

We’re going to be using FastMCP to build our server.

main.py

from fastmcp import FastMCP

mcp = FastMCP("Demo MCP")

@mcp.tool
def call_the_ceo() -> str:
    return "Calling the CEO... DONE!"

@mcp.tool
def send_email(to: str, subject: str, body: str) -> str:
    return f"Email sent to {to} with subject '{subject}' and body '{body}'"

@mcp.tool
def weather_info(location: str) -> str:
    return f"The weather in {location} is sunny with a high of 999°F."

if __name__ == "__main__":
    mcp.run()

We defined 3 tools. One that calls the CEO, another one that sends email and third one for weather info.

Dockerfile

# Use official Python image
FROM python:3.12-slim

# Set working directory
WORKDIR /app

# Copy requirements and source code
COPY requirements.txt ./
COPY main.py ./

# Install dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Expose port
EXPOSE 8000

# Set entrypoint
CMD ["fastmcp", "run", "./main.py:mcp", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

Since we’re going to use containers, we need Dockerfile. We’re first going to run this locally using Docker Desktop and test it with a tool called MCP Inspector. Then we will push this to Azure Container Registry and then run it on Container Apps.

Make sure you install the packages inside virtual environment and then run it.

uv venv
uv pip install -r .\requirements.txt
.venv\Scripts\activate

Now, let’s build our image.

docker build -t mcp-server-demo .

Run the image

docker run --name mcp-server-demo --rm -p 8000:8000 `
   -e HOST=0.0.0.0 -e PORT=8000 `
   mcp-server-demo

Now, let’s run the MCP Inspector. Inside the project folder, run the following.

npx @modelcontextprotocol/inspector fastmcp run .\main.py

Click Connect and if all done correctly, you should see the following.

Click on Tools and you should see all the tools that we have exposed. You can test each one of them if you want by providing the required parameters and clicking on Run Tool.

That’s great, we’ve tested the MCP server, and we saw it working locally. Now, let’s deploy this to Container Apps and use it remotely.

Deploy to Container Apps (Steps):

1. Create resource group in Azure

2. Create Azure Container Registry

3. Log into your container registry using azure cli

   az acr login --name [YOUR AZURE CONTAINER REGISTRY NAME]

4. Tag your container image

   docker tag mcp-server-demo [YOUR CONTAINER REGISTRY NAME].azurecr.io/mcp-server-demo:latest

5. Push to Azure Container Registry

   docker push [YOUR CONTAINER REGISTRY NAME].azurecr.io/mcp-server-demo:latest

6. Create Container App and in the set-up steps add the image you just pushed. Also, don’t forget to enable external traffic (Ingress option).

7. Once deployed, copy your container app’s URL

   

8. Open Claude Desktop (assuming you have it installed)

9. On the left screen at the bottom click on your user and then to Settings

   

10. Click on Developer and then on Edit Config

11. Open claude_desktop_config.json if it didn’t open automatically

12. Add the following snipper and replace [YOUR CONTAINER APP URL] with your actual container app url you copied earlier.

    {
      "mcpServers": {
        "custom-mcp": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "[YOUR CONTAINER APP URL]"
          ]
        }
      }
    }
    

13. Install custom-mcp package (the one we used above)

    npm i -g mcp-remote

14. Open Claude Desktop

Now, if you’ve followed along (and if I didn’t miss any step) you shouldn’t see any errors. Also, you should see the remote MCP server by clicking on the bar icon. Make sure it is enabled.

Now, let’s test this with the following prompt.

call the ceo

If everything was done correctly, you should see something similar to the following.

Choose either Allow always as we trust our own MCP server.

Here’s the result:

As you can see this actually worked. Now, let’s ask about the weather.

We can see that it says it’s 999F, which is exactly what we put in our code above. It works!

Now, let’s send an email, but let’s see how the LLM can provide a better user experience on its own, without us explicitly programming it to do so.

Here, if I wanted to send email directly, I would’ve provided the parameters. But instead, I said that I want to send an email and the LLM knows what parameters the tool needs in order for the email to be sent - email address, subject and body. And it asks me for that. Smart, and cool!

Now, let’s send the email.

Honestly, I’m too tired to fix any grammar mistakes at this point and am not going to use AI to do that either. I hope you found this quick demo useful!

Until next time!

Today, I’ll show you a quick way to experiment with it. For more details, check the official documentation.

Prerequisites

To follow along, make sure you have the following installed:

• Python

• Claude Desktop

• uv

Step 1: Set up the project

Windows

# Create a new directory for our project
uv init fakedb
cd fakedb

# Create virtual environment and activate it
uv venv
.venv\Scripts\activate

# Install dependencies
uv add mcp[cli]

# Create our server file
code fakedb.py

macOS

# Create a new directory for our project
uv init fakedb
cd fakedb

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]"

# Create our server file
touch fakedb.py

Step 2: Build a simple MCP server

Let’s add an endpoint to our MCP server that retrieves user information by user ID.

fakedb.py

This script creates a simple MCP server named fakedb with one tool, get_user_info. The tool takes a user ID, looks it up in a hardcoded dictionary (fake_db), and returns the matching user’s name and age. You could make this more interesting by integrating a real database and performing an actual query, but for simplicity, we’re keeping it in-memory here.

from typing import Any
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("fakedb")

@mcp.tool()
def get_user_info(user_id: str) -> dict[str, Any] | None:
    """Get user information from the database.

    Args:
        user_id: The ID of the user to retrieve.
    """

    # Here we're simulating a real database lookup 
    # (you can try with a real one to make it more interesting)
    fake_db = {
        "1234": {"name": "Alice", "age": 30},
        "5678": {"name": "Bob", "age": 25},
    }
    return fake_db.get(user_id)

if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='stdio')

Step 3: Connect to Claude Desktop

Windows

Open:

%APPDATA%\Claude\claude_desktop_config.json

macOS

Open:

~/Library/Application Support/Claude/claude_desktop_config.json

Replace the file contents with:

{
  "mcpServers": {
    "userDatabase": {
      "command": "uv",
      "args": [
        "--directory",
        "<<FULL PATH TO YOUR PROJECT DIRECTORY>>",
        "run",
        "fakedb.py"
      ]
    }
  }
}

This configuration creates a new MCP server connection called userDatabase. The command and args simply run your MCP server.

Restart Claude Desktop, and you should see your new MCP server with one endpoint, called get_user_info.

Step 4: Test it in Claude

Now, if you ask Claude for user information (for example, “Give me all you have about user with id 1234 in tabular format”), the LLM will:

1. Detect the get_user_info tool.

2. Call it with the provided user_id.

3. Return the result in a neat, tabular format, exactly how we defined it.

You can see from the image above the prompt, the tool that was used and the output.

So this is it! A quick and neat way to test what MCP is and how it works without writing lots of complex code.

Thanks for reading!

Here’s a quick overview of how you can make it happen.

To keep things simple, I’ve used TigerCloud to spin up a PostgreSQL instance in the cloud.

Now, back to code.

general.txt

For the purpose of this demo, I’ve used Python’s Q&A section in their documentation that you can see here: General Python FAQ — Python 3.13.5 documentation

You can either copy the text from that page, or click Download to download the whole docs, then go to faq folder and take the general.txt from there and put it in your solution.

requirements.txt

Here are all the packages I needed:

openai
pandas
numpy
psycopg2-binary
pgvector
dotenv

.env

For the demo I had to get my OpenAI key as well as the connection string from TigerCloud:

OPENAI_API_KEY=<YOUR OPENAI API KEY HERE>
TIMESCALE_CONNECTION_STRING=<YOUR TIMESCALE CONNECTION STRING HERE>

utils.py

import numpy as np
import openai
from pgvector.psycopg2 import register_vector

# Function to process input with retrieval of most similar documents from the database
def process_input_with_retrieval(user_input, conn):
    delimiter = "```"

    #Step 1: Get documents related to the user input from database
    related_docs = get_top3_similar_docs(get_embeddings(user_input), conn)

    # Step 2: Get completion from OpenAI API
    # Set system message to help set appropriate tone and context for model
    system_message = f"""
    You are a friendly chatbot. \
    You can answer questions about Python, the programming language. \
    You respond in a concise, technically credible tone. Always use ONLY the data from the context and DO NOT PROVIDE any additional information. If you can't find the answer in the context, say "I don't know". Even if you find something that you think is not correct, but if it is in the context - say it.
    """

    # Prepare messages to pass to model
    # We use a delimiter to help the model understand the where the user_input starts and ends
    messages = [
        {"role": "system", "content": system_message},
        {"role": "user", "content": f"{delimiter}{user_input}{delimiter}"},
        {"role": "assistant", "content": f"Relevant Python information: \n {related_docs[0][0]} \n {related_docs[1][0]} {related_docs[2][0]}"}   
    ]

    final_response = get_completion_from_messages(messages)
    return final_response

# Helper function: get text completion from OpenAI API
def get_completion_from_messages(messages, model="gpt-4o", temperature=0, max_tokens=1000):
    openai_client = openai.OpenAI()
    response = openai_client.chat.completions.create(
        model=model,
        messages=messages,
        temperature=temperature, 
        max_tokens=max_tokens, 
    )
    return response.choices[0].message.content

# Helper function: Get top 3 most similar documents from the database
def get_top3_similar_docs(query_embedding, conn):
    embedding_array = np.array(query_embedding)
    # Register pgvector extension
    register_vector(conn)
    cur = conn.cursor()
    # Get the top 3 most similar documents using the KNN <=> operator
    cur.execute("SELECT content FROM embeddings ORDER BY embedding <=> %s LIMIT 3", (embedding_array,))
    top3_docs = cur.fetchall()
    return top3_docs

# Load text file content (duh!)
def load_text_file(file_path):
    with open(file_path, 'r', encoding='utf-8') as file:
        return file.read()

# Function to chunk text into smaller pieces
def chunk_text(text, num_chunks):
    """
    Split text into a specified number of chunks.
    
    Args:
        text (str): The text to be chunked
        num_chunks (int): Number of chunks to create
        
    Returns:
        list: List of text chunks
    """
    if num_chunks <= 0:
        raise ValueError("Number of chunks must be greater than 0")
    
    if not text:
        return [""] * num_chunks
    
    text_length = len(text)
    chunk_size = text_length // num_chunks
    remainder = text_length % num_chunks
    
    chunks = []
    start = 0
    
    for i in range(num_chunks):
        # Add one extra character to the first 'remainder' chunks
        current_chunk_size = chunk_size + (1 if i < remainder else 0)
        end = start + current_chunk_size
        chunks.append(text[start:end])
        start = end
    
    return chunks

# Function to get embeddings for a given text using OpenAI API
def get_embeddings(text):
    openai_client = openai.OpenAI()
    response = openai_client.embeddings.create(
        model="text-embedding-3-small",
        input = text.replace("\n"," ")
    )
    return response.data[0].embedding

main.py

from dotenv import load_dotenv, find_dotenv
import os
import openai
import pandas as pd
import numpy as np
import psycopg2
from utils import chunk_text, get_embeddings, load_text_file, process_input_with_retrieval
from psycopg2.extras import execute_values
from pgvector.psycopg2 import register_vector
_ = load_dotenv(find_dotenv()) 
openai.api_key  = os.environ['OPENAI_API_KEY'] 

new_list = []
text = load_text_file('general.txt')

# You can change the number of chunks here based on your needs and the size of the text
chunks = chunk_text(text, 5)

for i in range(len(chunks)):
    embedding = get_embeddings(chunks[i])
    new_list.append([chunks[i], embedding])

df = pd.DataFrame(new_list, columns=['content', 'embedding'])

print(f"Created DataFrame with {len(df)} rows")

connection_string  = os.environ['TIMESCALE_CONNECTION_STRING']

# Connect to PostgreSQL database in Timescale using connection string
conn = psycopg2.connect(connection_string)
cur = conn.cursor()

#install pgvector
cur.execute("CREATE EXTENSION IF NOT EXISTS vector;")
conn.commit()

#install pgvectorscale
cur.execute("CREATE EXTENSION IF NOT EXISTS vectorscale CASCADE;")
conn.commit()

# Create table to store embeddings and metadata
table_create_command = """
-- Remove table embeddings if it exists
DROP TABLE IF EXISTS embeddings;
CREATE TABLE embeddings (
            id bigserial primary key, 
            content text,
            embedding vector(1536)
            );
            """

cur.execute(table_create_command)
cur.close()
conn.commit()


#Batch insert embeddings and metadata from dataframe into PostgreSQL database
register_vector(conn)
cur = conn.cursor()

# Prepare the list of tuples to insert
data_list = [(row['content'], np.array(row['embedding'])) for index, row in df.iterrows()]

# Use execute_values to perform batch insertion
execute_values(cur, "INSERT INTO embeddings (content, embedding) VALUES %s", data_list)

# Commit after we insert all embeddings
conn.commit()

# Create an index on the data for faster retrieval
cur.execute('CREATE INDEX embedding_idx ON embeddings USING diskann (embedding);')
conn.commit()

input = 'Is Python portable?'

response = process_input_with_retrieval(input, conn)
print(input)
print(response)

Here’s the outcome

You can play around with this by changing the input, the data, etc.

All in all, it works great. And the fact that you are using one of the most widely used relational databases as your vector store for RAG is super convenient.

Thanks:

• PostgreSQL as a Vector Database: A Pgvector Tutorial | TigerData

This blog post is meant to give you a high-level overview of how I approached it, not a full step-by-step tutorial.

You can watch the video at the end to see the app in action.

The Onboarding App

I built a simple onboarding web app for, you guessed it, onboarding new employees in a company.

The app takes three inputs: the employee’s full name, email, and department. Behind the scenes, it creates three agents:

• department_rag_agent uses Azure AI Search to perform a vector-based RAG (see RAG and generative AI - Azure AI Search) search and find relevant onboarding information for the specified department (for example, Software Engineering).

• discord_agent is responsible for sending a welcome message on Discord, which includes the employee’s details and any department-specific information returned by the RAG agent.

• onboarding_agent acts as the orchestrator. It first invokes the RAG agent to gather relevant information, then passes the results to the Discord agent to send the final message.

The entire process is coordinated automatically once the onboarding form is submitted.

Here’s the end result message in Discord:

Project Structure Overview

This project showcases a multi-agent onboarding flow using Azure AI Foundry Agent Service. The main folders are:

• src/api/ – Contains the FastAPI backend with agent logic, tools, and utilities.

• func-api/ – An Azure Function App that exposes an endpoint for sending Discord messages. This is needed because connected agents do not support local function calls (see How to use connected agents - Azure AI Foundry | Microsoft Learn).

• web/ – A React.js frontend that serves as the UI for triggering the onboarding flow.

Environment Setup

• Azure Function App (for webhook to Discord)

• Azure AI Search (for RAG)

• Azure OpenAI (for embedding model)

• Azure AI Foundry project (for LLM)

To run the app locally or deploy it yourself, you’ll need a .env file with the following variables:

# Azure AI Foundry
PROJECT_ENDPOINT=   # Your Azure AI Foundry project endpoint
MODEL_DEPLOYMENT_NAME=   # The model deployment name used for your agents (e.g., gpt-4o-mini)

# Azure AI Search
AZURE_SEARCH_ENDPOINT=   # Endpoint of your Azure AI Search resource
AZURE_SEARCH_API_KEY=    # API key for your Azure AI Search instance
AZURE_SEARCH_INDEX_NAME= # Name of the index used for department RAG search

Also, you need to make sure you connect your Azure AI Search resource with your AI Foundry (see How to add a new connection in Azure AI Foundry portal - Azure AI Foundry | Microsoft Learn)

Final Thoughts

This was a fun Sunday experiment that gave me a hands-on introduction to Azure AI Foundry Agent Service (seriously, Microsoft, please give it a shorter and cooler name). With multi-agent coordination, Azure AI Search, and Discord integration via Azure Functions and an OpenAPI spec, I built a simple but practical onboarding automation flow that helped me understand what this framework is currently capable of.

Keep in mind that this framework is still new and actively evolving, so things may change quickly.

Here’s a demo of the app as well as quick walkthrough of the solution

Resources

• Github Repo

• What is Azure AI Foundry Agent Service?

CrewAI is a popular open-source framework that simplifies the creation of collaborative AI agent systems. Combined with Langfuse's specialized monitoring capabilities, we can gain deep insights into agent interactions, performance, cost, and behavior patterns.

Why Langfuse Over Traditional Monitoring Tools?

You might wonder why we need a specialized tool like Langfuse when established monitoring solutions like Azure Monitor or AWS CloudWatch already exist. Here's the key difference:

Traditional monitoring tools excel at tracking infrastructure metrics, application performance, and system health. However, they weren't designed for the unique challenges of AI agent systems. Langfuse fills this gap by providing:

• LLM-specific observability: Track token usage, model performance, and response quality across different language models

• Agent conversation flows: Visualize complex multi-agent interactions and decision chains

• Cost tracking: Monitor AI model costs in real-time across your entire agent ecosystem

• Prompt engineering insights: Analyze how different prompts affect agent behavior and outcomes

• Human feedback integration: Capture and analyze user feedback to improve agent performance

Langfuse Dashboard Overview

Here's a demo dashboard showing what Langfuse monitoring looks like in action:

As you can see, we have a comprehensive view of our multi-agent system's performance. The dashboard displays several key metrics:

• 38 total traces tracked across our agent interactions, giving us visibility into every conversation and task execution

• Model costs of $159,065 with detailed breakdowns by model type (gpt-4-0613 and gpt-4o-mini), helping us understand the financial impact of our agent operations

• Trace activity over time showing peak usage patterns and system load distribution

• Model usage analytics with cost and token consumption trends, essential for optimizing our agent configurations

The left sidebar shows different trace categories like "blog-post-agent," "Crew Created," "blog-post-title," and "Task Created," which correspond to different agents and processes in our CrewAI system. This granular tracking allows us to identify bottlenecks, optimize specific agent behaviors, and ensure our multi-agent workflow is performing efficiently.

Now let's dive into how to set up this monitoring for your own CrewAI agents.

Setting Up Langfuse with CrewAI

Let's walk through the implementation step by step. First, here are the required dependencies for our project:

• crewai

• langfuse

• openlit

• crewai-tools

Environment Configuration

Start by setting up your environment variables in a .env file:

• LANGFUSE_SECRET_KEY=your_langfuse_secret_key

• LANGFUSE_PUBLIC_KEY=your_langfuse_public_key

• LANGFUSE_HOST=http://localhost:3000

• OPENAI_API_KEY=your_openai_api_key

Implementation Code

Here's the complete implementation that demonstrates how to integrate Langfuse monitoring with CrewAI:

from crewai import LLM, Agent, Task, Crew
from langfuse import Langfuse, observe
from langfuse.openai import openai
import dotenv
import os

# Load environment variables
dotenv.load_dotenv()

# Initialize Langfuse client
langfuse = Langfuse(
    secret_key=os.getenv("LANGFUSE_SECRET_KEY"),
    public_key=os.getenv("LANGFUSE_PUBLIC_KEY"),
    host=os.getenv("LANGFUSE_HOST")
)

openai_api_key = os.getenv("OPENAI_API_KEY")
client = openai.OpenAI(api_key=openai_api_key)

@observe(name="blog-agent", as_type="generation")
def generate_blog_post_title():
    # Configure LLM for CrewAI
    llm = LLM(model="gpt-4o-mini", api_key=openai_api_key)

    # Create the agent
    blog_agent = Agent(
        role="Blog Post Agent",
        goal="Generate a blog post title about AI",
        backstory="You are a blog post agent that generates blog posts about AI",
        llm=llm,
        verbose=True
    )
    
    # Define the task
    title_task = Task(
        description="Generate a blog post title about AI",
        expected_output="A blog post title about AI",
        agent=blog_agent
    )

    # Create and execute the crew
    crew = Crew(agents=[blog_agent], tasks=[title_task])
    response = crew.kickoff()

    # Additional Langfuse span for specific tracking
    with langfuse.start_as_current_span(name="blog-post-title"):
        return response.raw

# Execute the function
print(generate_blog_post_title())

Key Integration Points

The magic happens in several places:

• @observe decorator: This automatically tracks the entire function execution, capturing inputs, outputs, and performance metrics

• Langfuse client initialization: Connects to your Langfuse instance (running locally on port 3000 in this example)

• CrewAI execution: The standard CrewAI workflow runs normally while Langfuse captures all the underlying LLM calls

• Additional spans: The start_as_current_span context manager allows you to add custom tracking points

When you run this code, Langfuse automatically captures every interaction between your agents, including token usage, response times, and the complete conversation flow that led to the final blog post title.

Configuring Model Pricing for Cost Tracking

One crucial step for accurate cost monitoring is configuring your models in the Langfuse platform. Without this configuration, Langfuse won't be able to calculate the actual costs of your agent interactions.

As you can see in the screenshot above, you need to add your specific models to Langfuse with their pricing information. For our example using gpt-4o-mini, the configuration includes the following dummy configuration:

• Input tokens: $5.0000000 per 1M units

• Output tokens: $5.0000000 per 1M units

• Input cached tokens: $5.0000000 per 1M units

• Output reasoning tokens: $5.0000000 per 1M units

To set this up for your own project:

1. Navigate to your Langfuse dashboard

2. Go to the Models section

3. Click "Add Model" or configure an existing one

4. Enter the correct pricing based on your model provider's current rates

Important: Make sure to use the actual pricing from your model provider. For gpt-4o-mini, you should verify the current OpenAI pricing rates, as they may differ from the example values shown, which are for illustrative purposes and are not real ($5.00 per 1M units). Always check OpenAI's official pricing page for the most up-to-date rates.

Once configured, Langfuse will automatically calculate costs for every agent interaction, giving you the detailed cost breakdowns we saw in the dashboard earlier.

Conclusion

I was researching open-source monitoring tools over the weekend and decided to give Langfuse a try. It seems like an established platform, well-liked by the community. I liked it too and maybe I will use it in some production project soon.

The combination of Langfuse and CrewAI provides excellent visibility into agent interactions, token usage, and costs—all essential for production multi-agent systems. As your systems grow, these observability features become invaluable for tracking performance and optimizing workflows.

This isn't an advertisement for either tool, just sharing what worked well for my own projects. There are other monitoring solutions out there that I will test and write about soon.

Ready to try it yourself? Set up your Langfuse instance, integrate it with your favorite agentic framework, and start monitoring your multi-agent systems today.

Useful Resources:

• Langfuse Documentation

• CrewAI Documentation

Written by human and AI 🤖👨‍💻

As much as I love AI—and I do use it, build systems with it, and follow the space closely—there’s one trend I keep seeing across platforms like X, Reddit, and LinkedIn that really worries me. It’s what people call vibe coding.

So, what is vibe coding?

Vibe coding is a new approach to software development that leverages large language models (LLMs) to generate code based on natural language prompts—essentially letting the AI handle the implementation while the developer focuses on describing what they want in plain language instead of code.

In other words, it’s not about writing code in the traditional sense anymore. It’s about typing prompts into an AI tool, copying whatever comes out, and hoping it works—without fully understanding what’s being built under the hood.

Platforms like Lovable, Bolt.new, and Replit make it extremely easy to spin up an app quickly with AI and zero coding. While that’s great for rapid prototyping or learning, it encourages a mindset where understanding is not needed — as long as the app runs. This new idea of building an application by just typing to some magic black box (AI) what you want, and you magically get 'something' is extremely dangerous.

I love the quote, “a picture is worth a thousand words,” and nothing illustrates the danger better than a quick search on GitHub. If you type something like OPENAI_API_KEY= into the search bar, you'll instantly find thousands of leaked API keys. Why?

Because many vibe coders—especially those who rely heavily on AI tools—either blindly copy-paste the output into their codebase or use tools that inject the code for them automatically, often including sensitive information like API keys, database URIs, and credentials. They deploy it and move on—without understanding the risks.

This is the dark side of vibe coding: no fundamentals, no awareness of security, no understanding of secret management—just code being deployed by people with no real understanding of coding or proper development practices.

These vibe coders aren't aware that secrets should be stored in environment variables and protected using secure services like Azure Key Vault, AWS Secrets Manager, or Vault. They don’t know about .gitignore or the consequences of exposing a key in a public repository.

Many of them started coding only after LLMs became widely available and skipped the foundational learning entirely. They rely solely on prompts, with little to no understanding of security, architecture, or even basic coding principles—which is extremely dangerous.

They’re just chasing a working demo with gradient backgrounds and emojis, not building a secure, reliable system.

I’m not against vibe coding—when it’s used for basic, boilerplate tasks you already understand but simply don’t want to spend hours doing. That’s totally fine.

But the idea of building entire systems or applications blindly, without understanding what’s actually happening under the hood, and expecting them to work long-term—that’s a recipe for disaster.

Vibe coding is cancerous

Vibe coding is harmless when confined to trivial boilerplate or an isolated sandbox.
The rot begins when entire features—or worse, full systems—reach production without anyone truly understanding the code.

If this starts spreading like cancer, the consequences will be severe. Entire teams will ship code they don’t understand, creating systems that are fragile, insecure, and impossible to maintain. Technical debt will explode. Debugging will become guesswork. Critical bugs and vulnerabilities will slip through because no one knows what the code is supposed to do in the first place.

Over time, we’ll have a generation of developers who can prompt but can’t code—who can build demos, but not systems.
And companies will be left with software that’s essentially a black box—one that breaks, exposes sensitive data, or collapses under real-world load with no one capable of fixing it.

The developer risks

First, the engineer who ships vibe-coded solutions often has no idea what’s inside the AI-generated black box. And when you don’t understand something, you can’t control it—just like mistaking an alligator for a puppy.

But the real danger is long-term: relying solely on vibe coding erodes your fundamentals—if you had any to begin with. You stop thinking in terms of design patterns, data structures, security, performance, and scalability. Over time, you become someone who can only prompt but not debug, only generate but not reason. You become completely dependent on these tools—and suddenly, you can't build anything on your own.

And when the AI fails—or the job market demands real engineering skills—what’s the need for you? You’re done.

The business risk

Unchecked vibe code in production can sink a company financially and reputationally unless a qualified engineer reviews every line. Imagine someone “prompt-engineering” a banking service and pressing Deploy. Here’s what can—and often does—go wrong:

• Hard-coded secrets leak to GitHub, letting attackers drain accounts in minutes.

• Missing input validation enables SQL injection or path-traversal attacks that expose customer data.

• Broken authorization logic lets one user see or transfer another user’s funds.

• Concurrency bugs (e.g., unsafely updating balances) cause double withdrawals or negative totals.

• Unbounded retries / infinite loops spike cloud bills and DOS your own service.

• Silent error-handling swallows exceptions, leaving corrupted data with no audit trail.

• Regulatory breaches—like logging raw cardholder data—trigger multi-million-euro GDPR fines.

• Untested edge cases crash mobile apps, torpedoing user trust and app-store ratings.

Let’s say your vibe-coded solution makes it to production. If you don’t understand how it works, then even when things start breaking, you might not realize that the feature is the root cause. It could take days—or worse, weeks—to connect the dots.

And here’s the nightmare scenario: how do you debug something you don’t even understand?
You’re staring at code that looks like magic, with no idea what’s normal and what’s broken.
Good luck fixing a production issue under pressure when you weren’t the one who actually written the code.

Keep vibe coding on a short leash; once it slips into critical paths, it mutates from a time-saver into an existential threat.

Who profits from selling this illusion?

This whole mindset has been fueled by the big tech companies, who are investing tens—and even hundreds—of billions into AI, while aggressively pushing the narrative that “everyone can be a developer now.” But that’s one of the biggest and costliest lies the tech world has ever seen.

They promote ideas like the “prompt engineer” or the “AI pair programmer” by building tools such as GitHub Copilot, Claude Code, and Cursor—platforms where you can let AI generate large chunks of code with little to no understanding of what it’s actually doing. For many, it feels like magic—a black box that just works.

But that same code might as well launch a nuclear missile, and they wouldn’t know the difference.
Of course, I’m exaggerating (I hope) to make a point—but the danger is real.

Let’s be real now

AI is here to stay. It’s a major breakthrough and absolutely boosts productivity—that's a fact. But what AI is not is a self-sufficient software engineer that can build and maintain entire systems on its own.

As much as companies pushing this narrative want us to believe otherwise—mostly to justify the billions they've poured into AI, boost their stock prices, and keep investors happy—the reality is very different. There’s no AI system you can just turn on and expect it to build the next Netflix or Amazon.

Yes, there are incredible tools that help you build and ship faster. That’s true. But that’s where it ends.

I especially love when companies claim that “30%,” “50%,” or even “60%” of their code is now written by AI. It sounds impressive—until you realize what it actually means. It doesn’t mean there’s some evil AI in the basement writing production-grade systems while engineers sip mojitos. It simply means that some portion of the code pushed to production contains AI-generated snippets—most of which are (hopefully) still reviewed, edited, and understood by real developers.

Judgement Day

My advice to you: never be that guy.
Thanks, AI, for painting this so beautifully on the first try.

Until next time—write code, learn code, not just prompts.

Written by human and AI ❤️🤖

As a solution architect, this experience got me thinking. Simplicity for the user isn’t magic. It’s the result of conscious, often painstaking decisions made by designers, architects, and engineers. The complexity doesn't disappear — it shifts. I call this Burden Shifting Design: the practice of moving the hard parts away from the user experience and into the product’s architecture, processes, and operations.

The Wrong Approach: Offloading Complexity to the User

Too often, systems are designed for the convenience of the company or development team rather than the user. The result? Clunky interfaces, fragmented workflows, and experiences that force users to handle the complexity that should have been absorbed by the product:

• “Please select from these 12 confusing options.”

• “You need to navigate through multiple forms to complete this simple task.”

• “Tell us which department to contact because we can’t figure it out for you.”

• “Enter these details again because our systems don’t talk to each other.”

• “We require you to upload the same document twice in different places.”

Technically, these products might work. But they fail the user because they place the burden in the wrong place. In time, products like these tend to lose the interest and loyalty of their users, or they get replaced by newer, smarter products that offer a better, simpler experience.

We’ve seen this happen again and again. BlackBerry and Nokia lost to the iPhone because Apple shifted the complexity inward, creating a seamless experience, while BlackBerry and Nokia clung to outdated, clunky interfaces.

Blockbuster was replaced by Netflix, which removed the friction of store visits, late fees, and availability issues, shifting the complexity to digital licensing, streaming infrastructure, and personalization.

Yahoo Search lost to Google, which delivered cleaner, faster, and more relevant results by shouldering the complexity of better algorithms and data handling behind the scenes.

The Right Approach: Burden Shifting Design

Now think about Uber. For me as a user, booking a ride was totally effortless. I just tapped a few buttons, and everything was taken care of. The app matched me with a driver in real time, calculated the price dynamically, processed my payment securely without me lifting a finger, and provided live tracking with accurate ETAs. It felt seamless — no friction, no confusion, no extra effort on my part.

And what impressed me even more was how smoothly things worked even when something didn’t go as planned. One time, I booked a ride, but the driver was taking too long to arrive. I decided to cancel — and even that was simple. With a single tap, I cancelled the ride, and the app handled the rest — no awkward calls, no hassle, no stress.

Behind the scenes, here’s what Uber was doing for me:

• Matching me with a driver in real time

• Calculating the price dynamically based on demand

• Processing my payment securely

• Tracking the driver live and giving me accurate ETAs

• Handling cancellations, refunds, and adjustments smoothly

• Ensuring compliance with local laws and regulations

• Doing all this seamlessly while managing billions of transactions like mine every day

The user enjoys simplicity because Uber takes on the complexity. This is the essence of Burden Shifting Design — moving the hard work from the user’s side to the product’s side.

Next time we start designing a system, let’s think about Uber and companies like it. Let’s ask ourselves: How can we take on the hard work, so our users don’t have to? That’s where great products begin.