<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Rodrigo de Oliveira</title>
    <description>The latest articles on DEV Community by Rodrigo de Oliveira (@rodri-oliveira-dev).</description>
    <link>https://dev.to/rodri-oliveira-dev</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4130418%2F5f4d2175-a0f9-4e03-a62e-b636a7fca764.jpeg</url>
      <title>DEV Community: Rodrigo de Oliveira</title>
      <link>https://dev.to/rodri-oliveira-dev</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/rodri-oliveira-dev"/>
    <language>en</language>
    <item>
      <title>Validation in DDD Applications: Protecting Domain Rules</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 18 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/validation-in-ddd-applications-protecting-domain-rules-5e47</link>
      <guid>https://dev.to/rodri-oliveira-dev/validation-in-ddd-applications-protecting-domain-rules-5e47</guid>
      <description>&lt;p&gt;&lt;em&gt;Learn how to distribute validation responsibilities, preserve invariants, and build consistent domain models without turning your application into a collection of scattered checks.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;This article is part of our ongoing series on Domain-Driven Design (DDD). In the previous article, &lt;a href="https://medium.com/@rodrigodotnet/aggregates-e-aggregate-roots-desenhando-fronteiras-de-consist%C3%AAncia-64a22cef822d" rel="noopener noreferrer"&gt;Aggregates and Aggregate Roots: Designing Consistency Boundaries&lt;/a&gt;, we discussed how aggregates help establish clear boundaries for maintaining data consistency.&lt;/p&gt;

&lt;p&gt;Now, let's explore a closely related question: &lt;strong&gt;How can we ensure that our data remains valid throughout an application's lifecycle?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;When we talk about validation, we often think about checking whether a field is required, whether a number is positive, or whether an email address follows an acceptable format.&lt;/p&gt;

&lt;p&gt;These checks are important, but they represent only part of the problem.&lt;/p&gt;

&lt;p&gt;In applications built around Domain-Driven Design, validation also means protecting the rules that define how the business operates. It means preventing an entity from entering an inconsistent state, even when an operation involves multiple services, integrations, or processes.&lt;/p&gt;

&lt;p&gt;And this brings us to an important distinction: &lt;strong&gt;Not every validation belongs in the domain, but every rule essential to domain consistency must be protected.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Let's explore what this means in practice.&lt;/p&gt;




&lt;h2&gt;
  
  
  Validating Data Is Not the Same as Validating the Domain
&lt;/h2&gt;

&lt;p&gt;Imagine an e-commerce application where customers can create orders, add products, and confirm purchases.&lt;/p&gt;

&lt;p&gt;When the application receives a request to add an item, we might check whether the product identifier was provided and whether the quantity is greater than zero.&lt;/p&gt;

&lt;p&gt;These are relatively simple validations, usually performed before executing the use case.&lt;/p&gt;

&lt;p&gt;Now consider a few other situations:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A confirmed order cannot accept additional items.&lt;/li&gt;
&lt;li&gt;An order cannot be confirmed without products.&lt;/li&gt;
&lt;li&gt;An order item cannot have a quantity of zero or less.&lt;/li&gt;
&lt;li&gt;A canceled order cannot transition directly back to the confirmed state.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Notice that we're no longer simply checking incoming data. We're protecting behaviors and states allowed by the business.&lt;/p&gt;

&lt;p&gt;An application can receive a technically valid request that still represents an invalid business operation.&lt;/p&gt;

&lt;p&gt;For example, adding five products to an order that has already been confirmed.&lt;/p&gt;

&lt;p&gt;The data is valid. The operation is not.&lt;/p&gt;

&lt;p&gt;This distinction helps explain why validation should not be concentrated exclusively in controllers, DTOs, or specialized validation libraries.&lt;/p&gt;

&lt;h2&gt;
  
  
  Invariants: The Rules That Must Remain True
&lt;/h2&gt;

&lt;p&gt;One of the most important concepts when discussing validation in DDD is the &lt;strong&gt;domain invariant&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;An invariant represents a condition that must remain true for an object or aggregate to be considered valid.&lt;/p&gt;

&lt;p&gt;In &lt;em&gt;Domain-Driven Design: Tackling Complexity in the Heart of Software&lt;/em&gt;, Eric Evans emphasizes the importance of preserving model integrity. Vaughn Vernon explores this further by connecting invariants to aggregate consistency boundaries.&lt;/p&gt;

&lt;p&gt;However, this doesn't mean every rule must be satisfied at every stage of a business process.&lt;/p&gt;

&lt;p&gt;Let's return to our order example.&lt;/p&gt;

&lt;p&gt;While an order is in draft status, it may contain no items at all. That's perfectly acceptable.&lt;/p&gt;

&lt;p&gt;However, before transitioning to the confirmed state, the order must contain at least one product.&lt;/p&gt;

&lt;p&gt;Therefore, the invariant isn't simply:&lt;/p&gt;

&lt;p&gt;"Every order must contain items."&lt;/p&gt;

&lt;p&gt;The correct business rule is:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"Every confirmed order must contain at least one item."&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;That small distinction significantly changes the implementation.&lt;/p&gt;

&lt;p&gt;The domain needs to represent legitimate business states and control transitions between them.&lt;/p&gt;

&lt;p&gt;A common mistake is treating an object as invalid simply because it hasn't reached its final state. In many business processes, intermediate states are perfectly valid.&lt;/p&gt;

&lt;p&gt;The challenge is identifying which conditions must remain true in each state.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where Should Each Validation Take Place?
&lt;/h2&gt;

&lt;p&gt;A recurring question is where validations should be implemented.&lt;/p&gt;

&lt;p&gt;In practice, no single layer should be responsible for every type of validation.&lt;/p&gt;

&lt;p&gt;A useful approach is to separate responsibilities across input validation, application orchestration, domain behavior, and persistence.&lt;/p&gt;

&lt;h3&gt;
  
  
  Input Validation
&lt;/h3&gt;

&lt;p&gt;The first concern is ensuring that incoming data meets the expected contract.&lt;/p&gt;

&lt;p&gt;We can use Data Annotations, FluentValidation, or similar mechanisms supported by our technology stack.&lt;/p&gt;

&lt;p&gt;In .NET, for example, we could represent a request like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;AddOrderItemCommand&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nc"&gt;Guid&lt;/span&gt; &lt;span class="nc"&gt;OrderId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nc"&gt;Guid&lt;/span&gt; &lt;span class="nc"&gt;ProductId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="nc"&gt;Quantity&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And create a validator:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AddOrderItemCommandValidator&lt;/span&gt;
    &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;AbstractValidator&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;AddOrderItemCommand&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;AddOrderItemCommandValidator&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;RuleFor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;OrderId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NotEmpty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="nc"&gt;RuleFor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;ProductId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NotEmpty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="nc"&gt;RuleFor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Quantity&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;GreaterThan&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This validator ensures that the request contains the necessary information and that the values meet the defined constraints.&lt;/p&gt;

&lt;p&gt;It can prevent obviously invalid requests from moving further into the application.&lt;/p&gt;

&lt;p&gt;But there's still a problem.&lt;/p&gt;

&lt;p&gt;Nothing in this code guarantees that the order is open for modifications.&lt;/p&gt;

&lt;p&gt;The validator doesn't even know the current state of the order.&lt;/p&gt;

&lt;p&gt;And that's perfectly fine. It doesn't have to.&lt;/p&gt;

&lt;p&gt;Input validation acts as the first line of defense, but it doesn't replace domain rules.&lt;/p&gt;

&lt;h3&gt;
  
  
  Validation in the Application Layer
&lt;/h3&gt;

&lt;p&gt;The application layer coordinates the execution of use cases.&lt;/p&gt;

&lt;p&gt;It may load aggregates, query services, check prerequisites, and orchestrate the necessary operations.&lt;/p&gt;

&lt;p&gt;Imagine that before adding a product, we need to verify whether the order exists.&lt;/p&gt;

&lt;p&gt;An Application Service or Command Handler can query the repository and report that the order was not found.&lt;/p&gt;

&lt;p&gt;It might also retrieve the current product price from an authoritative source rather than trusting a value supplied directly by the client.&lt;/p&gt;

&lt;p&gt;However, the application layer shouldn't be responsible for deciding whether a confirmed order can accept additional items.&lt;/p&gt;

&lt;p&gt;That decision belongs to the domain.&lt;/p&gt;

&lt;p&gt;One way to understand this separation is:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The application coordinates what needs to happen. The domain determines what is allowed to happen.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;This separation prevents essential business rules from becoming scattered across different handlers and services.&lt;/p&gt;

&lt;h3&gt;
  
  
  Validation in the Domain
&lt;/h3&gt;

&lt;p&gt;Now we reach the core of the discussion.&lt;/p&gt;

&lt;p&gt;Within the domain model, validations must protect invariants and control business operations.&lt;/p&gt;

&lt;p&gt;Let's represent an &lt;code&gt;Order&lt;/code&gt; aggregate in a simplified way:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderItem&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;_items&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;IReadOnlyCollection&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderItem&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;Items&lt;/span&gt;
        &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;_items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;AsReadOnly&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;OrderStatus&lt;/span&gt; &lt;span class="nc"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="n"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;OrderStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Draft&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nc"&gt;AddItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="nc"&gt;Guid&lt;/span&gt; &lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="kt"&gt;decimal&lt;/span&gt; &lt;span class="n"&gt;unitPrice&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Status&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="nc"&gt;OrderStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Draft&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;BusinessRuleException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                &lt;span class="s2"&gt;"The order does not allow new items."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="n"&gt;_items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;OrderItem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
            &lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;unitPrice&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nc"&gt;Confirm&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Status&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="nc"&gt;OrderStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Draft&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;BusinessRuleException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                &lt;span class="s2"&gt;"The order cannot be confirmed."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Count&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;BusinessRuleException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                &lt;span class="s2"&gt;"The order must contain items."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="nc"&gt;Status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;OrderStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Confirmed&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;em&gt;Illustrative example: &lt;code&gt;OrderItem&lt;/code&gt; must also protect its own values, such as requiring a positive quantity and a non-negative unit price.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Notice that we don't expose a public method for changing &lt;code&gt;Status&lt;/code&gt; directly.&lt;/p&gt;

&lt;p&gt;We also don't expose the internal collection for external modification.&lt;/p&gt;

&lt;p&gt;Instead, the aggregate's state changes through behaviors that represent business operations.&lt;/p&gt;

&lt;p&gt;This matters because allowing unrestricted property changes would enable any part of the application to put the order into an inconsistent state.&lt;/p&gt;

&lt;p&gt;The entity protects its own rules.&lt;/p&gt;

&lt;p&gt;And as we discussed in the previous article, the Aggregate Root serves as the entry point for operations that must preserve the consistency of the aggregate.&lt;/p&gt;

&lt;h2&gt;
  
  
  Value Objects Must Also Protect Their Validity
&lt;/h2&gt;

&lt;p&gt;Entities aren't the only components responsible for enforcing rules.&lt;/p&gt;

&lt;p&gt;Value Objects also play an important role.&lt;/p&gt;

&lt;p&gt;Imagine an object representing a product quantity.&lt;/p&gt;

&lt;p&gt;One possible implementation would be:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="k"&gt;struct&lt;/span&gt; &lt;span class="nc"&gt;Quantity&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="nc"&gt;Value&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;Quantity&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ArgumentOutOfRangeException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                &lt;span class="nf"&gt;nameof&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="s2"&gt;"Quantity must be positive."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="nc"&gt;Value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This approach communicates an important rule: an item quantity must be positive.&lt;/p&gt;

&lt;p&gt;However, C# has an interesting detail worth considering: a &lt;code&gt;struct&lt;/code&gt; can assume its default value without executing its custom constructor.&lt;/p&gt;

&lt;p&gt;As a result, &lt;code&gt;default(Quantity)&lt;/code&gt; could still produce a quantity of zero.&lt;/p&gt;

&lt;p&gt;If an absolute validity guarantee is important, we might choose an immutable reference type, carefully control object creation, or explicitly handle default values.&lt;/p&gt;

&lt;p&gt;This detail illustrates something I consider essential: &lt;strong&gt;Adding validation to a constructor doesn't automatically mean every possible object creation path is protected.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;We need to understand the language and the mechanisms involved in materialization, serialization, and persistence.&lt;/p&gt;

&lt;p&gt;The purpose of a Value Object is to provide a meaningful and reliable representation of a domain concept.&lt;/p&gt;

&lt;p&gt;When properly modeled, it reduces the need to repeat the same validations throughout the system.&lt;/p&gt;

&lt;h2&gt;
  
  
  Exceptions, Result, and Notification: How Should We Communicate Failures?
&lt;/h2&gt;

&lt;p&gt;So far, we've used exceptions to prevent invalid operations.&lt;/p&gt;

&lt;p&gt;That works, but should we use exceptions for every validation failure?&lt;/p&gt;

&lt;p&gt;Not necessarily.&lt;/p&gt;

&lt;p&gt;There's an important difference between encountering a truly exceptional condition and handling an expected business rejection.&lt;/p&gt;

&lt;p&gt;Consider confirming an empty order.&lt;/p&gt;

&lt;p&gt;Depending on the context, this may be a common and predictable situation. It might be better to communicate the outcome without relying on exception-based control flow.&lt;/p&gt;

&lt;p&gt;One alternative is the Result pattern.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;Result&lt;/span&gt; &lt;span class="nc"&gt;Confirm&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Status&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="nc"&gt;OrderStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Draft&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Failure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
            &lt;span class="s2"&gt;"order.invalid_state"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="s2"&gt;"The order cannot be confirmed."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Count&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Failure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
            &lt;span class="s2"&gt;"order.no_items"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="s2"&gt;"Add at least one item before confirming."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nc"&gt;Status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;OrderStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Confirmed&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Success&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;em&gt;This example replaces the previous &lt;code&gt;Confirm&lt;/code&gt; implementation. &lt;code&gt;Result&lt;/code&gt; represents a custom application or domain type, not a built-in C# feature.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Now the operation explicitly communicates success or failure.&lt;/p&gt;

&lt;p&gt;The code executing the use case can interpret that outcome and decide how to present it to the consumer.&lt;/p&gt;

&lt;p&gt;Martin Fowler also describes the &lt;strong&gt;Notification pattern&lt;/strong&gt; as an alternative when we want to collect multiple validation problems.&lt;/p&gt;

&lt;p&gt;Instead of stopping at the first issue, we can accumulate relevant errors and report them together.&lt;/p&gt;

&lt;p&gt;This is particularly useful for forms, complex commands, and processes where the consumer benefits from seeing all validation issues at once.&lt;/p&gt;

&lt;p&gt;But there's an important consideration.&lt;/p&gt;

&lt;p&gt;Collecting errors doesn't mean allowing an invalid entity to be modified or persisted.&lt;/p&gt;

&lt;p&gt;We can identify multiple failures before performing a state transition. If any essential rule isn't satisfied, the operation should be rejected without leaving partial changes behind.&lt;/p&gt;

&lt;p&gt;My preference is to choose the approach based on the nature of the failure:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Result:&lt;/strong&gt; When rejection is an expected outcome of an operation.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Notification:&lt;/strong&gt; When collecting multiple validation problems is useful.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Exceptions:&lt;/strong&gt; When something exceptional occurs, an unexpected contract violation is detected, or the design explicitly chooses exceptions to enforce invariants.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There's no reason to turn this decision into a competition between patterns.&lt;/p&gt;

&lt;p&gt;What matters is maintaining a consistent strategy that fits the domain.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Happens When a Rule Depends on External Information?
&lt;/h2&gt;

&lt;p&gt;So far, we've discussed rules that can be evaluated using information available within the aggregate.&lt;/p&gt;

&lt;p&gt;But that's not always enough.&lt;/p&gt;

&lt;p&gt;Imagine an application where every customer must have a unique registration identifier.&lt;/p&gt;

&lt;p&gt;To verify whether an identifier already exists, we may need to query a database.&lt;/p&gt;

&lt;p&gt;Would injecting a repository directly into the &lt;code&gt;Customer&lt;/code&gt; entity be a good idea?&lt;/p&gt;

&lt;p&gt;In most cases, I would avoid it.&lt;/p&gt;

&lt;p&gt;Entities and Value Objects should concentrate domain behaviors and concepts without becoming unnecessarily coupled to infrastructure.&lt;/p&gt;

&lt;p&gt;When a rule depends on external information, we can use the application layer to coordinate queries or introduce a Domain Service when the decision represents business logic that doesn't naturally belong to a specific entity.&lt;/p&gt;

&lt;p&gt;We can also represent more complex business policies through the Specification pattern, especially when we need to encapsulate and reuse decision criteria.&lt;/p&gt;

&lt;p&gt;However, there's another problem we need to consider: &lt;strong&gt;concurrency&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Imagine two simultaneous requests attempting to register the same identifier.&lt;/p&gt;

&lt;p&gt;Both query the database.&lt;/p&gt;

&lt;p&gt;Both discover that the identifier doesn't exist yet.&lt;/p&gt;

&lt;p&gt;Both attempt to save their changes.&lt;/p&gt;

&lt;p&gt;The earlier validation doesn't guarantee uniqueness.&lt;/p&gt;

&lt;p&gt;That's why, when consistency depends on persistence, additional mechanisms such as unique indexes, transactions, and concurrency control are important.&lt;/p&gt;

&lt;p&gt;Validation in the domain or application layer helps express the rule and anticipate a rejection. The database constraint protects data integrity when concurrent operations occur.&lt;/p&gt;

&lt;p&gt;These responsibilities complement one another.&lt;/p&gt;

&lt;h2&gt;
  
  
  Validation Across Aggregates: Respecting Consistency Boundaries
&lt;/h2&gt;

&lt;p&gt;In the previous article, we discussed how aggregates represent consistency boundaries.&lt;/p&gt;

&lt;p&gt;This concept also directly influences validation.&lt;/p&gt;

&lt;p&gt;Within an aggregate, invariants requiring immediate consistency must be preserved during its operations.&lt;/p&gt;

&lt;p&gt;However, when a rule involves multiple aggregates, we need to evaluate whether an atomic update is genuinely necessary.&lt;/p&gt;

&lt;p&gt;In some scenarios, eventual consistency is sufficient.&lt;/p&gt;

&lt;p&gt;Imagine that confirming an order must initiate an inventory allocation process.&lt;/p&gt;

&lt;p&gt;We might confirm the order and publish a domain event that triggers an operation in another aggregate.&lt;/p&gt;

&lt;p&gt;But there's an important difference between a consequence of confirmation and a mandatory prerequisite.&lt;/p&gt;

&lt;p&gt;If the business requires inventory reservation to be guaranteed before an order is confirmed, simply publishing an event and waiting for later processing does not satisfy that rule.&lt;/p&gt;

&lt;p&gt;In that situation, the model must correctly represent the reservation, its states, and the coordination required.&lt;/p&gt;

&lt;p&gt;Vaughn Vernon emphasizes this relationship between invariants and consistency boundaries in his work on aggregate design.&lt;/p&gt;

&lt;p&gt;The point is that we shouldn't automatically introduce distributed transactions or enlarge aggregates simply because a rule involves multiple business concepts.&lt;/p&gt;

&lt;p&gt;First, we need to understand which consistency guarantees the business actually requires.&lt;/p&gt;

&lt;p&gt;Then we can choose the appropriate mechanism.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Risk of Validating Everything in One Place
&lt;/h2&gt;

&lt;p&gt;There's a common temptation in .NET projects: centralizing nearly every rule in classes implementing &lt;code&gt;AbstractValidator&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The idea is appealing.&lt;/p&gt;

&lt;p&gt;We have a specialized library, readable syntax, and a standardized mechanism for reporting errors.&lt;/p&gt;

&lt;p&gt;The problem begins when essential business rules exist exclusively in those validators.&lt;/p&gt;

&lt;p&gt;Imagine a validator that checks whether an order is open, whether sufficient balance is available, whether a customer may perform an operation, and whether a particular state transition is allowed.&lt;/p&gt;

&lt;p&gt;If those rules exist only in that layer, other execution paths may bypass them.&lt;/p&gt;

&lt;p&gt;Applications don't receive commands exclusively through HTTP APIs.&lt;/p&gt;

&lt;p&gt;They may also be triggered by message consumers, scheduled jobs, integrations, and internal processes.&lt;/p&gt;

&lt;p&gt;When the aggregate itself protects the rule, all those execution paths must respect it.&lt;/p&gt;

&lt;p&gt;This doesn't prevent us from using FluentValidation to improve input handling or perform early checks.&lt;/p&gt;

&lt;p&gt;It simply means the library shouldn't become the sole guardian of the domain model.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;External validators help reject invalid requests. The domain must prevent invalid states.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  How Should We Test Validations?
&lt;/h2&gt;

&lt;p&gt;One advantage of keeping invariants inside the domain is that we can test them without depending on an API or a database.&lt;/p&gt;

&lt;p&gt;We can write unit tests that directly exercise aggregate behaviors.&lt;/p&gt;

&lt;p&gt;For our &lt;code&gt;Order&lt;/code&gt; example, important scenarios include verifying that an empty order cannot be confirmed, that a draft order accepts valid items, and that a confirmed order rejects further modifications.&lt;/p&gt;

&lt;p&gt;We also need to test successful paths.&lt;/p&gt;

&lt;p&gt;An operation that should be allowed must not be incorrectly blocked by an overly restrictive rule.&lt;/p&gt;

&lt;p&gt;These tests represent actual business expectations.&lt;/p&gt;

&lt;p&gt;Application-level tests can verify how outcomes are handled, how dependencies are coordinated, and how external information influences decisions.&lt;/p&gt;

&lt;p&gt;Finally, integration tests are important for validating database constraints, transactional behavior, and concurrency conflict handling.&lt;/p&gt;

&lt;p&gt;A uniqueness rule, for example, isn't completely tested just because a repository query returned the expected result.&lt;/p&gt;

&lt;p&gt;We also need to ensure persistence rejects incompatible writes.&lt;/p&gt;

&lt;p&gt;Ideally, our tests should answer not only whether a condition was checked, but whether the application can actually prevent a business rule from being violated.&lt;/p&gt;

&lt;h2&gt;
  
  
  References and Further Reading
&lt;/h2&gt;

&lt;p&gt;For those interested in exploring these concepts further, I recommend the following resources:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software.&lt;/strong&gt; The foundational book for understanding entities, Value Objects, aggregates, and model integrity.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Vaughn Vernon, Implementing Domain-Driven Design.&lt;/strong&gt; A deeper exploration of tactical modeling, including validation, invariants, and aggregate consistency.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Vaughn Vernon, Domain-Driven Design Distilled.&lt;/strong&gt; A more concise introduction to the essential concepts and responsibilities within the domain model.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Vaughn Vernon, &lt;a href="https://kalele.io/effective-aggregate-design/" rel="noopener noreferrer"&gt;Effective Aggregate Design&lt;/a&gt;.&lt;/strong&gt; A series of articles explaining how to identify invariants and establish appropriate consistency boundaries.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://docs.fluentvalidation.net/en/latest/" rel="noopener noreferrer"&gt;FluentValidation Official Documentation&lt;/a&gt;.&lt;/strong&gt; A useful resource for implementing strongly typed input validation in .NET applications while understanding its capabilities and limitations.&lt;/p&gt;

</description>
      <category>architecture</category>
      <category>backend</category>
      <category>softwaredevelopment</category>
      <category>softwareengineering</category>
    </item>
    <item>
      <title>MCP Beyond the Basics: Connecting Tools Is Easy. Designing Trust Is Hard.</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 18 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/mcp-beyond-the-basics-connecting-tools-is-easy-designing-trust-is-hard-37n5</link>
      <guid>https://dev.to/rodri-oliveira-dev/mcp-beyond-the-basics-connecting-tools-is-easy-designing-trust-is-hard-37n5</guid>
      <description>&lt;p&gt;The Model Context Protocol (MCP) has become an important topic in conversations about AI and software development.&lt;/p&gt;

&lt;p&gt;And it's easy to see why.&lt;/p&gt;

&lt;p&gt;The idea of connecting language models to external tools, systems, and data sources through a standardized protocol addresses a problem that previously required custom integrations for almost every application.&lt;/p&gt;

&lt;p&gt;The first results can be impressive.&lt;/p&gt;

&lt;p&gt;With relatively little code, we can build an MCP server, expose a few tools, and allow an AI agent to query a database, read files, or interact with an API.&lt;/p&gt;

&lt;p&gt;It feels almost too easy.&lt;/p&gt;

&lt;p&gt;But there's a significant difference between making an integration work and designing one that is ready for production.&lt;/p&gt;

&lt;p&gt;Once we move beyond local development environments and start dealing with sensitive information, multiple users, permissions, concurrent requests, and availability requirements, the questions become much more interesting.&lt;/p&gt;

&lt;p&gt;Who actually authorizes an operation?&lt;/p&gt;

&lt;p&gt;What prevents an agent from executing something outside its intended scope?&lt;/p&gt;

&lt;p&gt;What happens when a tool fails halfway through a process?&lt;/p&gt;

&lt;p&gt;And if an agent makes the wrong decision, how do we investigate what happened?&lt;/p&gt;

&lt;p&gt;These are not entirely new problems. In fact, they're quite familiar to anyone who has spent time designing distributed systems.&lt;/p&gt;

&lt;p&gt;What's new is the context in which we need to solve them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;MCP simplifies connectivity. It doesn't eliminate architectural responsibility.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;And that's where I believe the most interesting discussions should begin.&lt;/p&gt;

&lt;h2&gt;
  
  
  Understanding MCP's Role in Software Architecture
&lt;/h2&gt;

&lt;p&gt;Before discussing security or scalability, we need to clarify something important.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;MCP is not an AI agent.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;It's a protocol that standardizes communication between applications using language models and services exposing data or capabilities.&lt;/p&gt;

&lt;p&gt;Its architecture revolves around three main components.&lt;/p&gt;

&lt;p&gt;The &lt;em&gt;host&lt;/em&gt; is the application providing the AI-powered experience. Within that application, &lt;em&gt;clients&lt;/em&gt; communicate with MCP servers. The &lt;em&gt;servers&lt;/em&gt;, in turn, expose capabilities that applications can use.&lt;/p&gt;

&lt;p&gt;These capabilities are primarily organized into tools, resources, and prompts.&lt;/p&gt;

&lt;p&gt;Tools make it possible to execute operations, such as retrieving an order or analyzing a document. Resources expose contextual information. Prompts provide reusable templates for specific interactions.&lt;/p&gt;

&lt;p&gt;So far, nothing particularly complicated.&lt;/p&gt;

&lt;p&gt;But there's a detail worth paying attention to.&lt;/p&gt;

&lt;p&gt;In AI-powered applications, the decision to invoke a particular tool may come from a language model interpreting a user's request and the context available to it.&lt;/p&gt;

&lt;p&gt;That changes how we think about integrations.&lt;/p&gt;

&lt;p&gt;In traditional software, execution paths are generally defined through explicit application logic.&lt;/p&gt;

&lt;p&gt;With AI agents, part of the decision-making process may be probabilistic, influenced by prompts, external content, and previous interactions.&lt;/p&gt;

&lt;p&gt;The protocol standardizes how tools are discovered and invoked.&lt;/p&gt;

&lt;p&gt;It doesn't guarantee that the model will choose the correct tool, understand the user's intention perfectly, or make an appropriate decision.&lt;/p&gt;

&lt;p&gt;Those concerns belong to the architecture surrounding the protocol.&lt;/p&gt;

&lt;h2&gt;
  
  
  MCP Doesn't Replace APIs. And That's a Good Thing.
&lt;/h2&gt;

&lt;p&gt;One question I frequently see in discussions about MCP is whether it represents the next evolution of REST APIs.&lt;/p&gt;

&lt;p&gt;I think that's the wrong comparison.&lt;/p&gt;

&lt;p&gt;Traditional APIs expose contracts for communication between systems. MCP provides a standardized mechanism for exposing capabilities and context to AI applications.&lt;/p&gt;

&lt;p&gt;They serve different purposes, even when they work together.&lt;/p&gt;

&lt;p&gt;Imagine a financial platform that already provides an API for retrieving information about a customer agreement.&lt;/p&gt;

&lt;p&gt;We could expose that functionality through an MCP tool called &lt;code&gt;get_agreement_status&lt;/code&gt;, allowing an AI agent to retrieve the information during a conversation.&lt;/p&gt;

&lt;p&gt;Does that mean we should move the business logic into the MCP server?&lt;/p&gt;

&lt;p&gt;Not at all.&lt;/p&gt;

&lt;p&gt;A reasonable architectural choice would be to preserve business rules, domain validations, and existing integrations within the services that already own those responsibilities.&lt;/p&gt;

&lt;p&gt;The MCP server becomes an adapter exposing selected capabilities to AI applications.&lt;/p&gt;

&lt;p&gt;This avoids duplicating business logic and reduces the risk of inconsistent behavior across different interfaces.&lt;/p&gt;

&lt;p&gt;It also preserves existing investments in authentication, authorization, observability, and API contracts.&lt;/p&gt;

&lt;p&gt;A useful way to visualize the relationship is:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AI Application → MCP Server → Application API → Domain Services&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;This isn't the only possible architecture, of course. Some tools may execute operations directly, and additional components may be required depending on the environment.&lt;/p&gt;

&lt;p&gt;The important part is maintaining clear responsibilities.&lt;/p&gt;

&lt;p&gt;Introducing AI into an existing system shouldn't become an excuse to abandon established engineering practices.&lt;/p&gt;

&lt;h2&gt;
  
  
  A Tool's Contract Matters More Than You Think
&lt;/h2&gt;

&lt;p&gt;When designing an API, we usually spend time defining its contract.&lt;/p&gt;

&lt;p&gt;We consider operations, parameters, response formats, error handling, and validation rules.&lt;/p&gt;

&lt;p&gt;MCP tools deserve the same attention.&lt;/p&gt;

&lt;p&gt;But there's an additional complication: a tool's name and description also influence how a language model decides to use it.&lt;/p&gt;

&lt;p&gt;Consider a tool named &lt;code&gt;execute_operation&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;What exactly does it do?&lt;/p&gt;

&lt;p&gt;Now compare it with &lt;code&gt;get_customer_agreement_status&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The second name communicates a much clearer intention.&lt;/p&gt;

&lt;p&gt;This distinction isn't merely cosmetic.&lt;/p&gt;

&lt;p&gt;Ambiguous descriptions can make tool selection less reliable, particularly when an application exposes multiple tools with overlapping responsibilities.&lt;/p&gt;

&lt;p&gt;We should also think carefully about the level of control each tool provides.&lt;/p&gt;

&lt;p&gt;Exposing a tool capable of executing arbitrary SQL queries might seem convenient during development.&lt;/p&gt;

&lt;p&gt;In a production environment, however, that flexibility creates a much larger attack surface.&lt;/p&gt;

&lt;p&gt;In many cases, exposing specific operations with constrained parameters and explicit authorization rules is a better choice.&lt;/p&gt;

&lt;p&gt;Responses deserve similar attention.&lt;/p&gt;

&lt;p&gt;Returning an entire database record when the agent only needs a status field increases data exposure, context consumption, and unnecessary processing.&lt;/p&gt;

&lt;p&gt;Good tool design should favor clear responsibilities, validated inputs, predictable outputs, and well-defined boundaries.&lt;/p&gt;

&lt;p&gt;MCP supports structured schemas, including JSON Schema, which helps define these contracts.&lt;/p&gt;

&lt;p&gt;But schema validation is only one part of the solution.&lt;/p&gt;

&lt;p&gt;A structurally valid request can still represent an unauthorized or logically invalid operation.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Valid JSON doesn't automatically mean valid business behavior.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;That's a distinction worth remembering when building tools for increasingly autonomous systems.&lt;/p&gt;

&lt;h2&gt;
  
  
  Security: Just Because an Agent Can Doesn't Mean It Should
&lt;/h2&gt;

&lt;p&gt;This is probably one of the most important topics when discussing MCP in enterprise environments.&lt;/p&gt;

&lt;p&gt;Imagine an agent connected to two tools.&lt;/p&gt;

&lt;p&gt;One retrieves customer information. The other updates customer records.&lt;/p&gt;

&lt;p&gt;A user asks the agent to retrieve some information.&lt;/p&gt;

&lt;p&gt;During the interaction, however, the agent processes content from an external document containing instructions to modify a customer record.&lt;/p&gt;

&lt;p&gt;If the application doesn't enforce appropriate boundaries, the agent might attempt an operation the user never intended to authorize.&lt;/p&gt;

&lt;p&gt;This is a simplified example of how prompt injection can influence tool usage.&lt;/p&gt;

&lt;p&gt;The fundamental issue is treating untrusted content as if it were a legitimate instruction.&lt;/p&gt;

&lt;p&gt;A model may interpret instructions found in documents, web pages, or tool responses. That doesn't mean those instructions should have authority over application behavior.&lt;/p&gt;

&lt;p&gt;We need to establish clear trust boundaries.&lt;/p&gt;

&lt;p&gt;External content should be treated as potentially untrusted data. Authorization decisions must be enforced by reliable application components, not delegated exclusively to a language model.&lt;/p&gt;

&lt;p&gt;The official MCP security documentation also discusses risks such as confused deputy attacks, improper token handling, and authorization vulnerabilities.&lt;/p&gt;

&lt;p&gt;OAuth-based authorization is an important part of securing protected remote MCP servers, but authentication alone doesn't solve the entire problem.&lt;/p&gt;

&lt;p&gt;Knowing who is making a request is different from determining what that identity is allowed to do.&lt;/p&gt;

&lt;p&gt;Authorization should consider the operation being requested, the user's permissions, the target resource, and the privileges granted to the client.&lt;/p&gt;

&lt;p&gt;Token handling requires particular care.&lt;/p&gt;

&lt;p&gt;An MCP server should not blindly forward access tokens to downstream APIs. Each service should validate credentials intended for it, preserving the trust boundaries between components.&lt;/p&gt;

&lt;p&gt;And when an operation has significant consequences, such as deleting information, changing account details, or initiating a financial transaction, explicit confirmation may be necessary.&lt;/p&gt;

&lt;p&gt;That confirmation should happen through a trusted application mechanism.&lt;/p&gt;

&lt;p&gt;An agent can recommend or request an action.&lt;/p&gt;

&lt;p&gt;It shouldn't automatically receive the authority to execute it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AI autonomy should operate within architectural boundaries, not replace them.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Moving From Local Development to Production
&lt;/h2&gt;

&lt;p&gt;Many introductory MCP examples use the stdio transport, where clients and servers communicate through a local process's standard input and output streams.&lt;/p&gt;

&lt;p&gt;It's a practical choice for development tools and local integrations.&lt;/p&gt;

&lt;p&gt;But things become more interesting when MCP servers need to support multiple users over a network.&lt;/p&gt;

&lt;p&gt;Now we need to consider scalability, load balancing, availability, latency, and resource management.&lt;/p&gt;

&lt;p&gt;Streamable HTTP provides a transport mechanism for remote communication.&lt;/p&gt;

&lt;p&gt;The MCP &lt;code&gt;2026-07-28&lt;/code&gt; specification introduced an important architectural change: the protocol core became stateless, with self-contained requests rather than protocol sessions maintained across calls.&lt;/p&gt;

&lt;p&gt;This makes it easier to distribute requests across server instances using conventional HTTP infrastructure.&lt;/p&gt;

&lt;p&gt;However, there's an important distinction here.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A stateless protocol doesn't mean the application itself must be stateless.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Imagine a tool that starts analyzing a large collection of documents.&lt;/p&gt;

&lt;p&gt;The analysis might take several minutes.&lt;/p&gt;

&lt;p&gt;We still need a way to identify the execution, retrieve its progress, handle cancellation, and eventually access the results.&lt;/p&gt;

&lt;p&gt;Application-level state may still be necessary.&lt;/p&gt;

&lt;p&gt;Instead of relying on protocol sessions, we can explicitly represent this state through execution identifiers and appropriate persistence mechanisms.&lt;/p&gt;

&lt;p&gt;The MCP Tasks extension also provides capabilities for managing long-running operations, although implementations need to support the extension explicitly.&lt;/p&gt;

&lt;p&gt;Another concern is compatibility.&lt;/p&gt;

&lt;p&gt;Clients and servers won't necessarily adopt new protocol revisions simultaneously.&lt;/p&gt;

&lt;p&gt;A production architecture must account for the versions and capabilities actually supported by its components.&lt;/p&gt;

&lt;p&gt;And none of these protocol improvements eliminate the traditional challenges of distributed systems.&lt;/p&gt;

&lt;p&gt;Requests can time out.&lt;/p&gt;

&lt;p&gt;Network connections can fail.&lt;/p&gt;

&lt;p&gt;Clients may retry operations.&lt;/p&gt;

&lt;p&gt;If a tool performs an action with side effects, we still need to think about idempotency, retries, and protection against duplicate execution.&lt;/p&gt;

&lt;p&gt;These concerns existed long before MCP.&lt;/p&gt;

&lt;p&gt;They're simply becoming relevant to another category of applications.&lt;/p&gt;

&lt;h2&gt;
  
  
  Observability: Understanding What Actually Happened
&lt;/h2&gt;

&lt;p&gt;Let's consider a practical scenario.&lt;/p&gt;

&lt;p&gt;A developer asks an AI agent to evaluate the architectural impact of a proposed change.&lt;/p&gt;

&lt;p&gt;The agent retrieves architecture decision records, queries service dependencies, examines repository information, and invokes an analysis tool.&lt;/p&gt;

&lt;p&gt;Eventually, it produces an incorrect recommendation.&lt;/p&gt;

&lt;p&gt;Where do we start investigating?&lt;/p&gt;

&lt;p&gt;Without proper observability, we might not even know which tools were invoked.&lt;/p&gt;

&lt;p&gt;In traditional distributed systems, we rely on logs, metrics, and distributed tracing to understand application behavior.&lt;/p&gt;

&lt;p&gt;With AI agents, that foundation remains essential.&lt;/p&gt;

&lt;p&gt;But technical execution isn't the whole picture.&lt;/p&gt;

&lt;p&gt;A tool can execute successfully and still have been selected for the wrong reason.&lt;/p&gt;

&lt;p&gt;An HTTP response returning &lt;code&gt;200 OK&lt;/code&gt; tells us that the request succeeded at the protocol level.&lt;/p&gt;

&lt;p&gt;It doesn't tell us whether the model should have made that request in the first place.&lt;/p&gt;

&lt;p&gt;That's why observing agent-based systems requires looking at both technical execution and application behavior.&lt;/p&gt;

&lt;p&gt;We should be able to correlate requests across the AI application, MCP client, MCP server, and downstream services.&lt;/p&gt;

&lt;p&gt;OpenTelemetry can help establish that correlation.&lt;/p&gt;

&lt;p&gt;The 2026 MCP specification also documents W3C Trace Context propagation, making distributed tracing more consistent across participating components.&lt;/p&gt;

&lt;p&gt;Useful indicators might include tool invocation frequency, execution latency, error rates, authorization failures, retries, and resource consumption.&lt;/p&gt;

&lt;p&gt;Cost is another important consideration.&lt;/p&gt;

&lt;p&gt;A seemingly simple user interaction may trigger several tool calls, additional model executions, and repeated retrieval operations.&lt;/p&gt;

&lt;p&gt;Individually, these requests might appear inexpensive.&lt;/p&gt;

&lt;p&gt;At scale, they can become significant.&lt;/p&gt;

&lt;p&gt;Of course, observability introduces its own security considerations.&lt;/p&gt;

&lt;p&gt;Logging complete prompts, responses, access tokens, or sensitive business data without appropriate controls can create new vulnerabilities.&lt;/p&gt;

&lt;p&gt;The objective isn't to record everything.&lt;/p&gt;

&lt;p&gt;It's to collect enough reliable information to diagnose failures, investigate behavior, and support auditing without exposing unnecessary data.&lt;/p&gt;

&lt;h2&gt;
  
  
  Governance: Who Controls What AI Agents Can Access?
&lt;/h2&gt;

&lt;p&gt;As organizations adopt MCP, another challenge starts to emerge.&lt;/p&gt;

&lt;p&gt;Who decides which tools should be available?&lt;/p&gt;

&lt;p&gt;Who reviews a new integration?&lt;/p&gt;

&lt;p&gt;What happens when a tool's behavior changes?&lt;/p&gt;

&lt;p&gt;And how do we prevent an organization from accumulating dozens of poorly documented MCP servers with overlapping responsibilities?&lt;/p&gt;

&lt;p&gt;These are governance questions.&lt;/p&gt;

&lt;p&gt;A practical approach might include an approved catalog of MCP servers and tools, with defined ownership, access policies, versioning practices, and security requirements.&lt;/p&gt;

&lt;p&gt;Continuous integration pipelines can help validate schemas, test contracts, identify vulnerable dependencies, and detect potentially breaking changes.&lt;/p&gt;

&lt;p&gt;In larger environments, gateways or intermediary services may centralize concerns such as routing, authentication, rate limiting, and telemetry.&lt;/p&gt;

&lt;p&gt;But centralized infrastructure shouldn't become a substitute for authorization within the services that own business operations.&lt;/p&gt;

&lt;p&gt;There's also a connection worth exploring between MCP and architectural decision-making.&lt;/p&gt;

&lt;p&gt;Imagine an organization has an Architecture Decision Record stating that certain categories of customer data must never be sent to external AI providers.&lt;/p&gt;

&lt;p&gt;That decision shouldn't exist only as documentation.&lt;/p&gt;

&lt;p&gt;Whenever possible, it should influence the implementation through enforceable policies, approved tools, data filtering, and automated validation.&lt;/p&gt;

&lt;p&gt;This is where architecture governance becomes operational.&lt;/p&gt;

&lt;p&gt;Instead of relying exclusively on developers remembering every documented decision, we create mechanisms that help keep the system aligned with its intended architecture.&lt;/p&gt;

&lt;p&gt;The goal isn't to make governance more bureaucratic.&lt;/p&gt;

&lt;p&gt;It's to make important architectural constraints easier to understand, verify, and maintain.&lt;/p&gt;

&lt;h2&gt;
  
  
  A Practical Example: Architectural Impact Analysis
&lt;/h2&gt;

&lt;p&gt;Let's bring several of these ideas together.&lt;/p&gt;

&lt;p&gt;Imagine a development team maintaining Architecture Decision Records (ADRs), architecture diagrams, and service dependency information.&lt;/p&gt;

&lt;p&gt;The team wants an AI agent to help evaluate the potential impact of proposed architectural changes.&lt;/p&gt;

&lt;p&gt;An initial implementation could expose a single MCP tool that receives a change description and returns an analysis.&lt;/p&gt;

&lt;p&gt;That might work as a proof of concept.&lt;/p&gt;

&lt;p&gt;But we can design something more reliable.&lt;/p&gt;

&lt;p&gt;We could separate responsibilities into tools that retrieve relevant ADRs, identify dependencies, and perform a structured impact assessment.&lt;/p&gt;

&lt;p&gt;The agent would use those capabilities to gather evidence and construct a recommendation.&lt;/p&gt;

&lt;p&gt;The final result could identify affected components, relevant architectural decisions, potential risks, and areas requiring human validation.&lt;/p&gt;

&lt;p&gt;Notice what we're not doing.&lt;/p&gt;

&lt;p&gt;We're not giving the agent unrestricted authority to modify architectural decisions.&lt;/p&gt;

&lt;p&gt;We're allowing it to support the analysis process.&lt;/p&gt;

&lt;p&gt;If we later decide to support the creation of new ADR proposals, we could introduce a separate tool with its own authorization requirements and audit trail.&lt;/p&gt;

&lt;p&gt;Approving an architectural decision could remain part of the organization's established governance process.&lt;/p&gt;

&lt;p&gt;This separation matters because different operations carry different levels of risk.&lt;/p&gt;

&lt;p&gt;Reading an ADR is not equivalent to modifying one.&lt;/p&gt;

&lt;p&gt;Generating a recommendation is not equivalent to approving it.&lt;/p&gt;

&lt;p&gt;And identifying architectural drift is not the same as automatically changing production code to resolve it.&lt;/p&gt;

&lt;p&gt;A well-designed MCP integration makes those distinctions explicit.&lt;/p&gt;

&lt;p&gt;We don't have to choose between AI autonomy and architectural control.&lt;/p&gt;

&lt;p&gt;We can design systems that benefit from AI capabilities while preserving clear accountability.&lt;/p&gt;

&lt;h2&gt;
  
  
  When MCP Isn't the Right Choice
&lt;/h2&gt;

&lt;p&gt;One of the responsibilities of a software architect is recognizing when a technology isn't necessary.&lt;/p&gt;

&lt;p&gt;And MCP is no exception.&lt;/p&gt;

&lt;p&gt;If two backend services need to exchange information through a deterministic integration with well-defined contracts, traditional APIs or asynchronous messaging may already be the most appropriate solution.&lt;/p&gt;

&lt;p&gt;Introducing MCP into that interaction might add complexity without providing meaningful benefits.&lt;/p&gt;

&lt;p&gt;Similarly, we shouldn't expose every internal operation as an MCP tool just because we can.&lt;/p&gt;

&lt;p&gt;Every additional capability introduces maintenance requirements, security considerations, and governance responsibilities.&lt;/p&gt;

&lt;p&gt;The right question isn't whether a feature can be implemented using MCP.&lt;/p&gt;

&lt;p&gt;It's whether MCP provides value for the problem we're trying to solve.&lt;/p&gt;

&lt;p&gt;Architecture is about making deliberate trade-offs.&lt;/p&gt;

&lt;p&gt;And sometimes the best decision is to avoid introducing another abstraction.&lt;/p&gt;

&lt;h2&gt;
  
  
  Final Thoughts: The Protocol Simplifies Integration, Not Responsibility
&lt;/h2&gt;

&lt;p&gt;MCP represents an important step forward for AI-powered software.&lt;/p&gt;

&lt;p&gt;By standardizing how applications expose tools, resources, and contextual information, it reduces integration friction and enables new possibilities for automation and intelligent workflows.&lt;/p&gt;

&lt;p&gt;That's genuinely valuable.&lt;/p&gt;

&lt;p&gt;But making an integration easy to implement doesn't automatically make it production-ready.&lt;/p&gt;

&lt;p&gt;Security, contracts, authorization, observability, reliability, and governance remain essential.&lt;/p&gt;

&lt;p&gt;In fact, the more autonomy we give AI agents, the more important those architectural foundations become.&lt;/p&gt;

&lt;p&gt;And perhaps that's the most important point I'd like to leave you with.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The challenge isn't simply enabling AI agents to do more. It's designing systems where we can understand, control, and trust what they're allowed to do.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Regardless of the technology involved, that's still one of the fundamental responsibilities of software architecture.&lt;/p&gt;

&lt;h2&gt;
  
  
  Further Reading and Learning Resources
&lt;/h2&gt;

&lt;p&gt;If you'd like to explore MCP beyond introductory tutorials, these are some resources worth studying:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://modelcontextprotocol.io/specification/2026-07-28" rel="noopener noreferrer"&gt;Official MCP Specification&lt;/a&gt;&lt;/strong&gt;: The best place to understand the protocol's architecture, contracts, and capabilities.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://blog.modelcontextprotocol.io/posts/2026-07-28/" rel="noopener noreferrer"&gt;What's New in MCP 2026-07-28&lt;/a&gt;&lt;/strong&gt;: An overview of changes involving stateless communication, authorization, transport, and extensions.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices" rel="noopener noreferrer"&gt;MCP Security Best Practices&lt;/a&gt;&lt;/strong&gt;: Official guidance on security threats, trust boundaries, and mitigation strategies.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://owasp.org/projects/mcp-top-10/" rel="noopener noreferrer"&gt;OWASP MCP Top 10&lt;/a&gt;&lt;/strong&gt;: A useful reference for understanding security risks in MCP-enabled systems.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://github.com/modelcontextprotocol/csharp-sdk" rel="noopener noreferrer"&gt;Official MCP C# SDK&lt;/a&gt;&lt;/strong&gt;: A great starting point for experimenting with MCP in .NET.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>ai</category>
      <category>mcp</category>
      <category>software</category>
    </item>
    <item>
      <title>.NET 11 and C# 15: What Really Changes for Developers?</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Tue, 10 Nov 2026 13:48:08 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/net-11-and-c-15-what-really-changes-for-developers-291m</link>
      <guid>https://dev.to/rodri-oliveira-dev/net-11-and-c-15-what-really-changes-for-developers-291m</guid>
      <description>&lt;p&gt;Every new .NET release brings a substantial number of improvements: performance optimizations, language features, new APIs, and changes to existing behavior.&lt;/p&gt;

&lt;p&gt;The challenge isn't keeping up with every announcement. It's understanding which changes actually make a difference when developing and maintaining applications.&lt;/p&gt;

&lt;p&gt;.NET 11 and C# 15, scheduled for general availability in November 2026, continue this evolution. Highlights include union types, closed hierarchies, a new asynchronous execution model, improvements in SQL generation, and better integration with observability tools.&lt;/p&gt;

&lt;p&gt;Some of these features can significantly simplify our code. Others work behind the scenes, reducing execution overhead or addressing behaviors that have been difficult to work with.&lt;/p&gt;

&lt;p&gt;There are also changes that require careful attention, particularly for applications using Entity Framework Core, SQL Server, Cosmos DB, or background services.&lt;/p&gt;

&lt;p&gt;In this article, I'd like to explore what I consider the most relevant developments, explaining not just what has changed, but why these changes matter and how we can evaluate them in real-world projects.&lt;/p&gt;

&lt;h2&gt;
  
  
  C# 15: A More Expressive Language
&lt;/h2&gt;

&lt;p&gt;One of the things I've always appreciated about C# is its ability to evolve without abandoning the principles that made it popular: strong typing, readability, and a consistent ecosystem.&lt;/p&gt;

&lt;p&gt;C# 15 continues in that direction. Some additions are relatively small syntax improvements, while others can directly influence how we model our domains.&lt;/p&gt;

&lt;h3&gt;
  
  
  Union Types: Making Possibilities Explicit
&lt;/h3&gt;

&lt;p&gt;Imagine a payment operation that can end in three states: approved, declined, or pending.&lt;/p&gt;

&lt;p&gt;A traditional implementation might use a class containing a status property, several optional properties, and conditional checks to determine which information is available.&lt;/p&gt;

&lt;p&gt;That works, but there's a problem: the model may allow combinations of properties that don't make sense.&lt;/p&gt;

&lt;p&gt;With union types, we can explicitly represent a result that belongs to a known set of possible types.&lt;/p&gt;

&lt;p&gt;In C# 15, we can declare a union using the &lt;code&gt;union&lt;/code&gt; keyword.&lt;/p&gt;

&lt;p&gt;For example, assuming three types have already been defined, &lt;code&gt;PaymentApproved&lt;/code&gt;, &lt;code&gt;PaymentDeclined&lt;/code&gt;, and &lt;code&gt;PaymentPending&lt;/code&gt;, we can write:&lt;/p&gt;

&lt;p&gt;&lt;code&gt;public union PaymentResult(PaymentApproved, PaymentDeclined, PaymentPending);&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;The compiler understands the types that make up the union and can verify whether a &lt;code&gt;switch&lt;/code&gt; expression handles every possible case.&lt;/p&gt;

&lt;p&gt;This is particularly interesting in domain-oriented applications.&lt;/p&gt;

&lt;p&gt;Instead of representing results through combinations of Boolean values, strings, and optional properties, we can express different outcomes directly through the type system.&lt;/p&gt;

&lt;p&gt;The benefit isn't simply writing less code. It's making the model more explicit and allowing the compiler to catch certain errors before execution.&lt;/p&gt;

&lt;p&gt;Of course, union types don't replace domain modeling. Entities, value objects, and aggregates still have their own responsibilities. This is another tool for accurately representing states and outcomes.&lt;/p&gt;

&lt;h3&gt;
  
  
  Closed Hierarchies: Greater Control Over Inheritance
&lt;/h3&gt;

&lt;p&gt;Another interesting addition is the &lt;code&gt;closed&lt;/code&gt; modifier.&lt;/p&gt;

&lt;p&gt;It allows us to declare that a class can only have direct descendants defined within the same assembly.&lt;/p&gt;

&lt;p&gt;As a result, the compiler can identify the types directly derived from that class and verify pattern coverage in certain &lt;code&gt;switch&lt;/code&gt; expressions.&lt;/p&gt;

&lt;p&gt;Consider a set of operation states: created, processing, and completed.&lt;/p&gt;

&lt;p&gt;When those states belong to a controlled hierarchy, we can prevent new directly derived types from being introduced freely by other assemblies.&lt;/p&gt;

&lt;p&gt;There's an important distinction: the restriction isn't automatically transitive. If a derived class isn't closed, it may still allow external inheritance.&lt;/p&gt;

&lt;p&gt;In systems built around Domain-Driven Design (DDD), this feature can be useful when representing concepts with a clearly defined set of specializations.&lt;/p&gt;

&lt;h3&gt;
  
  
  Other Language Improvements
&lt;/h3&gt;

&lt;p&gt;C# 15 also introduces arguments in collection expressions, making it possible to specify construction parameters such as initial capacity and comparers using &lt;code&gt;with(...)&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Extension indexers allow us to add index-based access syntax to existing types without modifying their original implementations.&lt;/p&gt;

&lt;p&gt;Labeled &lt;code&gt;break&lt;/code&gt; and &lt;code&gt;continue&lt;/code&gt; statements make nested loops easier to control, avoiding some approaches that previously required auxiliary variables or &lt;code&gt;goto&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;These are relatively small improvements individually, but they reinforce an ongoing trend: making code more declarative without sacrificing clarity about its behavior.&lt;/p&gt;

&lt;h2&gt;
  
  
  Runtime Async: An Important Change to Asynchronous Execution
&lt;/h2&gt;

&lt;p&gt;Among the .NET 11 features, Runtime Async deserves particular attention.&lt;/p&gt;

&lt;p&gt;To understand its purpose, we first need to revisit how asynchronous methods traditionally work in C#.&lt;/p&gt;

&lt;p&gt;When we write a method using &lt;code&gt;async&lt;/code&gt; and &lt;code&gt;await&lt;/code&gt;, the compiler typically transforms that code into a state machine.&lt;/p&gt;

&lt;p&gt;This structure manages suspension points, preserves the necessary state, and allows execution to resume when the awaited operation completes.&lt;/p&gt;

&lt;p&gt;It's an efficient model, but it comes with costs associated with generated code, state management, and continuation execution.&lt;/p&gt;

&lt;p&gt;Runtime Async introduces a different approach.&lt;/p&gt;

&lt;p&gt;Instead of relying on traditional compiler-generated state machines, the runtime itself participates directly in managing execution suspension and resumption.&lt;/p&gt;

&lt;h3&gt;
  
  
  What Does This Mean in Practice?
&lt;/h3&gt;

&lt;p&gt;The first potential benefit is reduced overhead in asynchronous operations.&lt;/p&gt;

&lt;p&gt;In applications that execute thousands of concurrent operations, small optimizations can accumulate and produce meaningful results.&lt;/p&gt;

&lt;p&gt;Another benefit is the possibility of simpler stack traces.&lt;/p&gt;

&lt;p&gt;Anyone who has investigated an exception across multiple asynchronous calls knows that understanding the original execution flow isn't always straightforward.&lt;/p&gt;

&lt;p&gt;Runtime Async aims to make that diagnostic process more direct.&lt;/p&gt;

&lt;p&gt;However, we should avoid jumping to conclusions.&lt;/p&gt;

&lt;p&gt;It doesn't mean every asynchronous application will automatically become faster, or that every stack trace will shrink by a specific amount.&lt;/p&gt;

&lt;p&gt;Results depend on the workload, operations being performed, and characteristics of the code.&lt;/p&gt;

&lt;p&gt;It's also important to remember that &lt;strong&gt;Runtime Async remains an experimental feature in .NET 11&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Although parts of the framework itself are already compiled using this model, enabling it for application code requires an explicit project configuration using &lt;code&gt;runtime-async=on&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;My recommendation is to evaluate it first in experimental projects, running performance, stability, and compatibility tests before considering it for critical systems.&lt;/p&gt;

&lt;h2&gt;
  
  
  JIT Improvements: Better Performance Without Necessarily Changing Your Code
&lt;/h2&gt;

&lt;p&gt;Not every performance improvement requires application changes.&lt;/p&gt;

&lt;p&gt;The Just-in-Time (JIT) compiler, responsible for translating intermediate language into executable machine instructions, has also received optimizations.&lt;/p&gt;

&lt;p&gt;These include eliminating redundant bounds checks, improving devirtualization, and simplifying certain operations.&lt;/p&gt;

&lt;p&gt;A bounds check, for example, ensures that accessing an array element doesn't exceed its valid range.&lt;/p&gt;

&lt;p&gt;That protection is essential, but the compiler may identify situations where an additional check is unnecessary.&lt;/p&gt;

&lt;p&gt;When that happens, it can eliminate redundant work without compromising safety.&lt;/p&gt;

&lt;p&gt;Devirtualization follows a similar principle: when the JIT can safely determine which implementation will be called, it may optimize virtual dispatch and, in some cases, enable additional optimizations.&lt;/p&gt;

&lt;p&gt;These improvements are particularly valuable because existing applications may benefit from them.&lt;/p&gt;

&lt;p&gt;Still, performance needs to be measured.&lt;/p&gt;

&lt;p&gt;Before attributing improvements exclusively to a new runtime version, it's worth using tools such as BenchmarkDotNet and examining actual CPU usage, memory consumption, latency, and throughput.&lt;/p&gt;

&lt;p&gt;An isolated benchmark doesn't necessarily represent the behavior of an entire application.&lt;/p&gt;

&lt;h2&gt;
  
  
  ASP.NET Core 11: Less Repetitive Infrastructure Code
&lt;/h2&gt;

&lt;p&gt;ASP.NET Core continues evolving in a direction I consider positive: providing common infrastructure capabilities without requiring every team to build similar solutions independently.&lt;/p&gt;

&lt;h3&gt;
  
  
  Asynchronous Validation in Minimal APIs
&lt;/h3&gt;

&lt;p&gt;Previously, validation operations that depended on external queries often required pipeline customization or checks directly inside endpoints.&lt;/p&gt;

&lt;p&gt;ASP.NET Core 11 expands support for asynchronous validation, allowing rules to query databases or external services without blocking threads while waiting.&lt;/p&gt;

&lt;p&gt;For example, this can be useful when checking whether an identifier is already registered.&lt;/p&gt;

&lt;p&gt;However, there's an important architectural distinction.&lt;/p&gt;

&lt;p&gt;Being able to perform asynchronous validation doesn't mean every validation rule should depend on external infrastructure.&lt;/p&gt;

&lt;p&gt;Simple checks, such as email formatting and required fields, still belong naturally at the application boundary.&lt;/p&gt;

&lt;p&gt;Rules involving domain invariants should remain close to the domain model responsible for enforcing them.&lt;/p&gt;

&lt;p&gt;Also, checking a database for uniqueness before inserting a record doesn't eliminate the need for a database constraint. Two concurrent requests may still pass the validation.&lt;/p&gt;

&lt;h3&gt;
  
  
  OpenTelemetry and Observability
&lt;/h3&gt;

&lt;p&gt;ASP.NET Core now adds OpenTelemetry semantic attributes directly to HTTP activities.&lt;/p&gt;

&lt;p&gt;This reduces the need for a dedicated instrumentation package to obtain certain request-related information.&lt;/p&gt;

&lt;p&gt;It doesn't mean the entire observability infrastructure is automatically configured. We still need to define collection, export, sampling, and trace correlation.&lt;/p&gt;

&lt;p&gt;In distributed systems, this information is essential for understanding the path a request takes across multiple services.&lt;/p&gt;

&lt;p&gt;The improvement brings the framework closer to observability standards already widely adopted across the industry.&lt;/p&gt;

&lt;h3&gt;
  
  
  OpenAPI 3.2 and AI Agent Integration
&lt;/h3&gt;

&lt;p&gt;Another development is the use of OpenAPI 3.2 as the default specification version for generated documents.&lt;/p&gt;

&lt;p&gt;Among its benefits are more accurate descriptions of responses based on Server-Sent Events (SSE).&lt;/p&gt;

&lt;p&gt;For APIs that continuously stream events, more expressive contracts help tools and consumers understand the data format.&lt;/p&gt;

&lt;p&gt;The addition of the &lt;code&gt;mcpserver&lt;/code&gt; template to the SDK is also worth highlighting.&lt;/p&gt;

&lt;p&gt;Using &lt;code&gt;dotnet new mcpserver&lt;/code&gt;, we can create the initial structure of a server based on the Model Context Protocol (MCP).&lt;/p&gt;

&lt;p&gt;MCP makes it easier to expose tools and capabilities to AI-powered applications and agents in a controlled manner.&lt;/p&gt;

&lt;p&gt;This creates interesting opportunities to integrate existing systems with new automation interfaces, provided that authentication, authorization, and data exposure are carefully addressed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Entity Framework Core 11: Better Queries and More Flexible Modeling
&lt;/h2&gt;

&lt;p&gt;Entity Framework Core 11 introduces relevant improvements in both LINQ translation and data mapping.&lt;/p&gt;

&lt;p&gt;One area involves queries using &lt;code&gt;Include&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Depending on entity relationships, previous versions could generate unnecessary joins and ordering operations, particularly in split queries using &lt;code&gt;AsSplitQuery()&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;EF Core 11 can eliminate some of those operations.&lt;/p&gt;

&lt;p&gt;In a specific benchmark published by the EF Core team, this optimization resulted in approximately a 29% performance improvement.&lt;/p&gt;

&lt;p&gt;That's an interesting result, but it needs to be interpreted correctly: it isn't a promise that every query or application will become 29% faster.&lt;/p&gt;

&lt;h3&gt;
  
  
  FullJoin, MaxBy, and MinBy
&lt;/h3&gt;

&lt;p&gt;The new LINQ &lt;code&gt;FullJoin&lt;/code&gt; operator allows us to represent full outer joins between data sets.&lt;/p&gt;

&lt;p&gt;A full outer join preserves records from both sides, even when no matching record exists.&lt;/p&gt;

&lt;p&gt;This can be useful for reconciliation processes, comparing data sources, and generating reports that need to identify records present in only one source.&lt;/p&gt;

&lt;p&gt;EF Core 11 can translate this operator into &lt;code&gt;FULL JOIN&lt;/code&gt; on compatible relational database providers.&lt;/p&gt;

&lt;p&gt;Translation support has also been expanded for operations such as &lt;code&gt;MaxBy&lt;/code&gt; and &lt;code&gt;MinBy&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;These operations identify the element associated with the highest or lowest value of a specified criterion without requiring the entire collection to be transferred to the application.&lt;/p&gt;

&lt;p&gt;The advantage is executing the operation directly in the database when a compatible translation exists.&lt;/p&gt;

&lt;h3&gt;
  
  
  Complex Types and DDD
&lt;/h3&gt;

&lt;p&gt;Another improvement I consider particularly relevant is expanded support for complex types.&lt;/p&gt;

&lt;p&gt;EF Core 11 allows them to be used in inheritance scenarios involving TPT and TPC strategies, while offering greater flexibility when configuring properties.&lt;/p&gt;

&lt;p&gt;For developers working with Domain-Driven Design, this can make value object mapping easier.&lt;/p&gt;

&lt;p&gt;An address, for example, can be represented as a dedicated type instead of spreading properties such as street, city, and postal code across an entity.&lt;/p&gt;

&lt;p&gt;EF Core can map that structure without requiring the domain model to be designed entirely around database tables.&lt;/p&gt;

&lt;p&gt;This doesn't eliminate the need to understand persistence, but it helps reduce coupling between domain modeling decisions and ORM limitations.&lt;/p&gt;

&lt;h3&gt;
  
  
  Vector and Hybrid Search
&lt;/h3&gt;

&lt;p&gt;EF Core 11 also expands the possibilities for working with vector data.&lt;/p&gt;

&lt;p&gt;In semantic search applications, embeddings represent information as numerical structures that can be compared using similarity calculations.&lt;/p&gt;

&lt;p&gt;Integration with SQL Server vector capabilities makes it easier to build queries that combine semantic similarity with traditional text search.&lt;/p&gt;

&lt;p&gt;This approach is particularly interesting for applications using information retrieval to support AI systems.&lt;/p&gt;

&lt;p&gt;However, some APIs remain experimental and depend on the capabilities available in the database version being used.&lt;/p&gt;

&lt;p&gt;Before adopting them, we need to evaluate infrastructure requirements, result quality, and query behavior.&lt;/p&gt;

&lt;h2&gt;
  
  
  Libraries and Tools: Small Improvements That Make Everyday Work Easier
&lt;/h2&gt;

&lt;p&gt;Beyond the headline features, .NET 11 introduces practical improvements to its libraries and SDK.&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;Process.RunAndCaptureTextAsync&lt;/code&gt; API, for example, simplifies running external processes and capturing their results.&lt;/p&gt;

&lt;p&gt;JSON Lines support also makes incremental processing easier in scenarios where each line represents an independent JSON document.&lt;/p&gt;

&lt;p&gt;This can be useful for data pipelines, integrations, and streaming large volumes of information.&lt;/p&gt;

&lt;p&gt;In the SDK, the &lt;code&gt;#:include&lt;/code&gt; directive allows file-based applications to organize code across multiple C# files without initially requiring a conventional project structure.&lt;/p&gt;

&lt;p&gt;I don't consider this a replacement for well-structured solutions, but it can be useful for scripts, internal tools, and small automation tasks.&lt;/p&gt;

&lt;p&gt;EF Core 11 also improves migration tooling, including the ability to create and apply a migration in a single operation and centralize options in &lt;code&gt;.config/dotnet-ef.json&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Individually, these may seem like minor changes, but they can reduce repetitive development tasks.&lt;/p&gt;

&lt;h2&gt;
  
  
  Breaking Changes: Where Upgrading Requires Extra Care
&lt;/h2&gt;

&lt;p&gt;So far, we've focused mostly on benefits. However, upgrading a platform can also change important behaviors.&lt;/p&gt;

&lt;p&gt;And some .NET 11 changes deserve special attention.&lt;/p&gt;

&lt;h3&gt;
  
  
  BackgroundService and Exception Propagation
&lt;/h3&gt;

&lt;p&gt;In .NET 11, when a &lt;code&gt;BackgroundService&lt;/code&gt; fails and the host is configured with &lt;code&gt;BackgroundServiceExceptionBehavior.StopHost&lt;/code&gt;, host execution and shutdown methods propagate that failure.&lt;/p&gt;

&lt;p&gt;Previously, the process could terminate with an exit code indicating success even after a background service had failed.&lt;/p&gt;

&lt;p&gt;The new behavior makes these failures more visible.&lt;/p&gt;

&lt;p&gt;For applications running in containers or orchestrated environments, this can make abnormal termination easier to detect.&lt;/p&gt;

&lt;p&gt;On the other hand, it's important to review scripts, monitoring systems, and restart policies that depend on the process exit code.&lt;/p&gt;

&lt;h3&gt;
  
  
  SQL Server Compatibility
&lt;/h3&gt;

&lt;p&gt;EF Core 11 now assumes compatibility level 160, associated with SQL Server 2022.&lt;/p&gt;

&lt;p&gt;This enables the use of newer SQL capabilities, but it may generate queries that are incompatible with older database versions or databases configured with lower compatibility levels.&lt;/p&gt;

&lt;p&gt;Therefore, upgrading Entity Framework isn't just about verifying that the C# code still compiles.&lt;/p&gt;

&lt;p&gt;We also need to consider how the generated SQL behaves.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cosmos DB and the Risk of Data Loss
&lt;/h3&gt;

&lt;p&gt;This is one of the changes I consider most important.&lt;/p&gt;

&lt;p&gt;The EF Core provider for Cosmos DB now uses &lt;code&gt;System.Text.Json&lt;/code&gt; instead of Newtonsoft.Json.&lt;/p&gt;

&lt;p&gt;With this change, JSON properties that aren't mapped in the model are no longer automatically preserved.&lt;/p&gt;

&lt;p&gt;Imagine a document containing fields used by another application but unknown to the current EF Core model.&lt;/p&gt;

&lt;p&gt;When that document is loaded and saved again, those additional fields may be lost.&lt;/p&gt;

&lt;p&gt;This isn't merely an API compatibility issue. It represents a real risk to data integrity.&lt;/p&gt;

&lt;p&gt;Microsoft recommends explicitly mapping the required properties or using &lt;code&gt;CosmosClient&lt;/code&gt; directly when full control over the JSON document structure is necessary.&lt;/p&gt;

&lt;p&gt;The provider also stops supporting synchronous input/output operations.&lt;/p&gt;

&lt;h3&gt;
  
  
  Additional Considerations
&lt;/h3&gt;

&lt;p&gt;.NET 11 raises the minimum instruction-set requirement for x86/x64 processors to &lt;code&gt;x86-64-v2&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;It also introduces additional integrity checks when reading ZIP and TAR files, potentially resulting in exceptions for invalid archives.&lt;/p&gt;

&lt;p&gt;These changes reinforce an important principle: before upgrading, we need to understand both our infrastructure and the behaviors our application depends on.&lt;/p&gt;

&lt;h2&gt;
  
  
  Is Upgrading to .NET 11 Worth It?
&lt;/h2&gt;

&lt;p&gt;This may be the most important question of all.&lt;/p&gt;

&lt;p&gt;.NET 11 follows the STS support lifecycle, with approximately two years of support, expected through November 2028.&lt;/p&gt;

&lt;p&gt;.NET 10, on the other hand, is an LTS release with official support through November 14, 2028.&lt;/p&gt;

&lt;p&gt;Therefore, teams already using .NET 10 don't need to upgrade immediately just because a newer version is available.&lt;/p&gt;

&lt;p&gt;In enterprise systems, I prefer evaluating upgrades through three dimensions: technical necessity, operational risk, and measurable benefits.&lt;/p&gt;

&lt;p&gt;If a feature solves a concrete problem, reduces complexity, or provides meaningful performance improvements, there's a good reason to investigate it.&lt;/p&gt;

&lt;p&gt;On the other hand, when an application is stable, depends on libraries that aren't yet compatible, or operates under significant constraints, rushing an upgrade may introduce unnecessary risks.&lt;/p&gt;

&lt;p&gt;A reasonable strategy is to start with less critical applications, run regression tests, compare metrics, and review breaking changes before moving to core systems.&lt;/p&gt;

&lt;p&gt;It's also worth remembering that we don't necessarily need to adopt every new language feature.&lt;/p&gt;

&lt;p&gt;A runtime upgrade can provide benefits without requiring a domain model rewrite. Similarly, new C# features can be introduced gradually as their usefulness becomes clear.&lt;/p&gt;

&lt;p&gt;And there's an important distinction between upgrading technology and improving architecture.&lt;/p&gt;

&lt;p&gt;An application with excessive coupling, poorly distributed responsibilities, or inadequate observability won't have those problems solved simply because it's running on a newer .NET version.&lt;/p&gt;

&lt;h2&gt;
  
  
  Final Thoughts
&lt;/h2&gt;

&lt;p&gt;.NET 11 and C# 15 represent another step forward for an ecosystem that continues investing in performance, productivity, and integration capabilities.&lt;/p&gt;

&lt;p&gt;Among the new features, I find union types, closed hierarchies, Runtime Async, and Entity Framework Core's query translation improvements particularly relevant.&lt;/p&gt;

&lt;p&gt;The additions to ASP.NET Core also demonstrate increasing attention to observability, API contracts, and integration with modern tools.&lt;/p&gt;

&lt;p&gt;But the most important takeaway isn't knowing every available feature.&lt;/p&gt;

&lt;p&gt;It's understanding which problems these features solve, what limitations they have, and how they can contribute to applications that are easier to maintain, observe, and evolve.&lt;/p&gt;

&lt;p&gt;As developers and software architects, we need to keep learning without turning every release into a race to adopt the latest technology.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The best technical decision isn't necessarily to use the newest feature. It's to choose the one that solves the right problem at a cost and risk level that make sense.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Key Takeaways
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;C# 15:&lt;/strong&gt; Union types and closed hierarchies offer new ways to model states and outcomes with stronger type safety.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Runtime:&lt;/strong&gt; JIT improvements may benefit existing applications, while Runtime Async is promising but remains experimental.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;ASP.NET Core 11:&lt;/strong&gt; Asynchronous validation, OpenTelemetry, OpenAPI 3.2, and MCP support expand the platform's capabilities.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;EF Core 11:&lt;/strong&gt; More efficient queries, new LINQ operators, and vector search capabilities create opportunities, but Cosmos DB changes require particular care.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Upgrades:&lt;/strong&gt; Compatibility, testing, observability, and measurable benefits should guide the decision.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Further Reading
&lt;/h2&gt;

&lt;p&gt;Microsoft's official documentation is the best place to start. I recommend beginning with language and runtime changes, then exploring the areas most relevant to your work.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What's New in C# 15&lt;/strong&gt;&lt;br&gt;&lt;br&gt;
&lt;a href="https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-15" rel="noopener noreferrer"&gt;https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-15&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Covers language changes, including examples of union types, closed hierarchies, and extension indexers.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What's New in the .NET 11 Runtime&lt;/strong&gt;&lt;br&gt;&lt;br&gt;
&lt;a href="https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/runtime" rel="noopener noreferrer"&gt;https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/runtime&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Explains Runtime Async and the main performance optimizations.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What's New in ASP.NET Core 11&lt;/strong&gt;&lt;br&gt;&lt;br&gt;
&lt;a href="https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-11" rel="noopener noreferrer"&gt;https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-11&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Documents new validation, OpenAPI, observability, and MCP integration capabilities.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What's New in Entity Framework Core 11&lt;/strong&gt;&lt;br&gt;&lt;br&gt;
&lt;a href="https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-11.0/whatsnew" rel="noopener noreferrer"&gt;https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-11.0/whatsnew&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;A useful reference for LINQ translation, complex types, migrations, and vector search.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Breaking Changes in EF Core 11&lt;/strong&gt;&lt;br&gt;&lt;br&gt;
&lt;a href="https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-11.0/breaking-changes" rel="noopener noreferrer"&gt;https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-11.0/breaking-changes&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Essential reading before planning upgrades for existing systems.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;.NET Support Policy&lt;/strong&gt;&lt;br&gt;&lt;br&gt;
&lt;a href="https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core" rel="noopener noreferrer"&gt;https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Provides information about LTS and STS release cycles and official support dates.&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>csharp</category>
      <category>aspnet</category>
    </item>
    <item>
      <title>Exploring MCP: From My First Integration to Architectural Decisions</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 04 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/exploring-mcp-from-my-first-integration-to-architectural-decisions-36gf</link>
      <guid>https://dev.to/rodri-oliveira-dev/exploring-mcp-from-my-first-integration-to-architectural-decisions-36gf</guid>
      <description>&lt;p&gt;During my vacation, I decided to spend some time learning more about the Model Context Protocol, or MCP for short.&lt;/p&gt;

&lt;p&gt;I had already been following the topic and had implemented MCP support in a few of my open-source projects. Still, I wanted to understand the protocol better, experiment with a few possibilities, and, most importantly, revisit some of my earlier decisions to see if they still made sense.&lt;/p&gt;

&lt;p&gt;Rather than starting another project from scratch, I thought it would be more useful to revisit what I had already built. After all, these are tools that solve real problems, have their own business rules, and were designed independently of any AI integration.&lt;/p&gt;

&lt;p&gt;I ended up spending time with projects like &lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard&lt;/a&gt;, &lt;a href="https://github.com/rodri-oliveira-dev/Repo2C4" rel="noopener noreferrer"&gt;Repo2C4&lt;/a&gt;, &lt;a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector" rel="noopener noreferrer"&gt;DotNetRepoInspector&lt;/a&gt;, and &lt;a href="https://github.com/rodri-oliveira-dev/complexity-analyzers" rel="noopener noreferrer"&gt;Complexity Analyzers&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;What made this exercise interesting was that each project had different needs. Some only needed to expose information, others performed more complex analysis, and a few involved situations where an agent could participate in generating files.&lt;/p&gt;

&lt;p&gt;As I went through them, I realized that implementing the protocol itself wasn't necessarily the hardest part.&lt;/p&gt;

&lt;p&gt;The more interesting questions were about what should be exposed to an agent, how much freedom it should have, how to preserve existing business rules, and how to make sure the results remained reliable.&lt;/p&gt;

&lt;p&gt;Those questions ended up shaping most of what I learned.&lt;/p&gt;

&lt;h2&gt;
  
  
  MCP is useful, but it isn't magic
&lt;/h2&gt;

&lt;p&gt;For anyone who hasn't worked with it yet, MCP is an open protocol that standardizes communication between AI applications and external systems.&lt;/p&gt;

&lt;p&gt;The idea is to let a compatible client discover and use capabilities provided by a server without needing to understand every implementation detail.&lt;/p&gt;

&lt;p&gt;Think about a tool that analyzes a .NET solution.&lt;/p&gt;

&lt;p&gt;Normally, you would run a command, get a report, and interpret the results. An agent could attempt the same thing by executing the CLI and reading its output.&lt;/p&gt;

&lt;p&gt;And depending on the situation, that might work perfectly well.&lt;/p&gt;

&lt;p&gt;But with MCP, we can expose more specific operations, such as &lt;code&gt;list_projects&lt;/code&gt;, &lt;code&gt;get_sdk_metadata&lt;/code&gt;, or &lt;code&gt;get_project_reference_graph&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Instead of figuring out which command to execute and how to parse its output, the client receives tools with names, descriptions, defined parameters, and structured responses.&lt;/p&gt;

&lt;p&gt;The protocol also supports &lt;em&gt;resources&lt;/em&gt;, which make information available to clients, and &lt;em&gt;prompts&lt;/em&gt;, which provide reusable interaction templates.&lt;/p&gt;

&lt;p&gt;You don't need to implement all of these in every server. In my projects, I focused mainly on &lt;em&gt;tools&lt;/em&gt; because they were a natural fit for the capabilities I wanted to expose.&lt;/p&gt;

&lt;p&gt;There's an important distinction here, though.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;MCP is not an AI agent, and it isn't a language model either.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The server exposes capabilities. The client handles communication and may make those capabilities available to a language model.&lt;/p&gt;

&lt;p&gt;That separation allows the same tool to work with different compatible clients without being tied to a particular AI provider.&lt;/p&gt;

&lt;p&gt;Conceptually, it's fairly straightforward. Things become more interesting when you start deciding which capabilities to expose and how they should behave.&lt;/p&gt;

&lt;h2&gt;
  
  
  Not everything needs AI
&lt;/h2&gt;

&lt;p&gt;One of the things I found most interesting was how much traditional software functionality can be reused when working with agents.&lt;/p&gt;

&lt;p&gt;Take &lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard&lt;/a&gt;, for example.&lt;/p&gt;

&lt;p&gt;The project can validate Architecture Decision Records, analyze relationships between decisions, and identify potential architectural impacts caused by code changes.&lt;/p&gt;

&lt;p&gt;Much of that functionality is deterministic.&lt;/p&gt;

&lt;p&gt;If an ADR needs to follow a particular structure, contain certain fields, or comply with predefined validation rules, I don't need a language model to check those conditions.&lt;/p&gt;

&lt;p&gt;The application already knows how to do that.&lt;/p&gt;

&lt;p&gt;What MCP adds is the ability for an agent to access those capabilities during its own analysis.&lt;/p&gt;

&lt;p&gt;A tool like &lt;code&gt;validate_adrs&lt;/code&gt; can return the problems found in a set of documents. The agent can then explain the diagnostics, provide context, and suggest improvements.&lt;/p&gt;

&lt;p&gt;But there's a boundary I don't want to cross: an agent shouldn't turn a failed validation into an approval simply because it interpreted the document differently.&lt;/p&gt;

&lt;p&gt;The tool's result needs to represent what was actually verified.&lt;/p&gt;

&lt;p&gt;The same reasoning applies to static analysis, automated tests, contract validation, and plenty of other software engineering tasks.&lt;/p&gt;

&lt;p&gt;A language model can help interpret the results, connect related information, and explain what they mean. That doesn't mean it needs to replace the logic responsible for producing those results.&lt;/p&gt;

&lt;p&gt;In fact, in many cases, I'd rather it didn't.&lt;/p&gt;

&lt;p&gt;When I have a verifiable rule, I want it to produce the same result regardless of which model is being used or how the question was phrased.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why I didn't want to duplicate business logic
&lt;/h2&gt;

&lt;p&gt;Another thing I tried to preserve was the separation between existing functionality and the MCP interface.&lt;/p&gt;

&lt;p&gt;This isn't a concern that appeared because of AI. It's something we've dealt with in software development for a long time.&lt;/p&gt;

&lt;p&gt;Imagine maintaining two implementations for validating an ADR: one used by the CLI and another used by the MCP server.&lt;/p&gt;

&lt;p&gt;Initially, both might work just fine. Then a few fixes and features come along, and differences start appearing.&lt;/p&gt;

&lt;p&gt;A validation rule gets updated in one place but not the other. Diagnostics behave slightly differently. A test covers one execution path but misses the other.&lt;/p&gt;

&lt;p&gt;It's the kind of maintenance problem I'd rather avoid.&lt;/p&gt;

&lt;p&gt;In ADR Guard, both the CLI and the MCP server rely on the same internal domain services.&lt;/p&gt;

&lt;p&gt;In &lt;a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector" rel="noopener noreferrer"&gt;DotNetRepoInspector&lt;/a&gt;, the inspection engine remains independent of whoever consumes its results.&lt;/p&gt;

&lt;p&gt;The same approach appears in &lt;a href="https://github.com/rodri-oliveira-dev/complexity-analyzers" rel="noopener noreferrer"&gt;Complexity Analyzers&lt;/a&gt;, where the MCP server reuses the complexity analysis capabilities already available through the existing tooling.&lt;/p&gt;

&lt;p&gt;The MCP server becomes an adapter.&lt;/p&gt;

&lt;p&gt;It receives parameters, enforces operational boundaries, invokes the appropriate services, and returns responses through the protocol.&lt;/p&gt;

&lt;p&gt;This may sound like a fairly ordinary architectural decision, and in many ways it is. But it makes a difference.&lt;/p&gt;

&lt;p&gt;Business rules remain centralized, tests can be reused, and changes to the protocol don't require rewriting the domain.&lt;/p&gt;

&lt;p&gt;It also helps avoid unnecessary coupling to AI SDKs.&lt;/p&gt;

&lt;p&gt;If I decide to expose the same functionality through HTTP, a CLI, or another integration in the future, the core implementation is still there.&lt;/p&gt;

&lt;p&gt;After more than twenty years working with software, I still find this separation valuable. Integration technologies change, but the domain shouldn't have to change every time they do.&lt;/p&gt;

&lt;h2&gt;
  
  
  An agent doesn't need the entire repository
&lt;/h2&gt;

&lt;p&gt;While working with DotNetRepoInspector and Complexity Analyzers, another question came up: how much information should a tool return?&lt;/p&gt;

&lt;p&gt;It's tempting to expose a single operation that produces a complete report containing everything the application knows.&lt;/p&gt;

&lt;p&gt;But an agent doesn't always need all that information.&lt;/p&gt;

&lt;p&gt;Imagine asking which projects in a solution are still targeting an older version of .NET.&lt;/p&gt;

&lt;p&gt;An initial inventory might be enough to identify the relevant projects. After that, the agent can request additional details only for those that need closer inspection.&lt;/p&gt;

&lt;p&gt;There's little benefit in returning every detail about every project in the very first call.&lt;/p&gt;

&lt;p&gt;In DotNetRepoInspector, this idea appears in the separation between project inventory, project details, reference graphs, and diagnostics.&lt;/p&gt;

&lt;p&gt;Complexity Analyzers follows a similar approach. An analysis can return a summary, and the client can later retrieve detailed evidence for a specific method or member.&lt;/p&gt;

&lt;p&gt;It also supports reusing analysis snapshots instead of repeating potentially expensive work.&lt;/p&gt;

&lt;p&gt;This can reduce the amount of data transferred to the client, the context consumed by the model, and the work performed by the server.&lt;/p&gt;

&lt;p&gt;But there's another benefit I appreciate: each operation becomes easier to understand and test.&lt;/p&gt;

&lt;p&gt;A tool designed to answer a specific question usually has a clearer contract than one that tries to handle every possible request.&lt;/p&gt;

&lt;p&gt;Of course, that doesn't mean splitting everything into dozens of tiny tools. Too much granularity introduces its own complexity.&lt;/p&gt;

&lt;p&gt;The goal is to give the agent enough information to do its job without turning every call into a massive data dump.&lt;/p&gt;

&lt;h3&gt;
  
  
  What happens when the answer isn't clear?
&lt;/h3&gt;

&lt;p&gt;This also made me think about how uncertainty should be represented.&lt;/p&gt;

&lt;p&gt;In Complexity Analyzers, some analyses can produce unknown or inconclusive results.&lt;/p&gt;

&lt;p&gt;When that happens, I'd rather preserve that information in the response.&lt;/p&gt;

&lt;p&gt;An &lt;code&gt;Unknown&lt;/code&gt; result may be less satisfying at first, but it's more accurate than presenting an estimate that isn't supported by enough evidence.&lt;/p&gt;

&lt;p&gt;This matters even more when a language model is interpreting the results.&lt;/p&gt;

&lt;p&gt;An agent can turn incomplete data into a very convincing explanation. If the original contract doesn't communicate its limitations clearly, it becomes harder to distinguish verified facts from assumptions.&lt;/p&gt;

&lt;p&gt;That's why I think MCP tools should expose not only their findings but also relevant diagnostics, limitations, and inconclusive states.&lt;/p&gt;

&lt;p&gt;Sometimes, knowing what couldn't be determined is just as useful as knowing what could.&lt;/p&gt;

&lt;h2&gt;
  
  
  Repo2C4: when the agent can do more than read
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://github.com/rodri-oliveira-dev/Repo2C4" rel="noopener noreferrer"&gt;Repo2C4&lt;/a&gt; turned out to be one of the more interesting projects to revisit.&lt;/p&gt;

&lt;p&gt;Unlike tools focused primarily on querying information, Repo2C4 deals with generating architectural representations using LikeC4.&lt;/p&gt;

&lt;p&gt;That introduces an important distinction between identifying facts in a repository and understanding its architecture.&lt;/p&gt;

&lt;p&gt;Finding project references, dependencies, or implementation patterns provides evidence. But those facts alone aren't always enough to describe architectural components and their relationships correctly.&lt;/p&gt;

&lt;p&gt;In Repo2C4's MCP workflow, the server exposes structured evidence collected from the repository.&lt;/p&gt;

&lt;p&gt;A client can use that evidence to propose an &lt;code&gt;ArchitectureModel&lt;/code&gt;. The server can then validate the proposed model and generate LikeC4 files deterministically.&lt;/p&gt;

&lt;p&gt;The architectural interpretation happens outside the MCP server.&lt;/p&gt;

&lt;p&gt;I like this approach because the model can be proposed by an AI agent, another mechanism, or even prepared manually.&lt;/p&gt;

&lt;p&gt;The server doesn't need to know who came up with the model. It only needs to understand whether the supplied model satisfies its contracts and what it can safely generate from it.&lt;/p&gt;

&lt;p&gt;The more challenging part was handling file writes.&lt;/p&gt;

&lt;p&gt;Reading repository information and modifying repository contents are very different responsibilities.&lt;/p&gt;

&lt;p&gt;For that reason, generation starts in preview mode, with &lt;code&gt;dryRun=true&lt;/code&gt;. Persisting files requires an explicit request, including &lt;code&gt;write=true&lt;/code&gt; and &lt;code&gt;dryRun=false&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The implementation also includes checks to prevent conflicts with managed files and to reject proposals that no longer match the expected state.&lt;/p&gt;

&lt;p&gt;Alongside the MCP server, the project has a separate agent built with Microsoft Agent Framework. It uses the MCP capabilities and includes a human approval step before applying changes.&lt;/p&gt;

&lt;p&gt;I find this separation useful because responsibilities remain visible.&lt;/p&gt;

&lt;p&gt;The server understands its operations and constraints. The agent coordinates the workflow and interprets the evidence. Human approval is part of the process before changes are applied.&lt;/p&gt;

&lt;p&gt;That doesn't eliminate every risk, of course. Approval needs to be tied to a specific proposal, and the repository may change between preview and execution.&lt;/p&gt;

&lt;p&gt;But these are exactly the kinds of details that appear when you move beyond a simple demo and try to build something people can actually use.&lt;/p&gt;

&lt;h2&gt;
  
  
  Security is more than marking a tool as ReadOnly
&lt;/h2&gt;

&lt;p&gt;Security came up repeatedly during this exercise.&lt;/p&gt;

&lt;p&gt;One of my main concerns was controlling filesystem access.&lt;/p&gt;

&lt;p&gt;For local servers, I try to work with an explicitly authorized repository root. Tool operations must stay within that boundary, even when paths are supplied by the client.&lt;/p&gt;

&lt;p&gt;That means handling relative paths, directory traversal attempts, symbolic links, and oversized files.&lt;/p&gt;

&lt;p&gt;Execution time, cancellation, and response size also matter.&lt;/p&gt;

&lt;p&gt;A tool that works perfectly when analyzing a few dozen files might behave very differently when pointed at a large repository.&lt;/p&gt;

&lt;p&gt;Another concern is the content being processed.&lt;/p&gt;

&lt;p&gt;A Markdown document, configuration file, or source code comment might contain text that attempts to influence an agent's behavior.&lt;/p&gt;

&lt;p&gt;That content needs to remain data, not become instructions.&lt;/p&gt;

&lt;p&gt;In ADR Guard, for instance, returned document content is explicitly identified as untrusted. This makes the boundary clearer for the client consuming the information.&lt;/p&gt;

&lt;p&gt;But security annotations don't automatically isolate an application.&lt;/p&gt;

&lt;p&gt;DotNetRepoInspector is a good example of why this distinction matters.&lt;/p&gt;

&lt;p&gt;Although its MCP tools are marked as read-only, inspecting .NET projects may involve MSBuild evaluation, which can load logic defined by the repository itself.&lt;/p&gt;

&lt;p&gt;In other words, declaring a tool &lt;code&gt;ReadOnly&lt;/code&gt; doesn't guarantee that no potentially unsafe code can run during the operation.&lt;/p&gt;

&lt;p&gt;Likewise, using &lt;code&gt;stdio&lt;/code&gt; avoids exposing a network endpoint, but it doesn't solve everything related to process permissions or client behavior.&lt;/p&gt;

&lt;p&gt;There's also a data privacy consideration.&lt;/p&gt;

&lt;p&gt;An MCP server may control which information it reads and returns, but the client may send that information to an external model, depending on its configuration.&lt;/p&gt;

&lt;p&gt;Those are separate trust boundaries.&lt;/p&gt;

&lt;p&gt;I think it's important to be clear about them rather than assume that using a standardized protocol automatically makes an integration secure.&lt;/p&gt;

&lt;h2&gt;
  
  
  MCP, agents, and skills: where does each one fit?
&lt;/h2&gt;

&lt;p&gt;Another project I revisited was &lt;a href="https://github.com/rodri-oliveira-dev/ai-ready-dotnet-workspace" rel="noopener noreferrer"&gt;AI-Ready .NET Workspace&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Its purpose is to provide a .NET development environment prepared for working with AI tools and agents.&lt;/p&gt;

&lt;p&gt;One of the decisions I wanted to make explicit was the separation between concepts that often get mixed together.&lt;/p&gt;

&lt;p&gt;An agent can take on a role, such as reviewing architecture or assisting with implementation.&lt;/p&gt;

&lt;p&gt;A skill can describe a reusable procedure, such as the checks that should be performed before considering a change complete.&lt;/p&gt;

&lt;p&gt;A prompt can organize a particular request or workflow.&lt;/p&gt;

&lt;p&gt;MCP, meanwhile, provides concrete capabilities that those workflows can use.&lt;/p&gt;

&lt;p&gt;In this workspace, the MCP server exposes only two tools: one for retrieving .NET project metadata and another for reading architectural responsibility rules.&lt;/p&gt;

&lt;p&gt;There's no need to provide unrestricted filesystem access, a generic terminal, or arbitrary command execution.&lt;/p&gt;

&lt;p&gt;I recorded that decision in an ADR because I wanted the responsibilities to remain clear.&lt;/p&gt;

&lt;p&gt;What I found interesting is that an MCP server doesn't necessarily need to be sophisticated.&lt;/p&gt;

&lt;p&gt;Sometimes, two well-defined operations with small contracts are enough to solve a real problem.&lt;/p&gt;

&lt;p&gt;It's easy to get carried away by what agents can potentially do. Having a specific use case helps keep the design focused.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I know whether it actually works?
&lt;/h2&gt;

&lt;p&gt;One thing is having an MCP server that compiles and starts correctly. Another is knowing whether a client can use it consistently.&lt;/p&gt;

&lt;p&gt;That's why I tried to include tests beyond the business logic itself.&lt;/p&gt;

&lt;p&gt;The projects cover areas such as protocol initialization, tool discovery, real tool calls, invalid arguments, cancellation, and operational limits.&lt;/p&gt;

&lt;p&gt;Some tests start the MCP server as a separate process and use the official SDK client to communicate with it.&lt;/p&gt;

&lt;p&gt;This helps catch integration problems that ordinary unit tests might miss.&lt;/p&gt;

&lt;p&gt;A simple example is standard output.&lt;/p&gt;

&lt;p&gt;With the &lt;code&gt;stdio&lt;/code&gt; transport, standard output is reserved for protocol communication. If the application starts writing log messages there, it can interfere with the MCP client.&lt;/p&gt;

&lt;p&gt;That's an easy detail to overlook when you're used to building console applications.&lt;/p&gt;

&lt;p&gt;But there's another distinction worth making: &lt;strong&gt;testing the protocol isn't the same as testing an agent's behavior.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;An automated test can prove that a tool returns the expected project inventory.&lt;/p&gt;

&lt;p&gt;It doesn't guarantee that a language model will choose that tool for the right question, interpret its result correctly, or avoid unnecessary calls.&lt;/p&gt;

&lt;p&gt;To evaluate that behavior, we need scenarios that are closer to actual usage.&lt;/p&gt;

&lt;p&gt;DotNetRepoInspector, for example, includes deterministic evaluations and compatibility records that distinguish what has been tested from what still requires validation.&lt;/p&gt;

&lt;p&gt;That's an approach I want to keep improving.&lt;/p&gt;

&lt;p&gt;I also think it's important to distinguish between code that exists in a repository and a package that has actually been published and validated for distribution.&lt;/p&gt;

&lt;p&gt;A working implementation doesn't automatically mean the release process is complete.&lt;/p&gt;

&lt;p&gt;These details may not be as exciting as watching an agent perform a task, but they matter when people start depending on the tool.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I still want to explore
&lt;/h2&gt;

&lt;p&gt;MCP continues to evolve, along with its SDKs and the clients that support it.&lt;/p&gt;

&lt;p&gt;That leaves several areas I'd like to investigate further.&lt;/p&gt;

&lt;p&gt;One is interoperability between different clients. Not just checking whether they can start a server, but comparing how they select tools, handle structured responses, and deal with failures.&lt;/p&gt;

&lt;p&gt;Another is understanding how newer protocol revisions affect servers that maintain temporary information, such as the snapshots used by Repo2C4.&lt;/p&gt;

&lt;p&gt;I'm also interested in looking more closely at context usage.&lt;/p&gt;

&lt;p&gt;Detailed tool responses can be valuable, but they can also increase cost and complexity without providing much additional benefit.&lt;/p&gt;

&lt;p&gt;Finding the right balance between summary information and detailed evidence seems worth exploring further.&lt;/p&gt;

&lt;p&gt;And there's the distribution side of things: versioning, contract compatibility, NuGet publishing, and MCP server registration.&lt;/p&gt;

&lt;p&gt;These topics aren't necessarily the most exciting part of working with agents, but they're important if you intend to maintain a tool beyond the initial experiment.&lt;/p&gt;

&lt;h2&gt;
  
  
  A few thoughts after spending time with MCP
&lt;/h2&gt;

&lt;p&gt;Spending part of my vacation studying MCP turned out to be a good opportunity to revisit concepts I've been working with for years.&lt;/p&gt;

&lt;p&gt;Separation of concerns, reusable business logic, explicit contracts, security, and testing are still important.&lt;/p&gt;

&lt;p&gt;The protocol provides an interesting way to make existing capabilities available to agents, but it doesn't remove the need to think about those things.&lt;/p&gt;

&lt;p&gt;I also came away with a clearer understanding that not every application needs a sophisticated agent, and not every tool needs AI built into it.&lt;/p&gt;

&lt;p&gt;In many cases, combining deterministic software that understands a particular problem with language models that can interpret and explain its results seems like a sensible approach.&lt;/p&gt;

&lt;p&gt;For now, I'll keep experimenting with these ideas in my projects.&lt;/p&gt;

&lt;p&gt;There's still plenty I want to learn, particularly around interoperability, security, and how agents behave in real-world scenarios.&lt;/p&gt;

&lt;p&gt;But one conclusion already seems reasonable to me:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before thinking about everything an agent could do, it's worth being very clear about what we actually want to let it do.&lt;/strong&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  A quick recap
&lt;/h2&gt;

&lt;p&gt;If I had to summarize what I learned, I'd say MCP becomes particularly useful when it exposes capabilities that already have clear responsibilities.&lt;/p&gt;

&lt;p&gt;Reusing existing domain logic is usually better than rebuilding it inside the server. Structured responses and focused queries help control context usage. Inconclusive results should remain inconclusive, even when an AI model is interpreting them.&lt;/p&gt;

&lt;p&gt;And tools that can modify the environment need boundaries and authorization mechanisms that reflect what they're capable of doing.&lt;/p&gt;

&lt;p&gt;None of this is particularly new to people who work with software architecture.&lt;/p&gt;

&lt;p&gt;Maybe that's the interesting part. We're learning to use new technologies, but many of the engineering problems we need to solve are still very familiar.&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;p&gt;For anyone interested in learning more about MCP, these are some useful starting points:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://modelcontextprotocol.io/" rel="noopener noreferrer"&gt;Model Context Protocol documentation&lt;/a&gt;: a good introduction to the protocol, its main concepts, and the responsibilities of clients and servers.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/modelcontextprotocol/csharp-sdk" rel="noopener noreferrer"&gt;Official MCP C# SDK&lt;/a&gt;: particularly useful for .NET developers who want to explore how the protocol is implemented.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/microsoft/mcp-for-beginners" rel="noopener noreferrer"&gt;MCP for Beginners by Microsoft&lt;/a&gt;: examples and practical exercises for getting started.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://modelcontextprotocol.io/specification" rel="noopener noreferrer"&gt;Model Context Protocol specification&lt;/a&gt;: for a deeper understanding of contracts, transports, and security considerations.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;I'm also sharing the repositories I used throughout this study:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard&lt;/a&gt; | &lt;a href="https://github.com/rodri-oliveira-dev/Repo2C4" rel="noopener noreferrer"&gt;Repo2C4&lt;/a&gt; | &lt;a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector" rel="noopener noreferrer"&gt;DotNetRepoInspector&lt;/a&gt; | &lt;a href="https://github.com/rodri-oliveira-dev/complexity-analyzers" rel="noopener noreferrer"&gt;Complexity Analyzers&lt;/a&gt; | &lt;a href="https://github.com/rodri-oliveira-dev/ai-ready-dotnet-workspace" rel="noopener noreferrer"&gt;AI-Ready .NET Workspace&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;If you're just getting started, I'd suggest choosing a feature that already exists in one of your own projects.&lt;/p&gt;

&lt;p&gt;It doesn't have to be anything complicated. A simple read-only operation with clear parameters and a structured response is enough to start understanding how the protocol works.&lt;/p&gt;

&lt;p&gt;From there, add some tests, try different clients, and pay attention to the problems that come up.&lt;/p&gt;

&lt;p&gt;That kind of hands-on experimentation is what helped me learn the most.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>mcp</category>
      <category>dotnet</category>
      <category>opensource</category>
    </item>
    <item>
      <title>The C4 Model: How to Communicate Complex Software Architectures Clearly</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 04 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/the-c4-model-how-to-communicate-complex-software-architectures-clearly-1lda</link>
      <guid>https://dev.to/rodri-oliveira-dev/the-c4-model-how-to-communicate-complex-software-architectures-clearly-1lda</guid>
      <description>&lt;p&gt;If you've worked with software architecture, you've probably experienced something interesting: after weeks of discussing technical decisions, integrations, and responsibilities, it's finally time to present the solution, and someone asks a seemingly simple question:&lt;/p&gt;

&lt;p&gt;"But how does all of this work together?"&lt;/p&gt;

&lt;p&gt;It's a fair question. And depending on how we've documented our architecture, answering it can be surprisingly difficult.&lt;/p&gt;

&lt;p&gt;In large-scale systems, we deal with applications, APIs, databases, messaging infrastructure, external services, and different technologies working together. The challenge isn't just making these elements function properly. It's also explaining their responsibilities and relationships.&lt;/p&gt;

&lt;p&gt;A developer needs to understand where to implement a particular feature. An architect needs to identify dependencies, boundaries, and risks. Meanwhile, someone from the business side probably wants to understand what capabilities the solution provides and which systems it depends on.&lt;/p&gt;

&lt;p&gt;Presenting the same diagram to all these audiences usually leads to one of two outcomes: too much technical information for some people and not enough detail for others.&lt;/p&gt;

&lt;p&gt;This is exactly where the &lt;strong&gt;C4 Model&lt;/strong&gt; becomes valuable.&lt;/p&gt;

&lt;p&gt;Created by Simon Brown, C4 provides a way to visualize software architecture through different levels of abstraction. Its main contribution is allowing us to present a solution progressively, starting with the big picture and moving toward implementation details when necessary.&lt;/p&gt;

&lt;p&gt;The idea is simple: we don't need to show everything at once.&lt;/p&gt;

&lt;h2&gt;
  
  
  Understanding the C4 Model
&lt;/h2&gt;

&lt;p&gt;An analogy I find particularly useful is to think of C4 as a map.&lt;/p&gt;

&lt;p&gt;When we want to understand where a city is located, we start by looking at a larger region. Then we zoom in to identify neighborhoods, streets, and eventually specific addresses.&lt;/p&gt;

&lt;p&gt;Software architecture follows a similar principle.&lt;/p&gt;

&lt;p&gt;The C4 Model organizes architectural visualization into four main levels:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Context&lt;/strong&gt;, to understand how a system interacts with users and other systems.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Containers&lt;/strong&gt;, to identify the applications and data stores that make up the solution.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Components&lt;/strong&gt;, to explain how responsibilities are organized within a container.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Code&lt;/strong&gt;, to examine implementation details when they actually matter.&lt;/p&gt;

&lt;p&gt;These levels aren't mandatory development stages, nor do they dictate how a team should work. They're simply different perspectives of the same architecture.&lt;/p&gt;

&lt;p&gt;Another important point: C4 isn't a methodology for deciding whether we should use microservices, hexagonal architecture, event-driven systems, or any other architectural approach. It helps us represent and communicate the decisions we've already made.&lt;/p&gt;

&lt;p&gt;To make things more concrete, let's follow a fictional example: an e-commerce platform that processes orders, handles payments, and integrates with shipping providers.&lt;/p&gt;

&lt;p&gt;We'll use this same system throughout all four levels.&lt;/p&gt;

&lt;h2&gt;
  
  
  Context: Understanding the System Before the Technology
&lt;/h2&gt;

&lt;p&gt;The first level, known as &lt;strong&gt;C1 or the System Context Diagram&lt;/strong&gt;, presents the system as part of a larger environment.&lt;/p&gt;

&lt;p&gt;At this stage, we don't need to explain which programming languages were used, where data is stored, or how many services exist.&lt;/p&gt;

&lt;p&gt;We want to answer more fundamental questions: Who uses the solution? What is its purpose? Which external systems does it interact with?&lt;/p&gt;

&lt;p&gt;Let's consider our e-commerce platform.&lt;/p&gt;

&lt;p&gt;Customers access the platform to browse products and place orders. The solution communicates with a payment provider to process transactions and with a shipping provider to arrange deliveries. Internal operations staff can also use the platform to monitor orders.&lt;/p&gt;

&lt;p&gt;These relationships are enough to begin understanding the system's context.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fy5pppi2ovy36qba6ln8b.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fy5pppi2ovy36qba6ln8b.png" alt=" " width="800" height="583"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The diagram should clearly identify the system we're examining and which elements fall outside its direct responsibilities.&lt;/p&gt;

&lt;p&gt;That might sound simple, but it has important implications.&lt;/p&gt;

&lt;p&gt;When we identify external systems, we begin recognizing dependencies. An outage at the payment provider, for example, could prevent customers from completing purchases. A failure in the shipping integration could affect delivery updates.&lt;/p&gt;

&lt;p&gt;The diagram doesn't explain how these problems will be handled yet, but it helps us identify where they might occur.&lt;/p&gt;

&lt;p&gt;This level is particularly useful when talking to stakeholders, product managers, business teams, and anyone who needs to understand the solution without getting into implementation details.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A good C1 diagram should make sense even to someone unfamiliar with the technical implementation.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If we have to explain infrastructure details for someone to understand a system context diagram, we're probably showing more information than necessary.&lt;/p&gt;

&lt;h2&gt;
  
  
  Containers: Discovering How the Solution Is Organized
&lt;/h2&gt;

&lt;p&gt;Once we understand the system from the outside, we can start looking at its internal structure.&lt;/p&gt;

&lt;p&gt;This is where &lt;strong&gt;C2, the Container Diagram&lt;/strong&gt;, comes in.&lt;/p&gt;

&lt;p&gt;Before going any further, let's clear up a common misconception: in the C4 Model, a container doesn't necessarily mean Docker or Kubernetes.&lt;/p&gt;

&lt;p&gt;A container represents an application or data store with a specific responsibility within the system. It might be a web application, an API, a background service, a database, or something similar.&lt;/p&gt;

&lt;p&gt;Our e-commerce platform could consist of:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A web application built with React, responsible for the user experience.&lt;/li&gt;
&lt;li&gt;An ASP.NET Core API, responsible for processing business operations.&lt;/li&gt;
&lt;li&gt;A SQL Server database, used to store products, customers, and orders.&lt;/li&gt;
&lt;li&gt;A message queue, used for asynchronous communication.&lt;/li&gt;
&lt;li&gt;A .NET worker service, responsible for processing certain background tasks.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;External payment and shipping systems are still part of the picture, but now we can see which parts of our platform interact with them.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fx0yv67w1ocuepx27nubw.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fx0yv67w1ocuepx27nubw.png" alt=" " width="800" height="583"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Notice how the questions we're answering begin to change.&lt;/p&gt;

&lt;p&gt;How does the web application communicate with the backend? Which parts of the solution access the database? Is order processing entirely synchronous? Which application sends information to the shipping provider?&lt;/p&gt;

&lt;p&gt;At this level, identifying relevant technologies and protocols makes sense. For example, we might show that the frontend uses HTTPS to communicate with the API, that the API persists information in SQL Server, and that it publishes messages consumed by the worker service.&lt;/p&gt;

&lt;p&gt;These details help us understand the solution's structure without requiring knowledge of the source code.&lt;/p&gt;

&lt;p&gt;C2 is also an excellent tool for discussing architectural responsibilities.&lt;/p&gt;

&lt;p&gt;If several applications access the same database directly, does that introduce coupling worth investigating? If an operation depends on five consecutive synchronous calls, what are the potential consequences for availability?&lt;/p&gt;

&lt;p&gt;The diagram won't automatically answer these questions, but it makes the relationships visible so we can discuss them.&lt;/p&gt;

&lt;p&gt;It's worth emphasizing that &lt;strong&gt;using C4 doesn't mean encouraging distributed architecture&lt;/strong&gt;. A monolithic application can be represented perfectly well using this model.&lt;/p&gt;

&lt;p&gt;The goal is to document the existing or planned architecture, regardless of the architectural style being used.&lt;/p&gt;

&lt;h2&gt;
  
  
  Components: Understanding Internal Responsibilities
&lt;/h2&gt;

&lt;p&gt;The third level, called &lt;strong&gt;C3 or the Component Diagram&lt;/strong&gt;, brings us closer to implementation.&lt;/p&gt;

&lt;p&gt;We now select a specific container and examine how it's organized internally.&lt;/p&gt;

&lt;p&gt;Let's use our platform's API as an example.&lt;/p&gt;

&lt;p&gt;We know it receives purchase requests, validates information, applies business rules, stores orders, and communicates with external services.&lt;/p&gt;

&lt;p&gt;But how are these responsibilities distributed?&lt;/p&gt;

&lt;p&gt;One possible design could organize the application into components such as:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Order API:&lt;/strong&gt; Receives HTTP requests and forwards operations to the appropriate application logic.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Order Processing:&lt;/strong&gt; Coordinates order creation and the execution of the required operations.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Order Domain:&lt;/strong&gt; Contains the business rules and invariants that must be preserved.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Persistence:&lt;/strong&gt; Abstracts the operations required to read and write information.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Payment Integration:&lt;/strong&gt; Encapsulates communication with the external payment provider.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fpbfu72gict2bcet8pgf0.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fpbfu72gict2bcet8pgf0.png" alt=" " width="800" height="583"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;These components represent just one possible organization, not a structure required by C4.&lt;/p&gt;

&lt;p&gt;What's important is understanding that a component represents a group of related functionality encapsulated behind a well-defined interface or responsibility. It doesn't necessarily correspond directly to a class, folder, or project in the repository.&lt;/p&gt;

&lt;p&gt;For example, the component responsible for processing orders might involve several classes working together.&lt;/p&gt;

&lt;p&gt;This is where we can start discussing cohesion, dependencies, and separation of concerns.&lt;/p&gt;

&lt;p&gt;Should a business rule live inside a controller? Is an external integration too tightly coupled to the domain? Can we replace a persistence mechanism without changing the core business logic?&lt;/p&gt;

&lt;p&gt;These questions become much easier to discuss when we can visualize the application's internal relationships.&lt;/p&gt;

&lt;p&gt;It's also important to avoid a common mistake: trying to represent every class in the project in a C3 diagram.&lt;/p&gt;

&lt;p&gt;If the diagram contains dozens of elements without clear organization, it has probably stopped serving its purpose.&lt;/p&gt;

&lt;p&gt;In large systems, creating separate component diagrams for different areas or features is perfectly reasonable.&lt;/p&gt;

&lt;p&gt;Documentation should make complexity easier to understand, not reproduce all that complexity in a single image.&lt;/p&gt;

&lt;h2&gt;
  
  
  Code: When We Need to Examine the Implementation
&lt;/h2&gt;

&lt;p&gt;We've reached &lt;strong&gt;C4 or the Code Diagram&lt;/strong&gt;, the most detailed level of the model.&lt;/p&gt;

&lt;p&gt;Here, we move beyond architectural responsibilities and begin examining concrete implementation elements, such as classes, interfaces, functions, and their relationships.&lt;/p&gt;

&lt;p&gt;Continuing with our example, let's focus on the component responsible for processing orders.&lt;/p&gt;

&lt;p&gt;Imagine it contains a class called &lt;code&gt;CreateOrderHandler&lt;/code&gt;, responsible for coordinating a purchase operation.&lt;/p&gt;

&lt;p&gt;This class depends on an &lt;code&gt;IOrderRepository&lt;/code&gt; interface for persistence and an &lt;code&gt;IPaymentGateway&lt;/code&gt; interface that abstracts the payment integration.&lt;/p&gt;

&lt;p&gt;We also have an &lt;code&gt;Order&lt;/code&gt; entity representing important domain information and behavior.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fj66izpqgw9deifdkw1tf.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fj66izpqgw9deifdkw1tf.png" alt=" " width="800" height="583"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;At this level, we can visualize these dependencies and understand how the implementation is structured.&lt;/p&gt;

&lt;p&gt;This can be especially useful when analyzing components with complex business rules, important algorithms, or relationships that aren't immediately obvious.&lt;/p&gt;

&lt;p&gt;It can also help during refactoring, when we need to evaluate which classes might be affected by a particular change.&lt;/p&gt;

&lt;p&gt;However, there's an important recommendation worth remembering: &lt;strong&gt;the code level is optional&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;There's no need to create class diagrams for every feature we develop.&lt;/p&gt;

&lt;p&gt;In most projects, development tools and static analysis utilities can provide this information directly from the source code.&lt;/p&gt;

&lt;p&gt;Manually maintaining highly detailed diagrams can become difficult, especially when the implementation changes frequently.&lt;/p&gt;

&lt;p&gt;My preference is to reserve this level for situations where a diagram genuinely helps explain a decision or understand a specific problem.&lt;/p&gt;

&lt;p&gt;Otherwise, the code itself, supported by tests and good conventions, is usually a more appropriate source of implementation details.&lt;/p&gt;

&lt;h2&gt;
  
  
  Large-Scale Architecture: Are the Four Levels Enough?
&lt;/h2&gt;

&lt;p&gt;So far, we've followed a relatively straightforward progression: starting with the system from the outside and eventually examining its internal implementation.&lt;/p&gt;

&lt;p&gt;But large-scale systems introduce concerns that aren't fully explained by these four levels alone.&lt;/p&gt;

&lt;p&gt;For example, a Container Diagram might show that an API communicates with a database. That doesn't necessarily explain how many application instances exist, how load balancing works, or what strategies are used for failure recovery.&lt;/p&gt;

&lt;p&gt;Similarly, understanding an application's components doesn't automatically explain the sequence of events that occurs when a customer places an order.&lt;/p&gt;

&lt;p&gt;For this reason, C4 also includes supplementary diagrams.&lt;/p&gt;

&lt;h3&gt;
  
  
  Dynamic Diagrams: Showing How the System Behaves
&lt;/h3&gt;

&lt;p&gt;Dynamic diagrams illustrate how certain elements collaborate during the execution of a feature or use case.&lt;/p&gt;

&lt;p&gt;We could use one to demonstrate the sequence of operations involved in creating an order.&lt;/p&gt;

&lt;p&gt;The application receives the request, validates information, records the order, requests payment, and initiates the following processing steps.&lt;/p&gt;

&lt;p&gt;By visualizing these interactions, we can discuss timeouts, error handling, data consistency, and potential compensating operations.&lt;/p&gt;

&lt;p&gt;This type of representation is especially useful when dealing with asynchronous communication or complex integration flows.&lt;/p&gt;

&lt;h3&gt;
  
  
  Deployment Diagrams: Connecting Architecture and Infrastructure
&lt;/h3&gt;

&lt;p&gt;Deployment Diagrams show how architectural elements are deployed and executed within a particular infrastructure environment.&lt;/p&gt;

&lt;p&gt;We can represent cloud environments, application instances, managed services, databases, and network resources.&lt;/p&gt;

&lt;p&gt;This perspective helps us discuss availability, scalability, redundancy, and environment isolation.&lt;/p&gt;

&lt;p&gt;It's important to understand that a Deployment Diagram doesn't replace C2. They answer different questions.&lt;/p&gt;

&lt;p&gt;While C2 explains which applications and data stores make up the solution, a Deployment Diagram shows where their instances are running.&lt;/p&gt;

&lt;h3&gt;
  
  
  System Landscape Diagrams: Looking Across the Organization
&lt;/h3&gt;

&lt;p&gt;In organizations with dozens or hundreds of applications, a &lt;strong&gt;System Landscape Diagram&lt;/strong&gt; can also be valuable.&lt;/p&gt;

&lt;p&gt;It provides a view of the systems that make up a department or organization without necessarily placing a single system at the center.&lt;/p&gt;

&lt;p&gt;This helps us understand dependencies between platforms, identify critical integrations, and support modernization initiatives.&lt;/p&gt;

&lt;p&gt;In large enterprise environments, this broader perspective can be just as important as the diagrams documenting individual applications.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to Apply C4 Without Creating Bureaucracy
&lt;/h2&gt;

&lt;p&gt;One legitimate concern for any engineering team is the cost of keeping documentation up to date.&lt;/p&gt;

&lt;p&gt;After all, there's little value in producing excellent diagrams at the beginning of a project if they stop reflecting reality after a few releases.&lt;/p&gt;

&lt;p&gt;That's why I recommend starting with what you actually need.&lt;/p&gt;

&lt;p&gt;In many projects, a System Context Diagram and a Container Diagram already provide a useful foundation for architectural discussions and onboarding new team members.&lt;/p&gt;

&lt;p&gt;Component Diagrams can be introduced gradually, particularly for the most important or complex parts of the solution.&lt;/p&gt;

&lt;p&gt;The code level comes into play when there's a specific reason to use it.&lt;/p&gt;

&lt;p&gt;Another valuable practice is keeping documentation close to the development workflow.&lt;/p&gt;

&lt;p&gt;Tools such as &lt;strong&gt;Structurizr DSL&lt;/strong&gt; allow us to describe architectural models using text files, making it easier to version them with Git and review changes.&lt;/p&gt;

&lt;p&gt;This means architectural changes can follow the same review process used for source code.&lt;/p&gt;

&lt;p&gt;I also believe it's important to connect diagrams with &lt;strong&gt;Architecture Decision Records (ADRs)&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Diagrams describe the system's structure and relationships. ADRs preserve the context behind architectural decisions, the alternatives considered, and the reasoning that led to a particular choice.&lt;/p&gt;

&lt;p&gt;Together, these resources help answer two fundamental questions:&lt;/p&gt;

&lt;p&gt;"How is the system organized?"&lt;/p&gt;

&lt;p&gt;"Why did we decide to organize it this way?"&lt;/p&gt;

&lt;p&gt;This combination becomes particularly valuable when a team needs to understand decisions made months or even years earlier.&lt;/p&gt;

&lt;p&gt;Still, no tool can solve the problem of outdated documentation on its own.&lt;/p&gt;

&lt;p&gt;Teams need clear ownership and a process that incorporates architectural documentation into the ongoing evolution of the software.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Makes a Good Diagram Different From a Complicated Drawing?
&lt;/h2&gt;

&lt;p&gt;One of the biggest traps in architecture documentation is assuming that adding more information automatically makes a diagram better.&lt;/p&gt;

&lt;p&gt;In practice, the opposite often happens.&lt;/p&gt;

&lt;p&gt;Imagine presenting an image with forty services, multiple databases, and dozens of overlapping arrows. Even if every element is technically correct, the visualization might be extremely difficult to understand.&lt;/p&gt;

&lt;p&gt;The first thing to consider is the purpose of the diagram.&lt;/p&gt;

&lt;p&gt;A diagram intended to explain payment processing doesn't need to include every service responsible for authentication, notifications, or reporting unless those elements are relevant to the flow being discussed.&lt;/p&gt;

&lt;p&gt;Another important consideration is how we describe relationships.&lt;/p&gt;

&lt;p&gt;An arrow labeled simply "uses" tells us very little. A relationship labeled "publishes order-created event through messaging" communicates something much more useful.&lt;/p&gt;

&lt;p&gt;It's also worth clearly identifying system boundaries, element responsibilities, and technologies whenever they're relevant to the level being presented.&lt;/p&gt;

&lt;p&gt;Consistency across diagrams matters too. If an application has a particular name in C2, it shouldn't suddenly appear under another name in C3 without a clear reason.&lt;/p&gt;

&lt;p&gt;Finally, we should remember that diagrams need to reflect the actual architecture, including limitations and dependencies that might not be ideal.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Architecture documentation shouldn't be a polished fantasy of how the system should work. It should be a tool for understanding how the system actually works and how it can evolve.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The Real Value of C4 Lies in Communication
&lt;/h2&gt;

&lt;p&gt;There's a natural tendency to associate software architecture with sophisticated technical decisions.&lt;/p&gt;

&lt;p&gt;We discuss patterns, platforms, protocols, and technologies. All of these matter, but an architecture also needs to be understandable to the people working with it.&lt;/p&gt;

&lt;p&gt;When we can present a system at different levels of detail, we make conversations easier that might otherwise require long explanations.&lt;/p&gt;

&lt;p&gt;Business stakeholders can understand the solution's fundamental dependencies. New developers can find the components they'll be working on more quickly. Operations and security teams can identify relationships relevant to their analyses.&lt;/p&gt;

&lt;p&gt;And architects gain a shared representation for discussing changes and their consequences.&lt;/p&gt;

&lt;p&gt;In large systems, this clarity helps reduce ambiguity, accelerates understanding, and supports better-informed decisions.&lt;/p&gt;

&lt;p&gt;C4 doesn't eliminate architectural complexity. Its strength lies in helping us organize that complexity into perspectives people can understand.&lt;/p&gt;

&lt;h2&gt;
  
  
  Further Reading and Resources
&lt;/h2&gt;

&lt;p&gt;If you'd like to explore the C4 Model in greater depth, I recommend starting with the official documentation and then experimenting with the model using a system you already know.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://c4model.com/" rel="noopener noreferrer"&gt;C4 Model, Official Website by Simon Brown&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The primary reference for understanding the concepts, abstractions, and different diagram types. I particularly recommend the sections covering containers, components, and supplementary diagrams.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://docs.structurizr.com/" rel="noopener noreferrer"&gt;Structurizr Documentation&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;An excellent resource for anyone interested in architecture as code. The Structurizr DSL tutorial demonstrates how to build models and generate different views from them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://c4model.com/diagrams/checklist" rel="noopener noreferrer"&gt;C4 Model Diagram Review Checklist&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;A practical resource for evaluating whether your diagrams actually communicate what they need to. It can be used during architecture reviews and team discussions.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://adr.github.io/madr/" rel="noopener noreferrer"&gt;Markdown Architectural Decision Records (MADR)&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;A complementary reference for documenting architectural decisions. It helps preserve the reasoning behind the choices represented in your diagrams.&lt;/p&gt;

&lt;p&gt;As a practical exercise, choose an application you know well and try drawing its System Context and Container Diagrams.&lt;/p&gt;

&lt;p&gt;Don't worry about sophisticated tools or visually impressive diagrams at first. Focus on clearly explaining what each element does and how it relates to the others.&lt;/p&gt;

&lt;p&gt;If someone else can understand the solution from those diagrams, you've already made meaningful progress.&lt;/p&gt;

&lt;p&gt;Because ultimately, good architecture documentation isn't about impressing people with the amount of detail it contains.&lt;/p&gt;

&lt;p&gt;It's about helping people understand systems, make decisions, and work better together.&lt;/p&gt;

</description>
      <category>architecture</category>
      <category>c4model</category>
      <category>softwareengineering</category>
      <category>systemdesign</category>
    </item>
    <item>
      <title>Dapper FluentMap Is Back: What Changed from Version 2.0 to 3.6?</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 28 Oct 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/dapper-fluentmap-is-back-what-changed-from-version-20-to-36-em8</link>
      <guid>https://dev.to/rodri-oliveira-dev/dapper-fluentmap-is-back-what-changed-from-version-20-to-36-em8</guid>
      <description>&lt;p&gt;&lt;em&gt;After six years without a new stable release, Dapper FluentMap is actively maintained again. But bringing an existing library back to life involves more than updating dependencies. It means finding a way to move forward without breaking the contracts that existing applications rely on.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Imagine a .NET application that uses Dapper to query a legacy database. In the code, we have a &lt;code&gt;Customer&lt;/code&gt; entity with properties such as &lt;code&gt;Id&lt;/code&gt; and &lt;code&gt;Name&lt;/code&gt;. In the database, the columns follow a different naming convention: &lt;code&gt;customer_id&lt;/code&gt; and &lt;code&gt;customer_name&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Handling this difference is not particularly difficult. We can use SQL aliases, introduce intermediate objects, or configure explicit mappings. All are reasonable approaches, depending on the context.&lt;/p&gt;

&lt;p&gt;The problem becomes more noticeable when these differences spread across dozens of queries and entities. Naming conventions, legacy database structures, and persistence-specific decisions gradually find their way into the application code.&lt;/p&gt;

&lt;p&gt;Dapper FluentMap was originally created to address this kind of problem: mapping .NET properties to database columns without introducing persistence attributes into domain entities.&lt;/p&gt;

&lt;p&gt;In August 2020, version 2.0.0 was released, updating its integration with Dapper 2.0.35 and Dommel 2.0. After that, the project went through a long period without new stable releases.&lt;/p&gt;

&lt;p&gt;In 2026, I took over its maintenance.&lt;/p&gt;

&lt;p&gt;The first question wasn't how many features could be added. It was how to evolve an established library without disrupting applications that might still depend on it.&lt;/p&gt;

&lt;p&gt;Today, with version 3.6.0, released on October 13, 2026, FluentMap retains its original purpose while introducing capabilities that were not available in the 2.x line.&lt;/p&gt;

&lt;h2&gt;
  
  
  The First Decision: Preserve What Already Worked
&lt;/h2&gt;

&lt;p&gt;A general-purpose library carries a different kind of responsibility than an application maintained by a single team.&lt;/p&gt;

&lt;p&gt;When we change an application, we usually know its consumers and can coordinate a migration. With a public library, we don't necessarily know how many projects depend on a particular behavior or which architectural decisions were made around it.&lt;/p&gt;

&lt;p&gt;For that reason, I see compatibility as an architectural requirement, not merely a versioning concern.&lt;/p&gt;

&lt;p&gt;In FluentMap, the traditional configuration model remains available:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Customer&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Name&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Empty&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CustomerMap&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;EntityMap&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Customer&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nf"&gt;CustomerMap&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;Map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;ToColumn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"customer_id"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="nf"&gt;Map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;ToColumn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"customer_name"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Registration remains familiar:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;FluentMapper&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Initialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;config&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;AddMap&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;CustomerMap&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;();&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="n"&gt;FluentMapper&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Validate&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And queries still use Dapper directly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;customer&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;QuerySingle&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Customer&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;(&lt;/span&gt;
    &lt;span class="s"&gt;"SELECT customer_id, customer_name FROM customers WHERE customer_id = @Id"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;10&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;FluentMap establishes the relationship between column names and entity properties. SQL execution, connection management, and basic materialization remain Dapper's responsibility.&lt;/p&gt;

&lt;p&gt;Internally, this integration relies on Dapper's type-mapping mechanism, connected to FluentMap's global configuration.&lt;/p&gt;

&lt;p&gt;That behavior has been preserved in the 3.x line.&lt;/p&gt;

&lt;p&gt;For applications using only traditional mappings, upgrading generally does not require rewriting entities or replacing existing query calls. This does not mean unrestricted compatibility: dependency versions and integration scenarios still need to be validated.&lt;/p&gt;

&lt;p&gt;The evolution also does not turn FluentMap into a full ORM. It does not introduce entity tracking, migration management, or generic CRUD generation in the core package.&lt;/p&gt;

&lt;p&gt;The goal remains to complement Dapper, not replace it.&lt;/p&gt;

&lt;h2&gt;
  
  
  When Property Mapping Is No Longer Enough
&lt;/h2&gt;

&lt;p&gt;Mapping a database column to a property solves many problems, but domain models are not always made up of simple scalar properties.&lt;/p&gt;

&lt;p&gt;In applications following Domain-Driven Design, for example, value objects, nested properties, and immutable entities are common. There are also situations where the same entity needs to be materialized from queries with different result shapes.&lt;/p&gt;

&lt;p&gt;FluentMap 3.x introduces specific mechanisms for these scenarios.&lt;/p&gt;

&lt;p&gt;An entity can now map a nested property:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CustomerMap&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;EntityMap&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Customer&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nf"&gt;CustomerMap&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;Map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Address&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;City&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;ToColumn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"city"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To materialize that path, we use one of FluentMap's dedicated query APIs:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;customer&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;QueryMappedSingle&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Customer&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;(&lt;/span&gt;
    &lt;span class="s"&gt;"SELECT 'Sao Paulo' AS city"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This distinction matters.&lt;/p&gt;

&lt;p&gt;Registering a nested mapping does not automatically make every standard Dapper query capable of constructing complex object structures. The functionality depends on using the appropriate materialization path.&lt;/p&gt;

&lt;p&gt;Beyond nested objects, the 3.x line introduces mapping profiles, property converters, and explicit construction strategies through &lt;code&gt;ConstructUsing(...)&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Mapping profiles allow an entity to support different query result shapes. Property converters handle transformations between database values and model properties. Explicit construction provides an alternative when automatic constructor selection does not meet an entity's requirements.&lt;/p&gt;

&lt;p&gt;These features expand the available modeling options, but they also introduce decisions that developers need to make deliberately.&lt;/p&gt;

&lt;p&gt;A Dapper &lt;code&gt;TypeHandler&amp;lt;T&amp;gt;&lt;/code&gt;, for example, remains a good choice when a type has a consistent scalar representation throughout an application. There is little reason to replace it with a property-specific converter if the existing mechanism already solves the problem correctly.&lt;/p&gt;

&lt;p&gt;This is a principle I try to preserve: a new capability does not automatically make an existing approach obsolete.&lt;/p&gt;

&lt;h2&gt;
  
  
  Global Configuration and Isolation: Two Execution Models
&lt;/h2&gt;

&lt;p&gt;Another important part of FluentMap's evolution concerns configuration.&lt;/p&gt;

&lt;p&gt;Historically, &lt;code&gt;FluentMapper.Initialize(...)&lt;/code&gt; established a global configuration. This model is straightforward and remains suitable for applications with a single set of mappings.&lt;/p&gt;

&lt;p&gt;However, global configuration requires attention in parallel tests, applications with multiple contexts, and scenarios where the same entity may need different mapping definitions.&lt;/p&gt;

&lt;p&gt;The 3.x line introduces immutable configuration and isolated &lt;code&gt;FluentMapRuntime&lt;/code&gt; instances:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;runtime&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;FluentMapConfigurationBuilder&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;AddMap&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;CustomerMap&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Build&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CreateRuntime&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;customer&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;runtime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;QueryMappedSingle&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Customer&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;(&lt;/span&gt;
    &lt;span class="n"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;sql&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In this model, the configuration belongs to the runtime instance used to execute the query.&lt;/p&gt;

&lt;p&gt;A separate package, &lt;code&gt;FluentMap.DependencyInjection&lt;/code&gt;, also provides integration with .NET's dependency injection container.&lt;/p&gt;

&lt;p&gt;But there is an important boundary: isolation applies to materialization APIs controlled by FluentMap.&lt;/p&gt;

&lt;p&gt;Standard &lt;code&gt;Dapper.Query&amp;lt;T&amp;gt;()&lt;/code&gt; calls continue to use Dapper's globally registered type maps, while Dommel integration remains associated with global configuration.&lt;/p&gt;

&lt;p&gt;In other words, introducing dependency injection does not automatically eliminate global state from an application.&lt;/p&gt;

&lt;p&gt;Choosing between these models depends on the need for isolation. For a straightforward application, keeping the traditional configuration may result in lower maintenance overhead. For scenarios requiring independent mapping configurations, an isolated runtime provides greater control.&lt;/p&gt;

&lt;h2&gt;
  
  
  Moving Some Work from Runtime to Compile Time
&lt;/h2&gt;

&lt;p&gt;One of the most interesting changes was introducing capabilities that operate during compilation.&lt;/p&gt;

&lt;p&gt;FluentMap now provides two additional packages: &lt;code&gt;FluentMap.Analyzers&lt;/code&gt; and &lt;code&gt;FluentMap.Generators&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Roslyn Analyzers identify certain configuration problems before the application runs. This helps detect mistakes that might otherwise surface only during initialization or query materialization.&lt;/p&gt;

&lt;p&gt;Source Generators provide generated mapping registration and materializers for supported scenarios.&lt;/p&gt;

&lt;p&gt;The architectural difference is that some work can move from runtime mechanisms into the compilation process, reducing dependence on reflection in those paths.&lt;/p&gt;

&lt;p&gt;This approach also made strict generated materialization possible. Instead of silently falling back to reflection-based materialization, strict mode rejects unsupported result shapes and configurations.&lt;/p&gt;

&lt;p&gt;There are potential benefits in predictability, diagnostics, and reducing reflection usage. However, it would be premature to claim that generated code makes every query faster.&lt;/p&gt;

&lt;p&gt;Performance depends on result shapes, data volumes, ADO.NET providers, and application characteristics. Improvements should be assessed through representative benchmarks, not assumed simply because code generation is involved.&lt;/p&gt;

&lt;p&gt;Similarly, although the project includes tests for specific Native AOT scenarios, version 3.6.0 does not claim full Native AOT compatibility. Reflection-based registration and other dynamic paths still have documented limitations.&lt;/p&gt;

&lt;h2&gt;
  
  
  Dommel and the Meaning of Persistence Operations
&lt;/h2&gt;

&lt;p&gt;The integration with Dommel has evolved as well.&lt;/p&gt;

&lt;p&gt;In the historical version, &lt;code&gt;Ignore()&lt;/code&gt; could end up being used as a workaround to prevent certain properties from being written to the database.&lt;/p&gt;

&lt;p&gt;However, excluding a property from mapping is not the same as declaring that it can be read but should not participate in an &lt;code&gt;INSERT&lt;/code&gt; or &lt;code&gt;UPDATE&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The current version distinguishes these cases through dedicated persistence metadata:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="nf"&gt;Map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;CreatedAt&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToColumn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"created_at"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;DatabaseDefaultOnInsert&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="nf"&gt;Map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UpdatedAt&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToColumn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"updated_at"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ReadOnly&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="nf"&gt;Map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Total&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToColumn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"total"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Computed&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It is now possible to express whether a column has a database-generated default, is computed, or must be excluded from write operations.&lt;/p&gt;

&lt;p&gt;Version 3.5.0 also introduced &lt;code&gt;InsertMapped*&lt;/code&gt; and &lt;code&gt;UpdateMapped*&lt;/code&gt; operations, which can apply property converters during persistence.&lt;/p&gt;

&lt;p&gt;These operations are opt-in and do not automatically change the behavior of traditional Dommel calls.&lt;/p&gt;

&lt;p&gt;For applications migrating from earlier versions, this is an area that deserves particular attention. A query returning the expected data does not prove that inserts and updates still behave correctly.&lt;/p&gt;

&lt;h2&gt;
  
  
  Compatibility Needs Evidence, Not Assumptions
&lt;/h2&gt;

&lt;p&gt;A recurring challenge with libraries built on ADO.NET is defining what compatibility with a database actually means.&lt;/p&gt;

&lt;p&gt;The fact that Dapper works with a particular provider does not automatically mean that every additional feature offered by another library has been validated against that provider.&lt;/p&gt;

&lt;p&gt;In version 3.6.0, FluentMap introduced documented compatibility levels supported by mandatory integration tests against real database instances.&lt;/p&gt;

&lt;p&gt;SQLite, SQL Server, PostgreSQL, MySQL, and MariaDB have certified coverage for both FluentMap Core and Dommel integration.&lt;/p&gt;

&lt;p&gt;Oracle and Firebird have Core certification, but not Dommel certification.&lt;/p&gt;

&lt;p&gt;SQL Server Compact Edition remains classified as a legacy integration without modern certification.&lt;/p&gt;

&lt;p&gt;This separation helps prevent an expectation of compatibility from becoming a guarantee that testing cannot support.&lt;/p&gt;

&lt;p&gt;The compatibility matrix also identifies the specific database and provider versions used during validation.&lt;/p&gt;

&lt;p&gt;The current packages declare support for Dapper versions starting at 2.1.79 and below 3.0.0. For Dommel, the supported range starts at 3.5.3 and remains below 4.0.0.&lt;/p&gt;

&lt;p&gt;Distributed packages continue to target &lt;code&gt;.NET Standard 2.0&lt;/code&gt;, preserving compatibility with a broad range of consuming applications.&lt;/p&gt;

&lt;p&gt;Beyond functional tests, project maintenance now includes public API compatibility checks, static analysis, code coverage, release artifacts, and automated compatibility validation.&lt;/p&gt;

&lt;p&gt;I don't consider these secondary activities.&lt;/p&gt;

&lt;p&gt;For an open-source library, the release process and the ability to detect regressions are part of the reliability we provide to consumers.&lt;/p&gt;

&lt;h2&gt;
  
  
  Should You Upgrade from Version 2.0?
&lt;/h2&gt;

&lt;p&gt;For applications still using FluentMap 2.0.0, my recommendation is to start with existing behavior rather than the new features.&lt;/p&gt;

&lt;p&gt;First, identify how mappings are registered, which Dapper and Dommel versions are installed, and whether any integrations depend on specific behaviors.&lt;/p&gt;

&lt;p&gt;Then update FluentMap packages to the same release version, build the application, validate mappings, and run the test suite.&lt;/p&gt;

&lt;p&gt;If Dommel is involved, pay particular attention to write operations, generated keys, database defaults, and ignored properties. Configuration combinations previously accepted may also produce validation errors in the newer version.&lt;/p&gt;

&lt;p&gt;Binary compatibility deserves attention too. The Dommel integration has differences in its public API, so full binary compatibility with the historical 2.0.0 package should not be assumed.&lt;/p&gt;

&lt;p&gt;Only after validating the existing application would I consider adopting features such as isolated runtimes, advanced materialization, or Source Generators.&lt;/p&gt;

&lt;p&gt;A successful migration does not require using every available feature.&lt;/p&gt;

&lt;p&gt;In many cases, the best decision is simply to upgrade the library while leaving most application code unchanged.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Bringing FluentMap Back Means
&lt;/h2&gt;

&lt;p&gt;Between versions 2.0.0 and 3.6.0, FluentMap went from a library whose maintenance had effectively stopped to a project with active development, new capabilities, documentation, compatibility testing, and an established release process.&lt;/p&gt;

&lt;p&gt;But the most important aspect, in my view, is not the number of features added.&lt;/p&gt;

&lt;p&gt;It is the ability to keep using a familiar abstraction without forcing existing applications to change how they work, while giving new projects access to mechanisms better suited to their requirements.&lt;/p&gt;

&lt;p&gt;Maintaining open-source software means balancing two responsibilities that often pull in different directions: preserving what consumers already depend on and allowing the project to evolve.&lt;/p&gt;

&lt;p&gt;For FluentMap, the approach has been to preserve the historical API as the compatibility path and introduce most new behaviors as optional capabilities.&lt;/p&gt;

&lt;p&gt;There are still limitations, particularly around global integration isolation and Native AOT support. They are part of the current contract and should remain explicit.&lt;/p&gt;

&lt;p&gt;To me, this is one of the most important measures of a library's evolution: not simply offering more possibilities, but helping consumers understand its contracts, limitations, and the consequences of their choices.&lt;/p&gt;

&lt;p&gt;FluentMap is actively maintained again. And for developers working with Dapper, version 3.6.0 offers new options without requiring them to rewrite what already works.&lt;/p&gt;




&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap" rel="noopener noreferrer"&gt;Dapper FluentMap: GitHub Repository&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/compare/v2.0.0...v3.6.0" rel="noopener noreferrer"&gt;Full Code Comparison: v2.0.0 to v3.6.0&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/releases/tag/v2.0.0" rel="noopener noreferrer"&gt;Version 2.0.0 Release&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/releases/tag/v3.6.0" rel="noopener noreferrer"&gt;Version 3.6.0 Release&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/blob/v3.6.0/MIGRATION.md" rel="noopener noreferrer"&gt;Migration Guide: 2.x to 3.x&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/blob/v3.6.0/COMPATIBILITY.md" rel="noopener noreferrer"&gt;Compatibility Matrix and Known Limitations&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>dotnet</category>
      <category>dapper</category>
      <category>open</category>
      <category>opensource</category>
    </item>
    <item>
      <title>Architecture Decisions Shouldn't Get Lost: Introducing ADR Guard for VS Code</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 21 Oct 2026 14:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/architecture-decisions-shouldnt-get-lost-introducing-adr-guard-for-vs-code-3211</link>
      <guid>https://dev.to/rodri-oliveira-dev/architecture-decisions-shouldnt-get-lost-introducing-adr-guard-for-vs-code-3211</guid>
      <description>&lt;p&gt;There's a question almost every developer has asked while working on a mature codebase:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"Why was it built this way?"&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Sometimes the answer is buried in an old GitHub discussion. Other times, it's hidden in a Slack thread, an outdated document, or, even worse, in the memory of someone who left the company two years ago.&lt;/p&gt;

&lt;p&gt;The code tells us &lt;em&gt;how&lt;/em&gt; something was implemented. It rarely tells us &lt;em&gt;why&lt;/em&gt; a particular approach was chosen, what alternatives were considered, or which constraints influenced the decision.&lt;/p&gt;

&lt;p&gt;And that's a problem.&lt;/p&gt;

&lt;p&gt;As software engineers, we spend considerable time reviewing code, writing tests, and maintaining documentation. Yet the reasoning behind some of our most important technical decisions often disappears over time.&lt;/p&gt;

&lt;p&gt;This is one of the problems I wanted to address when I started building &lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard&lt;/a&gt;, an open-source tool focused on Architecture Decision Records (ADRs).&lt;/p&gt;

&lt;p&gt;More recently, I've been working on bringing that experience directly into Visual Studio Code.&lt;/p&gt;

&lt;p&gt;But before discussing the extension, it's worth looking at why architectural decisions deserve more attention in the first place.&lt;/p&gt;

&lt;h2&gt;
  
  
  Architecture Decisions Are Part of Your System's History
&lt;/h2&gt;

&lt;p&gt;An Architecture Decision Record is a document that captures an important architectural decision, including its context, the approach selected, and its consequences.&lt;/p&gt;

&lt;p&gt;The concept is straightforward.&lt;/p&gt;

&lt;p&gt;Imagine your team decides to move from synchronous communication between services to an event-driven architecture.&lt;/p&gt;

&lt;p&gt;At that moment, everyone probably understands why.&lt;/p&gt;

&lt;p&gt;Perhaps you need better resilience. Maybe your services have become too tightly coupled. Or perhaps you're dealing with scalability requirements that the current design cannot comfortably support.&lt;/p&gt;

&lt;p&gt;Now imagine someone revisiting that decision two years later.&lt;/p&gt;

&lt;p&gt;The system has evolved. The team has changed. New technologies are available, and the original constraints may no longer exist.&lt;/p&gt;

&lt;p&gt;Without an ADR, that developer needs to reconstruct the reasoning behind the decision.&lt;/p&gt;

&lt;p&gt;With an ADR, they have a starting point.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;An ADR isn't meant to prevent architectural decisions from changing. It's meant to make those changes informed and intentional.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Good architecture isn't about making decisions that last forever. It's about understanding the trade-offs we accept and knowing when it's time to revisit them.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Real Challenge Isn't Writing ADRs
&lt;/h2&gt;

&lt;p&gt;I've noticed that adopting ADRs is often easier than maintaining the practice.&lt;/p&gt;

&lt;p&gt;Initially, everything looks promising.&lt;/p&gt;

&lt;p&gt;The team creates a &lt;code&gt;docs/adr&lt;/code&gt; directory, agrees on a template, and starts documenting important decisions alongside the source code.&lt;/p&gt;

&lt;p&gt;A few months later, inconsistencies begin to appear.&lt;/p&gt;

&lt;p&gt;Some documents are missing essential sections. Others use different formats. Certain decisions are never updated, even after significant architectural changes.&lt;/p&gt;

&lt;p&gt;Eventually, ADRs risk becoming another collection of Markdown files that nobody remembers to consult.&lt;/p&gt;

&lt;p&gt;I don't think the problem is necessarily a lack of discipline.&lt;/p&gt;

&lt;p&gt;The problem is that we sometimes introduce documentation practices without considering the developer experience around them.&lt;/p&gt;

&lt;p&gt;If creating, finding, editing, and validating architectural decisions requires too much effort, the practice becomes increasingly difficult to sustain.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Documentation needs to fit into the development workflow, not compete with it.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;That idea became an important part of the ADR Guard project.&lt;/p&gt;

&lt;h2&gt;
  
  
  ADR Guard: Bringing Structure to Architectural Decisions
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard&lt;/a&gt; is an open-source tool built with .NET to help teams manage Architecture Decision Records throughout their lifecycle.&lt;/p&gt;

&lt;p&gt;It doesn't attempt to replace Markdown or introduce a proprietary documentation platform.&lt;/p&gt;

&lt;p&gt;ADRs remain regular files in your repository, which means they can be versioned, reviewed through pull requests, and maintained alongside the code they describe.&lt;/p&gt;

&lt;p&gt;The CLI supports workflows such as creating records, validating their structure, organizing documentation, and performing incremental checks.&lt;/p&gt;

&lt;p&gt;It also supports different ADR formats, including canonical ADRs and MADR 4.0.&lt;/p&gt;

&lt;p&gt;The goal is to make architectural documentation more consistent and easier to maintain.&lt;/p&gt;

&lt;p&gt;For example, structural validation can identify documents that don't follow the expected format. Teams can also use baselines and automated checks to introduce governance incrementally instead of requiring an entire repository to become compliant overnight.&lt;/p&gt;

&lt;p&gt;These capabilities can be integrated into CI/CD workflows, making documentation quality part of the development process.&lt;/p&gt;

&lt;p&gt;There is, however, an important distinction.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Validating an ADR doesn't mean approving the architectural decision itself.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;A tool can verify structure, required sections, and documented conventions. It cannot replace engineering judgment, architectural discussions, or technical reviews.&lt;/p&gt;

&lt;p&gt;And it shouldn't try to.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bringing ADRs Into Visual Studio Code
&lt;/h2&gt;

&lt;p&gt;While the CLI provides the foundation, I wanted to reduce the friction involved in everyday ADR management.&lt;/p&gt;

&lt;p&gt;Most developers already spend a significant portion of their day inside their editor.&lt;/p&gt;

&lt;p&gt;So why should working with architectural decisions require a completely separate experience?&lt;/p&gt;

&lt;p&gt;That's where &lt;strong&gt;ADR Guard for VS Code&lt;/strong&gt; comes in.&lt;/p&gt;

&lt;p&gt;The extension provides a visual interface for common ADR workflows while relying on the existing ADR Guard CLI for the underlying operations.&lt;/p&gt;

&lt;p&gt;This separation is intentional: the same core behavior can be used from the terminal, VS Code, or automation pipelines.&lt;/p&gt;

&lt;h3&gt;
  
  
  Finding Architectural Decisions Without Searching Through Folders
&lt;/h3&gt;

&lt;p&gt;One of the first improvements is discoverability.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fh9ib248q9wg2jq3bjgqo.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fh9ib248q9wg2jq3bjgqo.png" alt="ADR Guard for VS Code showing the visual list of Architecture Decision Records" width="800" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The ADR Guard visual dashboard provides direct access to architectural decisions and their metadata.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Instead of manually browsing Markdown files, developers can use a visual list displaying information such as ADR identifiers, titles, statuses, and file locations.&lt;/p&gt;

&lt;p&gt;The interface supports searching, filtering by status, sorting, and opening documents directly in the editor.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmb0e2gk2irfs0ah2nqxd.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmb0e2gk2irfs0ah2nqxd.png" alt="ADR Guard search and status filtering in Visual Studio Code" width="800" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Searching and filtering ADRs makes architectural context easier to discover.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;There's also an ADR Explorer integrated into VS Code, providing another way to navigate records and recognized relationships.&lt;/p&gt;

&lt;p&gt;These features might sound simple, but I believe discoverability has a direct impact on whether documentation is actually used.&lt;/p&gt;

&lt;p&gt;A decision that's easy to find is much more likely to influence future engineering discussions.&lt;/p&gt;

&lt;h3&gt;
  
  
  Creating ADRs Without Memorizing Templates
&lt;/h3&gt;

&lt;p&gt;Another area I wanted to improve was ADR creation.&lt;/p&gt;

&lt;p&gt;Markdown is a great format for technical documentation, but asking every developer to remember the structure of every supported template introduces unnecessary friction.&lt;/p&gt;

&lt;p&gt;The extension provides a visual creation form that helps guide the process.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F86z9ajxl2d2qjwf5cwx4.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F86z9ajxl2d2qjwf5cwx4.png" alt="Creating an Architecture Decision Record using the ADR Guard Minimal template" width="800" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The Minimal template focuses on the essential elements of an architectural decision.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;With the Minimal template, developers can focus on three fundamental questions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;What is the context?&lt;/li&gt;
&lt;li&gt;What decision are we making?&lt;/li&gt;
&lt;li&gt;What are the consequences?&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For decisions requiring more detailed analysis, the Extended template includes additional fields, such as decision drivers, alternatives considered, rationale, risks, and references.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhdyrhwd5sr3xidstt7za.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhdyrhwd5sr3xidstt7za.png" alt="ADR Guard Extended ADR template with additional architectural decision fields" width="800" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The Extended template helps capture more detailed architectural reasoning and trade-offs.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The extension also supports a Markdown preview before creating the document.&lt;/p&gt;

&lt;p&gt;The point isn't to automate architectural thinking. It's to remove repetitive tasks so developers can focus on explaining their decisions clearly.&lt;/p&gt;

&lt;h3&gt;
  
  
  Editing Existing Decisions Safely
&lt;/h3&gt;

&lt;p&gt;Architectural decisions evolve, and documentation needs to reflect that.&lt;/p&gt;

&lt;p&gt;The extension provides visual editing for compatible ADR documents, allowing developers to update their content without manually navigating every Markdown section.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjtodaqymg9kamz373h5w.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjtodaqymg9kamz373h5w.png" alt="Editing an existing Architecture Decision Record in ADR Guard for VS Code" width="800" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Existing ADRs can be edited through a structured interface inside VS Code.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;One detail I consider particularly important is how the extension handles external modifications.&lt;/p&gt;

&lt;p&gt;If an ADR changes after being loaded into the editing form, the extension detects the conflict and prevents an outdated version from silently overwriting the newer content.&lt;/p&gt;

&lt;p&gt;This is especially relevant in collaborative repositories where multiple developers may be working on the same documentation.&lt;/p&gt;

&lt;p&gt;The goal is to provide convenience without sacrificing predictability or data integrity.&lt;/p&gt;

&lt;h3&gt;
  
  
  Making Validation Part of the Development Workflow
&lt;/h3&gt;

&lt;p&gt;Another useful capability is integration with VS Code's &lt;strong&gt;Problems&lt;/strong&gt; panel.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhjiwvgv0gshq5r4tlr89.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhjiwvgv0gshq5r4tlr89.png" alt="ADR Guard validation diagnostics displayed in the VS Code Problems panel" width="800" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;ADR validation findings appear alongside other development diagnostics in VS Code.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;When an ADR violates a supported structural rule, developers can see the corresponding diagnostic without leaving the editor.&lt;/p&gt;

&lt;p&gt;Validation can run explicitly, and automatic validation on save is available as an opt-in setting.&lt;/p&gt;

&lt;p&gt;The extension also provides workflows for validating changed ADRs against a local Git reference and checking findings against an existing baseline.&lt;/p&gt;

&lt;p&gt;I see this as a useful step toward making architectural documentation part of ordinary engineering feedback loops.&lt;/p&gt;

&lt;p&gt;We already expect immediate feedback when code violates certain rules. Having similar visibility for ADR structure can help teams maintain documentation standards without relying entirely on manual inspections.&lt;/p&gt;

&lt;p&gt;Of course, structural consistency isn't the same thing as architectural correctness. Human review remains essential.&lt;/p&gt;

&lt;h2&gt;
  
  
  Architecture Governance Shouldn't Become Another Source of Friction
&lt;/h2&gt;

&lt;p&gt;One concern I've had throughout this project is avoiding unnecessary complexity.&lt;/p&gt;

&lt;p&gt;It's easy to introduce tools and processes in the name of governance, only to make developers' lives harder.&lt;/p&gt;

&lt;p&gt;I believe architecture governance works best when its purpose is clear and its mechanisms are predictable.&lt;/p&gt;

&lt;p&gt;That's why the VS Code extension is designed as a user interface over the existing CLI rather than a separate implementation of ADR rules.&lt;/p&gt;

&lt;p&gt;It also avoids silently modifying architectural documents during ordinary navigation or validation.&lt;/p&gt;

&lt;p&gt;The developer remains responsible for deciding when records should be created or changed.&lt;/p&gt;

&lt;p&gt;To me, this is an important principle: &lt;strong&gt;good engineering tools should support deliberate decisions, not hide consequential actions behind convenience.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Not Every Technical Decision Needs an ADR
&lt;/h2&gt;

&lt;p&gt;I don't believe every implementation detail should become an architectural record.&lt;/p&gt;

&lt;p&gt;That would create unnecessary bureaucracy and eventually reduce the value of the documentation.&lt;/p&gt;

&lt;p&gt;ADRs are most useful for decisions that affect the system's structure, establish long-term technical constraints, introduce important dependencies, or involve meaningful trade-offs.&lt;/p&gt;

&lt;p&gt;Choosing between two local variable names probably doesn't need an ADR.&lt;/p&gt;

&lt;p&gt;Deciding how services communicate, how data ownership is defined, or why a particular persistence strategy was adopted probably deserves one.&lt;/p&gt;

&lt;p&gt;The objective isn't to produce more documentation.&lt;/p&gt;

&lt;p&gt;It's to preserve the context that future engineers will need to make good decisions.&lt;/p&gt;

&lt;h2&gt;
  
  
  Final Thoughts
&lt;/h2&gt;

&lt;p&gt;Building ADR Guard has reinforced something I strongly believe about software architecture:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The quality of an architecture depends not only on the decisions we make, but also on our ability to understand and revisit those decisions over time.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;An ADR won't solve architectural problems by itself.&lt;/p&gt;

&lt;p&gt;But it can preserve valuable engineering context, make trade-offs visible, and provide a foundation for better technical discussions.&lt;/p&gt;

&lt;p&gt;ADR Guard for VS Code is one more step toward making that practice easier to adopt and maintain.&lt;/p&gt;

&lt;p&gt;The project is open source and continues to evolve. If you work with software architecture, technical leadership, or long-lived systems, I'd be interested in hearing how your team handles architectural decisions.&lt;/p&gt;

&lt;p&gt;Do you use ADRs today? And if so, what's been the biggest challenge in keeping them useful?&lt;/p&gt;




&lt;h2&gt;
  
  
  Try ADR Guard
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://marketplace.visualstudio.com/items?itemName=rodrioliveira.adr-guard" rel="noopener noreferrer"&gt;Install ADR Guard for VS Code&lt;/a&gt;&lt;/strong&gt; — Get the extension from the Visual Studio Marketplace.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://rodri-oliveira-dev.github.io/adr-guard/product/vscode-visual-guide/" rel="noopener noreferrer"&gt;Official VS Code Visual Guide&lt;/a&gt;&lt;/strong&gt; — Explore the interface, screenshots, and supported workflows.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard on GitHub&lt;/a&gt;&lt;/strong&gt; — Explore the source code, report issues, or contribute.&lt;/p&gt;

&lt;p&gt;The VS Code extension uses the ADR Guard CLI, which must be installed separately. Check the official documentation for installation, compatibility, and configuration details.&lt;/p&gt;

</description>
      <category>architecture</category>
      <category>vscode</category>
      <category>opensource</category>
      <category>adr</category>
    </item>
    <item>
      <title>GitHub Dotfiles: Treating Your Development Environment Like Code</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 14 Oct 2026 14:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/github-dotfiles-treating-your-development-environment-like-code-2a04</link>
      <guid>https://dev.to/rodri-oliveira-dev/github-dotfiles-treating-your-development-environment-like-code-2a04</guid>
      <description>&lt;p&gt;Most developers eventually accumulate a collection of small configuration files, aliases, scripts, shell functions, and Git preferences that make their daily work a little more comfortable.&lt;/p&gt;

&lt;p&gt;At first, they usually live directly inside &lt;code&gt;~/.bashrc&lt;/code&gt;, &lt;code&gt;~/.gitconfig&lt;/code&gt;, random folders under &lt;code&gt;~/scripts&lt;/code&gt;, or maybe inside a note called something like &lt;em&gt;“things to install on a new machine”&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;That works surprisingly well — until you change computers.&lt;/p&gt;

&lt;p&gt;Or start using GitHub Codespaces.&lt;/p&gt;

&lt;p&gt;Or reinstall Linux.&lt;/p&gt;

&lt;p&gt;Or realize that the alias you depend on every day exists on one machine but not another.&lt;/p&gt;

&lt;p&gt;That is where &lt;strong&gt;dotfiles&lt;/strong&gt; become interesting.&lt;/p&gt;

&lt;p&gt;I maintain my development environment in a GitHub repository called &lt;a href="https://github.com/rodri-oliveira-dev/dotfiles" rel="noopener noreferrer"&gt;dotfiles&lt;/a&gt;. What started as a way to keep a few preferences synchronized gradually became something more useful: a reproducible, testable, and intentionally limited development environment for Git, Bash, .NET, and GitHub Codespaces.&lt;/p&gt;

&lt;p&gt;The important part isn't the aliases themselves.&lt;/p&gt;

&lt;p&gt;The interesting part is treating your personal development environment with some of the same engineering practices you would use in a production repository.&lt;/p&gt;

&lt;h2&gt;
  
  
  Dotfiles are configuration as code
&lt;/h2&gt;

&lt;p&gt;On Unix-like systems, configuration files commonly start with a dot: &lt;code&gt;.bashrc&lt;/code&gt;, &lt;code&gt;.gitconfig&lt;/code&gt;, &lt;code&gt;.vimrc&lt;/code&gt;, and so on. Because they are hidden by default, they became known collectively as &lt;em&gt;dotfiles&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;Putting them in Git gives you some immediate advantages.&lt;/p&gt;

&lt;p&gt;You get history. You can understand why a configuration changed.&lt;/p&gt;

&lt;p&gt;You get portability. A new environment can start from a known baseline instead of being rebuilt from memory.&lt;/p&gt;

&lt;p&gt;And you get rollback. When an experiment with your shell configuration goes badly, &lt;code&gt;git diff&lt;/code&gt; is a much nicer debugging tool than trying to remember what the file looked like yesterday.&lt;/p&gt;

&lt;p&gt;But versioning dotfiles is only the first step.&lt;/p&gt;

&lt;p&gt;The bigger question is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;What actually belongs in a personal environment repository?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That boundary turned out to be one of the most important design decisions in my setup.&lt;/p&gt;

&lt;h2&gt;
  
  
  Your dotfiles should not own your projects
&lt;/h2&gt;

&lt;p&gt;My repository deliberately manages &lt;strong&gt;developer-level preferences&lt;/strong&gt;, not project dependencies.&lt;/p&gt;

&lt;p&gt;For example, Git behavior and shell aliases belong to the dotfiles repository. A project's .NET SDK version does not.&lt;/p&gt;

&lt;p&gt;If a repository requires a particular .NET SDK, that decision belongs in its &lt;code&gt;global.json&lt;/code&gt;. NuGet package versions belong in project files or &lt;code&gt;Directory.Packages.props&lt;/code&gt;. Local .NET tools belong in &lt;code&gt;.config/dotnet-tools.json&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The same principle applies to the editor. A project may recommend VS Code extensions through &lt;code&gt;.vscode/extensions.json&lt;/code&gt;, while personal editor preferences can remain in VS Code Settings Sync.&lt;/p&gt;

&lt;p&gt;This separation prevents a surprisingly common problem: your personal workstation configuration slowly becoming an undocumented dependency of the applications you build.&lt;/p&gt;

&lt;p&gt;A project should still describe how it wants to be built when another developer clones it.&lt;/p&gt;

&lt;p&gt;Your dotfiles should make &lt;strong&gt;you&lt;/strong&gt; more productive while respecting that contract.&lt;/p&gt;

&lt;h2&gt;
  
  
  A safe installer is more important than a clever installer
&lt;/h2&gt;

&lt;p&gt;The entry point of the repository is intentionally boring:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/rodri-oliveira-dev/dotfiles.git &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$HOME&lt;/span&gt;&lt;span class="s2"&gt;/dotfiles"&lt;/span&gt;
&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$HOME&lt;/span&gt;&lt;span class="s2"&gt;/dotfiles"&lt;/span&gt;
./install.sh
&lt;span class="nb"&gt;source&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$HOME&lt;/span&gt;&lt;span class="s2"&gt;/.bashrc"&lt;/span&gt;
dotfiles-doctor
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The interesting work happens behind &lt;code&gt;install.sh&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Instead of replacing the entire &lt;code&gt;~/.bashrc&lt;/code&gt;, the installer adds a clearly delimited managed block. That block loads the repository's shell fragments and makes &lt;code&gt;~/.local/bin&lt;/code&gt; available through &lt;code&gt;PATH&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The actual managed configuration lives under:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;${XDG_CONFIG_HOME:-$HOME/.config}/rodri-dotfiles
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The installer creates links from that stable location to the files stored in the cloned repository.&lt;/p&gt;

&lt;p&gt;That distinction matters.&lt;/p&gt;

&lt;p&gt;A naïve dotfiles installer might simply copy a new &lt;code&gt;.bashrc&lt;/code&gt; over the user's existing one. That is easy to implement, but fairly hostile to environments such as Codespaces, Linux distributions, corporate machines, or anything else that has already added useful shell initialization.&lt;/p&gt;

&lt;p&gt;This repository instead tries to own only the portion it created.&lt;/p&gt;

&lt;p&gt;If an existing destination is not one of the symlinks the repository expects to manage, installation stops rather than replacing it.&lt;/p&gt;

&lt;p&gt;That behavior is slightly less convenient than &lt;code&gt;cp -f&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;It is also much harder to regret.&lt;/p&gt;

&lt;h2&gt;
  
  
  Idempotency changes everything
&lt;/h2&gt;

&lt;p&gt;A setup script becomes considerably more useful when running it twice produces the same result as running it once.&lt;/p&gt;

&lt;p&gt;That is the goal here.&lt;/p&gt;

&lt;p&gt;Running &lt;code&gt;install.sh&lt;/code&gt; repeatedly should not keep appending blocks to &lt;code&gt;.bashrc&lt;/code&gt;, duplicating Git configuration, or creating additional links.&lt;/p&gt;

&lt;p&gt;This is especially important with GitHub Codespaces because environment creation becomes an automated lifecycle operation rather than something you manually perform once every few years.&lt;/p&gt;

&lt;p&gt;The repository can be configured as a GitHub Codespaces dotfiles source, allowing new Codespaces to bootstrap the personal configuration automatically.&lt;/p&gt;

&lt;p&gt;At that point, idempotency is no longer just nice engineering hygiene.&lt;/p&gt;

&lt;p&gt;It becomes part of the interface.&lt;/p&gt;

&lt;h2&gt;
  
  
  Git configuration without replacing &lt;code&gt;.gitconfig&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;Git gets the same treatment.&lt;/p&gt;

&lt;p&gt;Rather than owning the user's complete global configuration, the installer adds an &lt;code&gt;include.path&lt;/code&gt; pointing at the managed Git configuration.&lt;/p&gt;

&lt;p&gt;The repository currently defines defaults such as:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="nn"&gt;[init]&lt;/span&gt;
    &lt;span class="py"&gt;defaultBranch&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;main&lt;/span&gt;

&lt;span class="nn"&gt;[fetch]&lt;/span&gt;
    &lt;span class="py"&gt;prune&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;true&lt;/span&gt;

&lt;span class="nn"&gt;[push]&lt;/span&gt;
    &lt;span class="py"&gt;autoSetupRemote&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;true&lt;/span&gt;

&lt;span class="nn"&gt;[rerere]&lt;/span&gt;
    &lt;span class="py"&gt;enabled&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;true&lt;/span&gt;

&lt;span class="nn"&gt;[diff]&lt;/span&gt;
    &lt;span class="py"&gt;algorithm&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;histogram&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;These are personal defaults, not project policies.&lt;/p&gt;

&lt;p&gt;Your employer's repository can still have its own configuration. Another tool can still add global Git settings. The dotfiles configuration participates in the final Git configuration instead of trying to become the entire configuration.&lt;/p&gt;

&lt;p&gt;That composability is something I now consider essential in a dotfiles repository.&lt;/p&gt;

&lt;h2&gt;
  
  
  Small aliases are useful. Context-aware helpers are better.
&lt;/h2&gt;

&lt;p&gt;Of course, the repository still contains the usual conveniences.&lt;/p&gt;

&lt;p&gt;For Git, I use aliases such as &lt;code&gt;gs&lt;/code&gt;, &lt;code&gt;gd&lt;/code&gt;, and &lt;code&gt;gl&lt;/code&gt;. For .NET, there are shortcuts such as &lt;code&gt;dr&lt;/code&gt; for restore, &lt;code&gt;db&lt;/code&gt; for build, and &lt;code&gt;dt&lt;/code&gt; for tests.&lt;/p&gt;

&lt;p&gt;Those save keystrokes.&lt;/p&gt;

&lt;p&gt;The more interesting commands are the repository-aware helpers.&lt;/p&gt;

&lt;p&gt;For example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet-context
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;can inspect the current Git repository and report conventions such as &lt;code&gt;global.json&lt;/code&gt;, &lt;code&gt;Directory.Build.props&lt;/code&gt;, &lt;code&gt;Directory.Packages.props&lt;/code&gt;, local tool manifests, and solution files.&lt;/p&gt;

&lt;p&gt;Another command:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet-repo-doctor
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;provides a broader diagnostic view of a .NET repository, including SDK resolution, solutions, projects, test projects, target frameworks, Central Package Management, and other common configuration.&lt;/p&gt;

&lt;p&gt;There is also:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet-deps vulnerable
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;for dependency diagnostics, and:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet-why Microsoft.CodeAnalysis.Common
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;for answering one of those wonderfully annoying questions:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Why is this package even in my dependency graph?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;And before pushing a change, I can run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet-verify
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;which coordinates restore, build, formatting verification, and tests using the repository's own configuration.&lt;/p&gt;

&lt;p&gt;The goal is not to hide the .NET CLI.&lt;/p&gt;

&lt;p&gt;It is to encode the repetitive discovery and safety checks that normally happen before invoking it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Respecting &lt;code&gt;global.json&lt;/code&gt; is a small but important detail
&lt;/h2&gt;

&lt;p&gt;One temptation when creating a developer bootstrap repository is installing your favorite SDK and tool versions globally.&lt;/p&gt;

&lt;p&gt;I intentionally avoided that.&lt;/p&gt;

&lt;p&gt;Different projects may target different SDK feature bands. Your dotfiles should not silently decide that every repository on your machine needs the same one.&lt;/p&gt;

&lt;p&gt;The helpers therefore resolve the SDK from the repository context instead of trying to impose one globally.&lt;/p&gt;

&lt;p&gt;The same idea applies to .NET tools.&lt;/p&gt;

&lt;p&gt;When a tool is part of a project's build process, a local tool manifest is a much better source of truth than someone's workstation.&lt;/p&gt;

&lt;p&gt;This is a subtle architectural boundary, but it dramatically improves reproducibility.&lt;/p&gt;

&lt;h2&gt;
  
  
  Diagnostics deserve a first-class command
&lt;/h2&gt;

&lt;p&gt;Automated setup is great until something becomes slightly wrong.&lt;/p&gt;

&lt;p&gt;That is why the repository includes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotfiles-doctor
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The doctor checks the assumptions that make the environment work: shell integration, managed symlinks, &lt;code&gt;PATH&lt;/code&gt;, Git includes, repository hooks, helper commands, Bash, Git, and the available .NET SDK.&lt;/p&gt;

&lt;p&gt;This is one of my favorite patterns in developer tooling.&lt;/p&gt;

&lt;p&gt;Installation says:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Here is how the environment should look.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;A doctor command says:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Here is whether it still looks that way.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That difference becomes increasingly valuable as the environment evolves.&lt;/p&gt;

&lt;p&gt;Instead of telling someone to inspect four configuration files and three symlinks manually, you give the environment an executable health check.&lt;/p&gt;

&lt;h2&gt;
  
  
  Updates are a trust boundary
&lt;/h2&gt;

&lt;p&gt;Updating dotfiles sounds trivial.&lt;/p&gt;

&lt;p&gt;You could simply run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git pull
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;and then execute the installer again.&lt;/p&gt;

&lt;p&gt;But there is a security detail hiding inside that workflow: &lt;strong&gt;the repository contains executable shell scripts&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Updating the repository therefore changes code that you may execute automatically.&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;dotfiles-update&lt;/code&gt; helper treats that as a trust boundary.&lt;/p&gt;

&lt;p&gt;It requires a clean worktree, verifies the expected &lt;code&gt;main&lt;/code&gt; branch and &lt;code&gt;origin/main&lt;/code&gt; upstream, validates that &lt;code&gt;origin&lt;/code&gt; points to the expected repository, rejects unexpected URL rewriting, fetches the update, requires a fast-forward, verifies expected executable files, and only then refreshes the installation.&lt;/p&gt;

&lt;p&gt;Afterward, it runs &lt;code&gt;dotfiles-doctor&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;This does not magically make remote code trustworthy. That would be an unrealistic claim.&lt;/p&gt;

&lt;p&gt;It does make the transition from one trusted local revision to another much more explicit.&lt;/p&gt;

&lt;p&gt;That is a useful distinction whenever an updater ends by executing newly downloaded code.&lt;/p&gt;

&lt;h2&gt;
  
  
  Uninstalling cleanly is part of installation design
&lt;/h2&gt;

&lt;p&gt;There is another feature that configuration scripts often forget:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;./uninstall.sh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The uninstaller removes what the repository owns and leaves unrelated configuration alone.&lt;/p&gt;

&lt;p&gt;That requirement influences the entire architecture.&lt;/p&gt;

&lt;p&gt;If you cannot identify which lines, files, symlinks, and Git configuration entries belong to your installer, safely removing them later becomes difficult.&lt;/p&gt;

&lt;p&gt;In other words, a good uninstall story is usually evidence of a good ownership model.&lt;/p&gt;

&lt;h2&gt;
  
  
  Dotfiles can leak more than you expect
&lt;/h2&gt;

&lt;p&gt;There is one rule worth repeating whenever dotfiles and GitHub appear in the same sentence:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Do not commit secrets.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Shell configuration is exactly the kind of place where credentials tend to accumulate over time.&lt;/p&gt;

&lt;p&gt;A quick &lt;code&gt;export API_KEY=...&lt;/code&gt; can become permanent history surprisingly easily.&lt;/p&gt;

&lt;p&gt;The repository therefore treats secret scanning as part of CI rather than relying purely on memory.&lt;/p&gt;

&lt;p&gt;Its validation pipeline currently includes Gitleaks for secret detection, actionlint for GitHub Actions validation, zizmor for workflow security auditing, and Hadolint for the lifecycle test Dockerfile.&lt;/p&gt;

&lt;p&gt;Shell scripts are additionally checked using Bash syntax validation, ShellCheck, and shfmt.&lt;/p&gt;

&lt;p&gt;The important lesson is not that every dotfiles repository needs exactly those tools.&lt;/p&gt;

&lt;p&gt;The lesson is that configuration repositories can execute code and can contain credentials, which means they deserve a security model too.&lt;/p&gt;

&lt;h2&gt;
  
  
  Yes, I test my dotfiles
&lt;/h2&gt;

&lt;p&gt;This may sound excessive until you consider what an installer does.&lt;/p&gt;

&lt;p&gt;It modifies shell startup behavior, Git configuration, symlinks, executable paths, and potentially every development environment you create.&lt;/p&gt;

&lt;p&gt;That is worth testing.&lt;/p&gt;

&lt;p&gt;The repository uses Bats to verify behavior such as installer idempotency, lifecycle operations, repository discovery, updater behavior, and the .NET helpers.&lt;/p&gt;

&lt;p&gt;It also builds a clean Ubuntu test container.&lt;/p&gt;

&lt;p&gt;That container verifies the lifecycle from a fresh environment: installation, diagnostics, idempotency, repository hooks, and uninstall.&lt;/p&gt;

&lt;p&gt;There is even a deny-by-default Docker context so unrelated local files are not accidentally copied into the lifecycle image.&lt;/p&gt;

&lt;p&gt;At some point, dotfiles stop being “some configuration files”.&lt;/p&gt;

&lt;p&gt;They become a small software product whose user happens to be you.&lt;/p&gt;

&lt;p&gt;And once you see them that way, tests stop looking strange.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I would recommend starting with
&lt;/h2&gt;

&lt;p&gt;You absolutely do not need all of this on day one.&lt;/p&gt;

&lt;p&gt;Start with the configuration that causes friction when you move between machines.&lt;/p&gt;

&lt;p&gt;Put your Git preferences and shell aliases in a repository. Add a simple bootstrap script. Make it safe to execute twice.&lt;/p&gt;

&lt;p&gt;Then resist the temptation to turn the repository into a universal package manager for your entire workstation.&lt;/p&gt;

&lt;p&gt;Add automation only when you repeatedly encounter a problem worth automating.&lt;/p&gt;

&lt;p&gt;The repository should grow with your workflow, not become another environment you have to maintain for its own sake.&lt;/p&gt;

&lt;h2&gt;
  
  
  Quick takeaways
&lt;/h2&gt;

&lt;p&gt;If you remember only a few things from this article:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Treat dotfiles as &lt;strong&gt;personal configuration as code&lt;/strong&gt;, not as a replacement for project configuration.&lt;/li&gt;
&lt;li&gt;Make installation &lt;strong&gt;idempotent and conservative&lt;/strong&gt;; avoid overwriting configuration you do not own.&lt;/li&gt;
&lt;li&gt;Keep SDKs, packages, tools, and other project dependencies &lt;strong&gt;inside the project that needs them&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Give automated environments a &lt;strong&gt;doctor command&lt;/strong&gt; so assumptions can be verified later.&lt;/li&gt;
&lt;li&gt;Consider updates to executable dotfiles a &lt;strong&gt;trust boundary&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Never store credentials in a public dotfiles repository, and consider automated secret scanning.&lt;/li&gt;
&lt;li&gt;Once your installer starts changing important parts of your environment, &lt;strong&gt;test it like software&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Where to go next
&lt;/h2&gt;

&lt;p&gt;If you want to explore the implementation discussed here, the complete repository is available at &lt;strong&gt;rodri-oliveira-dev/dotfiles&lt;/strong&gt; on GitHub. The most interesting places to start are &lt;code&gt;README.md&lt;/code&gt;, &lt;code&gt;install.sh&lt;/code&gt;, &lt;code&gt;bin/dotfiles-doctor&lt;/code&gt;, &lt;code&gt;bin/dotfiles-update&lt;/code&gt;, &lt;code&gt;shell/&lt;/code&gt;, &lt;code&gt;git/config&lt;/code&gt;, &lt;code&gt;.github/workflows/validate.yml&lt;/code&gt;, and &lt;code&gt;tests/&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;For the broader concepts, GitHub's documentation about personalizing Codespaces with dotfiles is an excellent next step. The Git documentation for configuration includes is useful for understanding the &lt;code&gt;include.path&lt;/code&gt; approach used here, while ShellCheck is worth studying if you maintain non-trivial Bash scripts.&lt;/p&gt;

&lt;p&gt;Bats is also a surprisingly useful tool to learn if you want executable tests around shell behavior. And if your dotfiles are stored remotely — especially in a public repository — studying secret scanning tools such as Gitleaks is time well spent.&lt;/p&gt;

&lt;p&gt;The main idea, however, is simpler than any particular tool.&lt;/p&gt;

&lt;p&gt;A development environment is part of the way we build software. Once we make that environment reproducible, observable, and intentionally scoped, moving to a new machine stops being a rebuilding exercise and becomes something much closer to deploying a known configuration.&lt;/p&gt;

&lt;p&gt;And that is a much nicer place to be.&lt;/p&gt;

</description>
      <category>dotfiles</category>
      <category>github</category>
      <category>dotnet</category>
      <category>devtools</category>
    </item>
    <item>
      <title>What Happens After the Commit?</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Wed, 07 Oct 2026 13:01:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/what-happens-after-the-commit-1a4c</link>
      <guid>https://dev.to/rodri-oliveira-dev/what-happens-after-the-commit-1a4c</guid>
      <description>&lt;p&gt;Saving a record to a database is relatively easy.&lt;/p&gt;

&lt;p&gt;We have mature tools for that problem. We open a transaction, change some state, commit it, and roll everything back if something fails before the commit.&lt;/p&gt;

&lt;p&gt;Things become much more interesting when the database commit is &lt;strong&gt;not the end of the operation&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Imagine a financial transaction. Once it is persisted, another service needs to know about it so it can update a balance projection. Maybe additional consumers will react to the same event later.&lt;/p&gt;

&lt;p&gt;The first implementation that comes to mind seems perfectly reasonable:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;save to database
publish event
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;But there is an uncomfortable question between those two lines:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What if the database commits successfully and the message broker becomes unavailable immediately afterward?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The transaction exists.&lt;/p&gt;

&lt;p&gt;The event does not.&lt;/p&gt;

&lt;p&gt;And now two parts of the system are telling different stories.&lt;/p&gt;

&lt;p&gt;This is one of the problems I wanted to explore in &lt;code&gt;poc-arquitetura&lt;/code&gt;, a repository I use as an executable software architecture laboratory.&lt;/p&gt;

&lt;p&gt;The project uses .NET, PostgreSQL, Kafka, Keycloak, OpenTelemetry, k6, and a few other tools. But the goal has never been to collect technologies or architectural patterns.&lt;/p&gt;

&lt;p&gt;What interests me is what happens when these patterns have to &lt;strong&gt;work together&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Outbox solves one problem and introduces new responsibilities. At-least-once delivery forces us to think about idempotency. Eventual consistency changes how we reason about reads. A Saga requires compensation. Retry needs boundaries. Messaging requires observability beyond HTTP.&lt;/p&gt;

&lt;p&gt;That simple question — &lt;em&gt;what happens after the commit?&lt;/em&gt; — opens a much broader discussion about distributed systems.&lt;/p&gt;


&lt;div class="ltag-github-readme-tag"&gt;
  &lt;div class="readme-overview"&gt;
    &lt;h2&gt;
      &lt;img src="https://assets.dev.to/assets/github-logo-5a155e1f9a670af7944dd5e12375bc76ed542ea80224905ecaf878b9157cdefc.svg" alt="GitHub logo"&gt;
      &lt;a href="https://github.com/rodri-oliveira-dev" rel="noopener noreferrer"&gt;
        rodri-oliveira-dev
      &lt;/a&gt; / &lt;a href="https://github.com/rodri-oliveira-dev/poc-arquitetura" rel="noopener noreferrer"&gt;
        poc-arquitetura
      &lt;/a&gt;
    &lt;/h2&gt;
    &lt;h3&gt;
      .NET architecture PoC for distributed services with CQRS, Kafka, PostgreSQL, Outbox, DLQ, observability and CI quality gates.
    &lt;/h3&gt;
  &lt;/div&gt;
  &lt;div class="ltag-github-body"&gt;
    
&lt;div id="readme" class="md"&gt;&lt;div class="markdown-heading"&gt;
&lt;h1 class="heading-element"&gt;poc-arquitetura&lt;/h1&gt;
&lt;/div&gt;

&lt;p&gt;&lt;a href="https://github.com/rodri-oliveira-dev/poc-arquitetura/actions/workflows/dotnet.yml" rel="noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/fe3131f0ae74307a8b6fee0b1aef474c4350a03abbe765f7bc5c23de95e7b9d5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f6472692d6f6c6976656972612d6465762f706f632d61727175697465747572612f646f746e65742e796d6c3f6272616e63683d6d61696e266c6162656c3d6275696c64" alt="Build"&gt;&lt;/a&gt;
&lt;a href="https://github.com/rodri-oliveira-dev/poc-arquitetura/actions/workflows/dotnet.yml" rel="noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/243e7d62ebda78d9a12d30c0d637d34ba406b27d4ae140b0dc40ec6c02c2365a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f6472692d6f6c6976656972612d6465762f706f632d61727175697465747572612f646f746e65742e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473" alt="Tests"&gt;&lt;/a&gt;
&lt;a href="https://sonarcloud.io/summary/new_code?id=rodri-oliveira-dev_poc-arquitetura" rel="nofollow noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/1cbca7d4eb2ec66bbc0533942842415c0e083cffef775ff5bddff0b05392e71f/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d726f6472692d6f6c6976656972612d6465765f706f632d6172717569746574757261266d65747269633d616c6572745f737461747573" alt="Quality Gate Status"&gt;&lt;/a&gt;
&lt;a href="https://sonarcloud.io/summary/new_code?id=rodri-oliveira-dev_poc-arquitetura" rel="nofollow noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/efb4081b14125ef862be0bab0ceb1c09bfd3cf406d3f06487b8eb0ee6391ac36/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d726f6472692d6f6c6976656972612d6465765f706f632d6172717569746574757261266d65747269633d73656375726974795f726174696e67" alt="Security Rating"&gt;&lt;/a&gt;
&lt;a href="https://rodri-oliveira-dev.github.io/poc-arquitetura/" rel="nofollow noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/e03cfc430fac7d97d80b41b3e219c9467a412ba45611163352c3e30055b39c09/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f6472692d6f6c6976656972612d6465762f706f632d61727175697465747572612f70616765732d6172636869746563747572652e796d6c3f6272616e63683d6d61696e266c6162656c3d617263686974656374757265253230646f6373" alt="Architecture Docs"&gt;&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;POC educacional de microserviços em .NET para estudar arquitetura de software com código real: Clean Architecture, DDD, PostgreSQL, Kafka, Outbox, Inbox, JWT/JWKS com Keycloak, observabilidade, segurança, contratos e testes automatizados.&lt;/p&gt;
&lt;p&gt;Ela demonstra um problema comum em sistemas financeiros: registrar fatos de forma transacional, publicar eventos com confiabilidade, projetar saldos em outro serviço e operar falhas sem esconder consistência eventual. O repositório também mostra contextos de identidade, transferência, pagamento externo e auditoria funcional para exercitar trade-offs de integração.&lt;/p&gt;
&lt;p&gt;Este projeto é útil para:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;quem está aprendendo arquitetura e quer ver os conceitos aplicados;&lt;/li&gt;
&lt;li&gt;desenvolvedores .NET que querem executar, testar e alterar uma stack local;&lt;/li&gt;
&lt;li&gt;arquitetos que querem avaliar decisões, limites e riscos;&lt;/li&gt;
&lt;li&gt;avaliadores técnicos que querem entender a proposta rapidamente.&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="markdown-heading"&gt;
&lt;h2 class="heading-element"&gt;Visão geral&lt;/h2&gt;
&lt;/div&gt;

  &lt;div class="js-render-enrichment-target"&gt;
    &lt;div class="render-plaintext-hidden"&gt;
      &lt;pre&gt;flowchart LR
    Client[Cliente ou teste] --&amp;gt; Keycloak[Keycloak OIDC]
    Client --&amp;gt; LedgerApi[LedgerService.Api]
    Client --&amp;gt; BalanceApi[BalanceService.Api]
    Client --&amp;gt; TransferApi[TransferService.Api]
    Client --&amp;gt; PaymentApi[PaymentService.Api]
    Client --&amp;gt; IdentityApi[IdentityService.Api]
    Client --&amp;gt; AuditApi[AuditService.Api]
    LedgerApi --&amp;gt;&lt;/pre&gt;…&lt;/div&gt;
&lt;/div&gt;&lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="gh-btn-container"&gt;&lt;a class="gh-btn" href="https://github.com/rodri-oliveira-dev/poc-arquitetura" rel="noopener noreferrer"&gt;View on GitHub&lt;/a&gt;&lt;/div&gt;
&lt;/div&gt;





&lt;h2&gt;
  
  
  Start by separating facts from projections
&lt;/h2&gt;

&lt;p&gt;Two bounded contexts are especially important in this example.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;LedgerService&lt;/code&gt; owns financial facts.&lt;/p&gt;

&lt;p&gt;If a financial transaction happened, the Ledger is where that fact should be recorded.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;BalanceService&lt;/code&gt; has a different responsibility. It maintains a projection optimized for balance queries.&lt;/p&gt;

&lt;p&gt;At a high level, the architecture looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;pre data-lang="mermaid"&gt;&lt;code&gt;flowchart LR
    Client[Client] --&amp;gt; LedgerApi[Ledger API]

    LedgerApi --&amp;gt; LedgerDb[(PostgreSQL&amp;lt;br/&amp;gt;Ledger)]

    LedgerDb --&amp;gt; LedgerWorker[Ledger Worker]
    LedgerWorker --&amp;gt; Kafka[(Kafka)]

    Kafka --&amp;gt; BalanceWorker[Balance Worker]
    BalanceWorker --&amp;gt; BalanceDb[(PostgreSQL&amp;lt;br/&amp;gt;Balance)]

    Client --&amp;gt; BalanceApi[Balance API]
    BalanceApi --&amp;gt; BalanceDb&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;A transaction and a balance are not the same thing.&lt;/p&gt;

&lt;p&gt;The transaction is a fact: something happened.&lt;/p&gt;

&lt;p&gt;The balance is a model derived from those facts.&lt;/p&gt;

&lt;p&gt;Could everything live in a single application and database? Absolutely. Depending on the system, that may even be the better architecture.&lt;/p&gt;

&lt;p&gt;But this laboratory deliberately separates those responsibilities so that the consequences of the decision become visible.&lt;/p&gt;

&lt;p&gt;One consequence appears immediately.&lt;/p&gt;

&lt;p&gt;The balance is no longer updated inside the same database transaction as the Ledger.&lt;/p&gt;

&lt;p&gt;We have entered the world of &lt;strong&gt;eventual consistency&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That does not mean the system is simply inconsistent or incorrect. It means there is a period during which the Ledger already knows about a transaction while the Balance projection has not processed it yet.&lt;/p&gt;

&lt;p&gt;That window is not an accident.&lt;/p&gt;

&lt;p&gt;It is part of the architecture.&lt;/p&gt;




&lt;h2&gt;
  
  
  The real problem is not Kafka. It is the dual write
&lt;/h2&gt;

&lt;p&gt;Suppose the Ledger does something like this:&lt;br&gt;
&lt;/p&gt;

&lt;pre data-lang="mermaid"&gt;&lt;code&gt;sequenceDiagram
    participant C as Client
    participant L as Ledger API
    participant DB as PostgreSQL
    participant K as Kafka

    C-&amp;gt;&amp;gt;L: Create transaction
    L-&amp;gt;&amp;gt;DB: INSERT LedgerEntry
    DB--&amp;gt;&amp;gt;L: COMMIT
    L-&amp;gt;&amp;gt;K: Publish event
    K--&amp;gt;&amp;gt;L: Acknowledged
    L--&amp;gt;&amp;gt;C: 201 Created

    Note over L,K: What happens if the process&amp;lt;br/&amp;gt;fails after COMMIT but before publish?&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;When everything works, this looks fine.&lt;/p&gt;

&lt;p&gt;Now imagine that the database commit succeeds but the process crashes before Kafka acknowledges the event.&lt;/p&gt;

&lt;p&gt;The Ledger contains the transaction.&lt;/p&gt;

&lt;p&gt;The event may never be published.&lt;/p&gt;

&lt;p&gt;Publishing first and saving afterward does not solve the problem either. It simply reverses it: we can now publish an event for a transaction that later fails to commit.&lt;/p&gt;

&lt;p&gt;This is the &lt;strong&gt;dual-write problem&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;We need to update two independent resources — the database and the broker — and would like them to behave as if they belonged to one atomic transaction.&lt;/p&gt;

&lt;p&gt;One option would be some form of distributed transaction.&lt;/p&gt;

&lt;p&gt;For this project, I chose a different approach: accept that PostgreSQL and Kafka have independent lifecycles and make the &lt;strong&gt;intent to publish durable&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That is where the Transactional Outbox pattern becomes useful.&lt;/p&gt;




&lt;h2&gt;
  
  
  Outbox: do not publish now, persist the intent to publish
&lt;/h2&gt;

&lt;p&gt;Instead of saving a transaction and immediately depending on Kafka, the Ledger stores both the financial fact and an Outbox message inside the &lt;strong&gt;same PostgreSQL transaction&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;pre data-lang="mermaid"&gt;&lt;code&gt;sequenceDiagram
    participant C as Client
    participant L as Ledger API
    participant DB as PostgreSQL
    participant W as Ledger Worker
    participant K as Kafka

    C-&amp;gt;&amp;gt;L: Create transaction

    rect rgb(235, 235, 235)
        L-&amp;gt;&amp;gt;DB: BEGIN
        L-&amp;gt;&amp;gt;DB: INSERT LedgerEntry
        L-&amp;gt;&amp;gt;DB: INSERT OutboxMessage
        L-&amp;gt;&amp;gt;DB: COMMIT
    end

    L--&amp;gt;&amp;gt;C: Transaction confirmed

    W-&amp;gt;&amp;gt;DB: Fetch pending messages
    DB--&amp;gt;&amp;gt;W: OutboxMessage
    W-&amp;gt;&amp;gt;K: Publish LedgerEntryCreated
    K--&amp;gt;&amp;gt;W: Acknowledged
    W-&amp;gt;&amp;gt;DB: Mark as processed&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;Either both records are persisted or neither is.&lt;/p&gt;

&lt;p&gt;The HTTP request no longer needs Kafka to be available in order to preserve the intent to publish the event.&lt;/p&gt;

&lt;p&gt;A separate worker polls pending Outbox messages and publishes them.&lt;/p&gt;

&lt;p&gt;After Kafka confirms publication, the worker updates the Outbox entry.&lt;/p&gt;

&lt;p&gt;If Kafka is unavailable, the financial transaction still exists &lt;strong&gt;together with durable information that an event still needs to be published&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;If the worker crashes, processing can resume later.&lt;/p&gt;

&lt;p&gt;This small architectural change has an important effect.&lt;/p&gt;

&lt;p&gt;The failure is no longer a tiny invisible window between two independent writes.&lt;/p&gt;

&lt;p&gt;It becomes &lt;strong&gt;state that the system can observe and recover from&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That, to me, is one of the most useful ways to understand Outbox.&lt;/p&gt;

&lt;p&gt;It does not magically turn Kafka and PostgreSQL into a single transaction.&lt;/p&gt;

&lt;p&gt;It does not guarantee exactly-once processing.&lt;/p&gt;

&lt;p&gt;It turns an otherwise difficult-to-recover failure into something explicitly represented in the system.&lt;/p&gt;

&lt;p&gt;Recoverable systems are usually far more interesting than systems designed around the assumption that failures will not happen.&lt;/p&gt;




&lt;h2&gt;
  
  
  Preventing message loss creates another problem: duplicates
&lt;/h2&gt;

&lt;p&gt;There is a consequence to this design.&lt;/p&gt;

&lt;p&gt;Imagine the worker publishes an event successfully, but crashes before marking the Outbox message as processed.&lt;/p&gt;

&lt;p&gt;When it restarts, the same message may be published again.&lt;br&gt;
&lt;/p&gt;

&lt;pre data-lang="mermaid"&gt;&lt;code&gt;sequenceDiagram
    participant O as Outbox
    participant W as Ledger Worker
    participant K as Kafka
    participant B as Balance Worker
    participant DB as Balance DB

    O-&amp;gt;&amp;gt;W: Pending message
    W-&amp;gt;&amp;gt;K: Publish event
    K--&amp;gt;&amp;gt;W: Success

    Note over W: Worker crashes before&amp;lt;br/&amp;gt;marking the message as processed

    O-&amp;gt;&amp;gt;W: Same message again
    W-&amp;gt;&amp;gt;K: Republish event

    K-&amp;gt;&amp;gt;B: Event
    B-&amp;gt;&amp;gt;DB: Was this event_id processed?
    DB--&amp;gt;&amp;gt;B: No
    B-&amp;gt;&amp;gt;DB: Update projection and store event_id

    K-&amp;gt;&amp;gt;B: Duplicate event
    B-&amp;gt;&amp;gt;DB: Was this event_id processed?
    DB--&amp;gt;&amp;gt;B: Yes

    Note over B: Duplicate safely ignored&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;This is not necessarily a bug.&lt;/p&gt;

&lt;p&gt;It is a normal consequence of &lt;strong&gt;at-least-once delivery&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The responsibility now moves to the consumer.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;BalanceService&lt;/code&gt; records processed event identifiers so the same event does not modify the projection twice.&lt;/p&gt;

&lt;p&gt;That is idempotency becoming part of the architecture.&lt;/p&gt;

&lt;p&gt;Retries are often presented as generic resilience configuration: retry three times, use exponential backoff, done.&lt;/p&gt;

&lt;p&gt;But retry is also a business decision.&lt;/p&gt;

&lt;p&gt;If executing the same operation twice produces two different side effects, a retry may cause more damage than the original failure.&lt;/p&gt;

&lt;p&gt;Before asking:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;How many times should we retry?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;I think a better question is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;What happens if we execute this operation again?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That question tends to uncover much more important design problems.&lt;/p&gt;




&lt;h2&gt;
  
  
  Eventual consistency has to exist outside the diagram too
&lt;/h2&gt;

&lt;p&gt;Once Ledger and Balance are separated, this state becomes perfectly valid:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Ledger:
Transaction exists.

Balance:
Transaction has not been projected yet.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;There is nothing inherently wrong with that.&lt;/p&gt;

&lt;p&gt;The problem appears when the architecture is asynchronous but the rest of the product behaves as though every read must immediately reflect every write.&lt;/p&gt;

&lt;p&gt;Different domains solve this in different ways.&lt;/p&gt;

&lt;p&gt;Some operations can expose a processing state. Some critical queries may need to consult the source of truth. Some applications can simply tolerate a small delay before projections become visible.&lt;/p&gt;

&lt;p&gt;There is no universal answer.&lt;/p&gt;

&lt;p&gt;The important point is that eventual consistency should be a &lt;strong&gt;known business and architectural property&lt;/strong&gt;, not an accidental side effect of adding Kafka.&lt;/p&gt;


&lt;h2&gt;
  
  
  Events are APIs too
&lt;/h2&gt;

&lt;p&gt;Once services depend on events, another problem eventually appears:&lt;/p&gt;

&lt;p&gt;contracts change.&lt;/p&gt;

&lt;p&gt;The project includes an evolution from events such as:&lt;br&gt;
&lt;/p&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;LedgerEntryCreated.v1
LedgerEntryCreated.v2
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;During a migration period, consumers may need to understand both versions.&lt;/p&gt;

&lt;p&gt;That forces us to treat event schemas as real integration contracts.&lt;/p&gt;

&lt;p&gt;We already think carefully about HTTP APIs: OpenAPI definitions, breaking changes, versioning, client compatibility.&lt;/p&gt;

&lt;p&gt;Events deserve similar care, perhaps even more.&lt;/p&gt;

&lt;p&gt;An HTTP response usually exists only during a request.&lt;/p&gt;

&lt;p&gt;An event may remain in a Kafka topic, a dead-letter queue, or a replay mechanism long after the application version that originally created it has disappeared.&lt;/p&gt;

&lt;p&gt;That changes how we think about compatibility.&lt;/p&gt;

&lt;p&gt;Ordering deserves attention too.&lt;/p&gt;

&lt;p&gt;Kafka guarantees ordering &lt;strong&gt;within a partition&lt;/strong&gt;, not universal ordering across the entire system.&lt;/p&gt;

&lt;p&gt;The message key therefore becomes an architectural decision because it influences which events share a partition and which operations can be processed in parallel.&lt;/p&gt;

&lt;p&gt;Details that look small in producer code can have significant consequences for correctness and throughput.&lt;/p&gt;


&lt;h2&gt;
  
  
  Retry cannot be the final answer
&lt;/h2&gt;

&lt;p&gt;Some failures are temporary.&lt;/p&gt;

&lt;p&gt;A broker can become unavailable. A network request can time out. A dependency may take longer than expected to respond.&lt;/p&gt;

&lt;p&gt;Retry with backoff makes sense in those cases.&lt;/p&gt;

&lt;p&gt;But a structurally invalid event will still be invalid ten seconds later.&lt;/p&gt;

&lt;p&gt;An incompatible schema will not suddenly become compatible on attempt number 47.&lt;/p&gt;

&lt;p&gt;Retrying forever simply turns one bad message into a permanent consumer of CPU, logs, and operational attention.&lt;/p&gt;

&lt;p&gt;That is where a &lt;strong&gt;Dead Letter Queue&lt;/strong&gt;, or DLQ, becomes useful.&lt;/p&gt;

&lt;p&gt;A useful DLQ should preserve enough information for investigation and recovery: the original payload, event type, failure classification, source information, and correlation metadata.&lt;/p&gt;

&lt;p&gt;But putting something in a DLQ is only half the solution.&lt;/p&gt;

&lt;p&gt;The more important question is:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What happens next?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Can the message be safely replayed?&lt;/p&gt;

&lt;p&gt;Was the root cause fixed?&lt;/p&gt;

&lt;p&gt;Can a projection be rebuilt?&lt;/p&gt;

&lt;p&gt;Should the message be discarded?&lt;/p&gt;

&lt;p&gt;Does the operation require manual review?&lt;/p&gt;

&lt;p&gt;The project explores requeue, replay, and projection rebuild scenarios because recovery is part of the architecture too.&lt;/p&gt;

&lt;p&gt;A phrase I keep coming back to is:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A DLQ without a recovery strategy is just a distributed archive of unresolved problems.&lt;/strong&gt;&lt;/p&gt;


&lt;h2&gt;
  
  
  Transfers make distributed failures much easier to see
&lt;/h2&gt;

&lt;p&gt;Updating a read projection is relatively straightforward compared with an operation that produces multiple distributed side effects.&lt;/p&gt;

&lt;p&gt;Consider a transfer.&lt;/p&gt;

&lt;p&gt;At a simplified level, we need to create a debit and then a credit.&lt;/p&gt;

&lt;p&gt;Inside one local database transaction, ACID properties solve a lot of problems for us.&lt;/p&gt;

&lt;p&gt;Across independent components, those guarantees disappear.&lt;/p&gt;

&lt;p&gt;The project models this flow as an orchestrated Saga:&lt;br&gt;
&lt;/p&gt;
&lt;pre data-lang="mermaid"&gt;&lt;code&gt;flowchart TD
    A[Transfer Requested] --&amp;gt; B[Create Debit]

    B --&amp;gt;|Success| C[Create Credit]
    B --&amp;gt;|Failure| F[Transfer Failed]

    C --&amp;gt;|Success| D[Transfer Completed]
    C --&amp;gt;|Failure| E[Compensate Debit]

    E --&amp;gt; G[Record Reversal]
    G --&amp;gt; F&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;This makes something very explicit:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;when we distribute an operation, we also distribute its failure modes.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If the debit succeeds and the credit fails, there is no global &lt;code&gt;ROLLBACK&lt;/code&gt; statement capable of reversing time across independent services.&lt;/p&gt;

&lt;p&gt;We have to define what compensation means.&lt;/p&gt;

&lt;p&gt;In financial domains, compensation often should not erase the original fact. A reversal can instead create a new fact that neutralizes the previous one while preserving the history of what happened.&lt;/p&gt;

&lt;p&gt;A Saga does not recreate ACID across services.&lt;/p&gt;

&lt;p&gt;It models the states and compensating actions required because that local transaction boundary no longer exists.&lt;/p&gt;

&lt;p&gt;That distinction is important.&lt;/p&gt;


&lt;h2&gt;
  
  
  Circuit breakers do not hide failures. They control them.
&lt;/h2&gt;

&lt;p&gt;Another scenario in the laboratory intentionally takes &lt;code&gt;LedgerService&lt;/code&gt; offline while the transfer worker is still running.&lt;/p&gt;

&lt;p&gt;Without protection, the worker can keep calling a dependency that is already known to be unavailable.&lt;/p&gt;

&lt;p&gt;Retries can make this even worse by multiplying calls against an unhealthy service.&lt;/p&gt;

&lt;p&gt;A Circuit Breaker changes that behavior.&lt;br&gt;
&lt;/p&gt;
&lt;pre data-lang="mermaid"&gt;&lt;code&gt;stateDiagram-v2
    [*] --&amp;gt; Closed

    Closed: Requests flow normally
    Open: Requests fail fast
    HalfOpen: Limited probe requests

    Closed --&amp;gt; Open: Consecutive failures
    Open --&amp;gt; HalfOpen: Wait period expires
    HalfOpen --&amp;gt; Closed: Dependency recovered
    HalfOpen --&amp;gt; Open: Dependency still unhealthy&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;When the circuit is open, the system has not somehow recovered.&lt;/p&gt;

&lt;p&gt;It has acknowledged the failure and chosen not to waste resources repeatedly exercising the same broken dependency.&lt;/p&gt;

&lt;p&gt;After a configured interval, the breaker allows a controlled probe through the half-open state.&lt;/p&gt;

&lt;p&gt;If that succeeds, traffic can resume.&lt;/p&gt;

&lt;p&gt;This leads to another principle that I think is worth emphasizing:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Resilience does not mean making failures invisible.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Resilience means making failure behavior predictable.&lt;/p&gt;


&lt;h2&gt;
  
  
  Observability becomes much more important after leaving HTTP
&lt;/h2&gt;

&lt;p&gt;Following a single HTTP request through logs is usually manageable.&lt;/p&gt;

&lt;p&gt;Following an asynchronous workflow across several processes is very different.&lt;/p&gt;

&lt;p&gt;A single operation may travel through:&lt;br&gt;
&lt;/p&gt;
&lt;pre data-lang="mermaid"&gt;&lt;code&gt;flowchart LR
    Request[HTTP Request]
        --&amp;gt; API[Ledger API]
        --&amp;gt; DB[(PostgreSQL)]
        --&amp;gt; Outbox[Outbox]
        --&amp;gt; Worker[Ledger Worker]
        --&amp;gt; Kafka[(Kafka)]
        --&amp;gt; Consumer[Balance Worker]
        --&amp;gt; Projection[(Balance DB)]

    Request -. Correlation ID .-&amp;gt; API
    API -. Trace Context .-&amp;gt; Outbox
    Outbox -. traceparent .-&amp;gt; Worker
    Worker -. Trace Context .-&amp;gt; Kafka
    Kafka -. traceparent .-&amp;gt; Consumer&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;If every component produces unrelated logs, diagnosing a problem becomes timestamp archaeology.&lt;/p&gt;

&lt;p&gt;The project propagates &lt;code&gt;correlation_id&lt;/code&gt;, and when OpenTelemetry is enabled, W3C tracing context such as &lt;code&gt;traceparent&lt;/code&gt; and &lt;code&gt;tracestate&lt;/code&gt; can also travel through the Outbox and Kafka messages.&lt;/p&gt;

&lt;p&gt;The observability side can be viewed separately:&lt;br&gt;
&lt;/p&gt;
&lt;pre data-lang="mermaid"&gt;&lt;code&gt;flowchart LR
    Client[Client] --&amp;gt; API[Ledger API]
    API --&amp;gt; DB[(PostgreSQL)]
    DB --&amp;gt; Outbox[Outbox]
    Outbox --&amp;gt; Worker[Ledger Worker]
    Worker --&amp;gt; Kafka[(Kafka)]
    Kafka --&amp;gt; Consumer[Balance Worker]
    Consumer --&amp;gt; Balance[(Balance DB)]

    API -.-&amp;gt; OTEL[OpenTelemetry]
    Worker -.-&amp;gt; OTEL
    Consumer -.-&amp;gt; OTEL

    OTEL --&amp;gt; Traces[Traces]
    OTEL --&amp;gt; Metrics[Metrics]

    API -. Logs .-&amp;gt; Logs[Centralized Logs]
    Worker -. Logs .-&amp;gt; Logs
    Consumer -. Logs .-&amp;gt; Logs&lt;/code&gt;&lt;/pre&gt;



&lt;p&gt;The local stack includes OpenTelemetry, Jaeger, Prometheus, Grafana, Loki, and supporting components.&lt;/p&gt;

&lt;p&gt;But the tools are not the important part.&lt;/p&gt;

&lt;p&gt;The important part is the questions they allow us to answer.&lt;/p&gt;

&lt;p&gt;The API is healthy, but is the Outbox backlog growing?&lt;/p&gt;

&lt;p&gt;Is the producer failing?&lt;/p&gt;

&lt;p&gt;Is consumer processing slowing down?&lt;/p&gt;

&lt;p&gt;Are duplicates increasing?&lt;/p&gt;

&lt;p&gt;Has the DLQ started receiving messages?&lt;/p&gt;

&lt;p&gt;Which original HTTP request produced the event that failed several minutes later in another process?&lt;/p&gt;

&lt;p&gt;Once asynchronous processing becomes central to the system, an HTTP health endpoint tells only a very small part of the story.&lt;/p&gt;


&lt;h2&gt;
  
  
  Test the architecture, not only the classes
&lt;/h2&gt;

&lt;p&gt;A system like this can have excellent unit-test coverage and still fail exactly where the interesting risks are: between components.&lt;/p&gt;

&lt;p&gt;That is why the laboratory also contains integration tests and k6 scenarios that exercise complete workflows.&lt;/p&gt;

&lt;p&gt;One scenario validates:&lt;br&gt;
&lt;/p&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Ledger
  -&amp;gt; Outbox
  -&amp;gt; Kafka
  -&amp;gt; Balance
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Another exercises the complete Transfer Saga.&lt;/p&gt;

&lt;p&gt;There is also a resilience scenario in which the Ledger dependency is deliberately stopped so the Circuit Breaker's behavior can be observed during failure and recovery.&lt;/p&gt;

&lt;p&gt;I am careful not to describe these tests as production-scale benchmarks.&lt;/p&gt;

&lt;p&gt;They run in a controlled local environment.&lt;/p&gt;

&lt;p&gt;Their latency thresholds are regression guardrails, not production SLOs.&lt;/p&gt;

&lt;p&gt;Running 50 requests per second on Docker Compose does not prove that an architecture can operate at banking scale.&lt;/p&gt;

&lt;p&gt;Real capacity depends on infrastructure, partitions, database behavior, network topology, autoscaling, workload characteristics, failure modes, and many other variables.&lt;/p&gt;

&lt;p&gt;The tests prove something narrower, but still valuable:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;the architectural behavior remains testable under concurrency and controlled failure conditions.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Sometimes the best architecture test is not checking whether a certain method was called.&lt;/p&gt;

&lt;p&gt;It is turning a dependency off and observing what the system actually does.&lt;/p&gt;


&lt;h2&gt;
  
  
  This is a laboratory, not a production reference architecture
&lt;/h2&gt;

&lt;p&gt;Projects that demonstrate microservices, Kafka, Outbox, Sagas, and observability can easily give the impression that they represent a universal production blueprint.&lt;/p&gt;

&lt;p&gt;This one does not.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;poc-arquitetura&lt;/code&gt; is intentionally a laboratory for experimenting with decisions.&lt;/p&gt;

&lt;p&gt;A real production environment would still need serious work around secrets management, workload identity, high availability, Kafka capacity and replication, disaster recovery, network security, production SLOs, infrastructure topology, deployment strategy, and many domain-specific controls.&lt;/p&gt;

&lt;p&gt;That distinction matters.&lt;/p&gt;

&lt;p&gt;Software architecture is not the process of fitting as many patterns as possible into a diagram.&lt;/p&gt;

&lt;p&gt;It is the process of choosing mechanisms that are proportional to the problems the system actually has.&lt;/p&gt;


&lt;h2&gt;
  
  
  Quick takeaways
&lt;/h2&gt;

&lt;p&gt;The database commit is often only the beginning of a distributed workflow.&lt;/p&gt;

&lt;p&gt;Transactional Outbox does not make PostgreSQL and Kafka a single transaction; it makes the intent to publish durable.&lt;/p&gt;

&lt;p&gt;At-least-once delivery means duplicates are expected, which makes idempotency a correctness requirement rather than a nice optimization.&lt;/p&gt;

&lt;p&gt;Eventual consistency has to be understood by the product, not hidden behind a message broker.&lt;/p&gt;

&lt;p&gt;Retries require operations that are safe to repeat. DLQs require recovery procedures. Sagas make states and compensations explicit when a local transaction is no longer available.&lt;/p&gt;

&lt;p&gt;Circuit Breakers control failures instead of pretending those failures disappeared.&lt;/p&gt;

&lt;p&gt;And observability has to cross the same boundaries that events cross.&lt;/p&gt;

&lt;p&gt;If I had to reduce the whole experiment to one idea, it would be this:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;In distributed systems, we do not design only the successful path. We also design how failures are detected, understood, and recovered.&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;


&lt;h2&gt;
  
  
  Where to go next
&lt;/h2&gt;

&lt;p&gt;For a broader view of .NET microservice architecture, Microsoft's &lt;strong&gt;“.NET Microservices: Architecture for Containerized .NET Applications”&lt;/strong&gt; is a useful starting point.&lt;/p&gt;

&lt;p&gt;For Transactional Outbox, Saga, Idempotent Consumer, and related distributed-system patterns, &lt;strong&gt;Chris Richardson's Microservices Patterns&lt;/strong&gt; and the Microservices.io pattern catalog are excellent references.&lt;/p&gt;

&lt;p&gt;For Kafka, it is worth going beyond basic producer/consumer tutorials and studying the official material on &lt;strong&gt;partitions, consumer groups, offsets, ordering, delivery semantics, and transactions&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;For distributed tracing and context propagation, the &lt;strong&gt;OpenTelemetry documentation&lt;/strong&gt; provides a vendor-neutral mental model for traces, spans, metrics, baggage, and propagation.&lt;/p&gt;

&lt;p&gt;For load and resilience testing, &lt;strong&gt;Grafana k6&lt;/strong&gt; is approachable enough to start small while still supporting serious workloads.&lt;/p&gt;

&lt;p&gt;And if you want to understand the deeper ideas behind transactions, replication, streams, partitioning, and distributed data, &lt;strong&gt;Designing Data-Intensive Applications&lt;/strong&gt;, by Martin Kleppmann, is still one of the books I would put near the top of the list.&lt;/p&gt;

&lt;p&gt;The repository behind this article contains the source code, ADRs, event contracts, architecture documentation, tests, and failure scenarios discussed here:&lt;/p&gt;


&lt;div class="ltag-github-readme-tag"&gt;
  &lt;div class="readme-overview"&gt;
    &lt;h2&gt;
      &lt;img src="https://assets.dev.to/assets/github-logo-5a155e1f9a670af7944dd5e12375bc76ed542ea80224905ecaf878b9157cdefc.svg" alt="GitHub logo"&gt;
      &lt;a href="https://github.com/rodri-oliveira-dev" rel="noopener noreferrer"&gt;
        rodri-oliveira-dev
      &lt;/a&gt; / &lt;a href="https://github.com/rodri-oliveira-dev/poc-arquitetura" rel="noopener noreferrer"&gt;
        poc-arquitetura
      &lt;/a&gt;
    &lt;/h2&gt;
    &lt;h3&gt;
      .NET architecture PoC for distributed services with CQRS, Kafka, PostgreSQL, Outbox, DLQ, observability and CI quality gates.
    &lt;/h3&gt;
  &lt;/div&gt;
  &lt;div class="ltag-github-body"&gt;
    
&lt;div id="readme" class="md"&gt;&lt;div class="markdown-heading"&gt;
&lt;h1 class="heading-element"&gt;poc-arquitetura&lt;/h1&gt;
&lt;/div&gt;

&lt;p&gt;&lt;a href="https://github.com/rodri-oliveira-dev/poc-arquitetura/actions/workflows/dotnet.yml" rel="noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/fe3131f0ae74307a8b6fee0b1aef474c4350a03abbe765f7bc5c23de95e7b9d5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f6472692d6f6c6976656972612d6465762f706f632d61727175697465747572612f646f746e65742e796d6c3f6272616e63683d6d61696e266c6162656c3d6275696c64" alt="Build"&gt;&lt;/a&gt;
&lt;a href="https://github.com/rodri-oliveira-dev/poc-arquitetura/actions/workflows/dotnet.yml" rel="noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/243e7d62ebda78d9a12d30c0d637d34ba406b27d4ae140b0dc40ec6c02c2365a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f6472692d6f6c6976656972612d6465762f706f632d61727175697465747572612f646f746e65742e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473" alt="Tests"&gt;&lt;/a&gt;
&lt;a href="https://sonarcloud.io/summary/new_code?id=rodri-oliveira-dev_poc-arquitetura" rel="nofollow noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/1cbca7d4eb2ec66bbc0533942842415c0e083cffef775ff5bddff0b05392e71f/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d726f6472692d6f6c6976656972612d6465765f706f632d6172717569746574757261266d65747269633d616c6572745f737461747573" alt="Quality Gate Status"&gt;&lt;/a&gt;
&lt;a href="https://sonarcloud.io/summary/new_code?id=rodri-oliveira-dev_poc-arquitetura" rel="nofollow noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/efb4081b14125ef862be0bab0ceb1c09bfd3cf406d3f06487b8eb0ee6391ac36/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d726f6472692d6f6c6976656972612d6465765f706f632d6172717569746574757261266d65747269633d73656375726974795f726174696e67" alt="Security Rating"&gt;&lt;/a&gt;
&lt;a href="https://rodri-oliveira-dev.github.io/poc-arquitetura/" rel="nofollow noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/e03cfc430fac7d97d80b41b3e219c9467a412ba45611163352c3e30055b39c09/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f6472692d6f6c6976656972612d6465762f706f632d61727175697465747572612f70616765732d6172636869746563747572652e796d6c3f6272616e63683d6d61696e266c6162656c3d617263686974656374757265253230646f6373" alt="Architecture Docs"&gt;&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;POC educacional de microserviços em .NET para estudar arquitetura de software com código real: Clean Architecture, DDD, PostgreSQL, Kafka, Outbox, Inbox, JWT/JWKS com Keycloak, observabilidade, segurança, contratos e testes automatizados.&lt;/p&gt;
&lt;p&gt;Ela demonstra um problema comum em sistemas financeiros: registrar fatos de forma transacional, publicar eventos com confiabilidade, projetar saldos em outro serviço e operar falhas sem esconder consistência eventual. O repositório também mostra contextos de identidade, transferência, pagamento externo e auditoria funcional para exercitar trade-offs de integração.&lt;/p&gt;
&lt;p&gt;Este projeto é útil para:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;quem está aprendendo arquitetura e quer ver os conceitos aplicados;&lt;/li&gt;
&lt;li&gt;desenvolvedores .NET que querem executar, testar e alterar uma stack local;&lt;/li&gt;
&lt;li&gt;arquitetos que querem avaliar decisões, limites e riscos;&lt;/li&gt;
&lt;li&gt;avaliadores técnicos que querem entender a proposta rapidamente.&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="markdown-heading"&gt;
&lt;h2 class="heading-element"&gt;Visão geral&lt;/h2&gt;
&lt;/div&gt;

  &lt;div class="js-render-enrichment-target"&gt;
    &lt;div class="render-plaintext-hidden"&gt;
      &lt;pre&gt;flowchart LR
    Client[Cliente ou teste] --&amp;gt; Keycloak[Keycloak OIDC]
    Client --&amp;gt; LedgerApi[LedgerService.Api]
    Client --&amp;gt; BalanceApi[BalanceService.Api]
    Client --&amp;gt; TransferApi[TransferService.Api]
    Client --&amp;gt; PaymentApi[PaymentService.Api]
    Client --&amp;gt; IdentityApi[IdentityService.Api]
    Client --&amp;gt; AuditApi[AuditService.Api]
    LedgerApi --&amp;gt;&lt;/pre&gt;…&lt;/div&gt;
&lt;/div&gt;&lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="gh-btn-container"&gt;&lt;a class="gh-btn" href="https://github.com/rodri-oliveira-dev/poc-arquitetura" rel="noopener noreferrer"&gt;View on GitHub&lt;/a&gt;&lt;/div&gt;
&lt;/div&gt;


&lt;p&gt;There is still plenty I want to experiment with.&lt;/p&gt;

&lt;p&gt;And that is probably the part I enjoy most about this kind of architecture work: once failure stops being treated as an exceptional event and becomes part of the design, the questions get much more interesting.&lt;/p&gt;

</description>
      <category>distributedsystems</category>
      <category>architecture</category>
      <category>dotnet</category>
      <category>kafka</category>
    </item>
    <item>
      <title>How I organized security policies, reusable workflows, .NET maintenance, and AI agent governance across my GitHub repositories.</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Tue, 29 Sep 2026 14:30:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/how-i-organized-security-policies-reusable-workflows-net-maintenance-and-ai-agent-governance-4jgg</link>
      <guid>https://dev.to/rodri-oliveira-dev/how-i-organized-security-policies-reusable-workflows-net-maintenance-and-ai-agent-governance-4jgg</guid>
      <description>&lt;h2&gt;
  
  
  The challenge of maintaining multiple repositories
&lt;/h2&gt;

&lt;p&gt;When you maintain one or two repositories, duplicating a few configuration files doesn't seem like a big deal.&lt;/p&gt;

&lt;p&gt;A &lt;code&gt;CONTRIBUTING.md&lt;/code&gt; here, a pull request template there, some security policies, and a few GitHub Actions workflows. Everything works, and development continues.&lt;/p&gt;

&lt;p&gt;The problem becomes more noticeable as the number of repositories grows.&lt;/p&gt;

&lt;p&gt;A security improvement implemented in one project never reaches the others. Workflows evolve, but several repositories continue using older versions. Contribution guidelines become inconsistent, and dependencies require individual updates.&lt;/p&gt;

&lt;p&gt;Over time, these differences create configuration drift.&lt;/p&gt;

&lt;p&gt;I started addressing this problem by evolving my &lt;code&gt;.github&lt;/code&gt; repository into a central governance and automation layer for the projects I maintain.&lt;/p&gt;

&lt;p&gt;The goal wasn't to move every configuration into a single repository or eliminate each project's autonomy. I wanted to establish shared standards, reduce duplication, and automate recurring maintenance tasks while preserving repository-specific requirements.&lt;/p&gt;

&lt;p&gt;In this article, I'll explain how that structure works, what I implemented, and the architectural decisions behind it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What makes a &lt;code&gt;.github&lt;/code&gt; repository special?
&lt;/h2&gt;

&lt;p&gt;GitHub provides special behavior for public repositories named &lt;code&gt;.github&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;They can contain default community health files that GitHub uses across other public repositories belonging to the same account or organization.&lt;/p&gt;

&lt;p&gt;This includes files such as &lt;code&gt;CONTRIBUTING.md&lt;/code&gt;, &lt;code&gt;CODE_OF_CONDUCT.md&lt;/code&gt;, &lt;code&gt;SECURITY.md&lt;/code&gt;, &lt;code&gt;SUPPORT.md&lt;/code&gt;, issue templates, and pull request templates.&lt;/p&gt;

&lt;p&gt;When a repository doesn't provide its own version of a supported file, GitHub can use the corresponding default.&lt;/p&gt;

&lt;p&gt;The important part is that local configurations take precedence.&lt;/p&gt;

&lt;p&gt;If a project requires a different security policy or pull request template, it can maintain its own version.&lt;/p&gt;

&lt;p&gt;This creates a useful governance model: shared defaults with local overrides when necessary.&lt;/p&gt;

&lt;p&gt;I initially used this functionality to provide consistent contribution guidelines, security policies, and support documentation.&lt;/p&gt;

&lt;p&gt;As my projects evolved, I realized several other responsibilities could benefit from a similar approach.&lt;/p&gt;

&lt;h2&gt;
  
  
  From shared files to a governance layer
&lt;/h2&gt;

&lt;p&gt;Maintaining multiple repositories involves more than keeping documentation consistent.&lt;/p&gt;

&lt;p&gt;Dependency updates, SDK versions, security checks, pipeline validation, and recurring maintenance tasks often require similar implementations.&lt;/p&gt;

&lt;p&gt;Instead of handling each concern independently, I started using the &lt;code&gt;.github&lt;/code&gt; repository as a coordination point.&lt;/p&gt;

&lt;p&gt;Today, it includes community health files, reusable workflows, maintenance automation, security policies, validation scripts, and a versioned registry of instructions and skills for development agents.&lt;/p&gt;

&lt;p&gt;There is an important distinction here.&lt;/p&gt;

&lt;p&gt;GitHub doesn't automatically distribute every file stored in a &lt;code&gt;.github&lt;/code&gt; repository to other projects.&lt;/p&gt;

&lt;p&gt;Native inheritance applies only to specific supported features. Workflows, Dependabot configurations, custom scripts, and AI agent instructions require their own reuse or distribution mechanisms.&lt;/p&gt;

&lt;p&gt;My implementation combines native GitHub features with automation built using GitHub Actions and the GitHub API.&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;.github&lt;/code&gt; repository provides the foundation, but the broader governance model is something we build on top of it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reusable workflows and centralized policies
&lt;/h2&gt;

&lt;p&gt;One of the first responsibilities I centralized was the implementation of policies used by multiple CI/CD pipelines.&lt;/p&gt;

&lt;p&gt;GitHub Actions supports reusable workflows, allowing one workflow to call another.&lt;/p&gt;

&lt;p&gt;Imagine several repositories that need to perform the same security scan.&lt;/p&gt;

&lt;p&gt;Instead of maintaining independent copies of the scanning logic, we can expose a reusable workflow that each project calls from its own pipeline.&lt;/p&gt;

&lt;p&gt;A simplified example:&lt;/p&gt;

&lt;p&gt;YAML&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Security&lt;/span&gt;

&lt;span class="na"&gt;on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;pull_request&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;

&lt;span class="na"&gt;jobs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;security&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;owner/.github/.github/workflows/reusable-secret-scan.yml@v1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Here, &lt;code&gt;owner&lt;/code&gt; represents the account maintaining the central repository, and &lt;code&gt;v1&lt;/code&gt; represents a published version of the reusable workflow.&lt;/p&gt;

&lt;p&gt;The consuming repository decides when the scan runs and how it fits into its development process.&lt;/p&gt;

&lt;p&gt;The central repository maintains the shared implementation.&lt;/p&gt;

&lt;p&gt;The application still owns its pipeline. The central repository owns the shared policy implementation.&lt;/p&gt;

&lt;p&gt;In my project, one example is a reusable secret-scanning workflow designed to detect potential credentials and other sensitive information in Git history, independently of the programming language used by the consumer.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why versioning matters
&lt;/h3&gt;

&lt;p&gt;When multiple repositories depend on a shared workflow, changes can affect several consumers.&lt;/p&gt;

&lt;p&gt;Pointing every repository to the central &lt;code&gt;main&lt;/code&gt; branch may be convenient, but it creates a dependency on its latest state.&lt;/p&gt;

&lt;p&gt;That's why I implemented an explicit versioning and release process.&lt;/p&gt;

&lt;p&gt;The strategy supports semantic versioning, major-version references, and full commit SHA references when strict reproducibility is required.&lt;/p&gt;

&lt;p&gt;A major-version reference allows consumers to receive compatible updates within that release channel. A full commit SHA identifies the exact code that will execute.&lt;/p&gt;

&lt;p&gt;Reusing code doesn't eliminate coupling. It requires us to manage that coupling deliberately.&lt;/p&gt;

&lt;p&gt;Versioning, compatibility, and change review are essential parts of maintaining shared automation.&lt;/p&gt;

&lt;h2&gt;
  
  
  Securing the automation itself
&lt;/h2&gt;

&lt;p&gt;When a repository starts coordinating operations across other repositories, its role changes.&lt;/p&gt;

&lt;p&gt;It can execute code, access repository metadata, create branches, and open pull requests.&lt;/p&gt;

&lt;p&gt;This introduces additional security considerations.&lt;/p&gt;

&lt;p&gt;One practice I adopted was pinning external GitHub Actions to their full commit SHA, identifying the exact code being executed.&lt;/p&gt;

&lt;p&gt;I also configured Dependabot to monitor GitHub Actions dependencies and propose updates through pull requests.&lt;/p&gt;

&lt;p&gt;However, automated updates don't mean automated merges.&lt;/p&gt;

&lt;p&gt;Updating an Action changes the code executed by a pipeline. Depending on the workflow, that code may have access to tokens, secrets, or other sensitive resources.&lt;/p&gt;

&lt;p&gt;For this reason, human review remains part of the process.&lt;/p&gt;

&lt;h3&gt;
  
  
  GitHub Apps and least privilege
&lt;/h3&gt;

&lt;p&gt;I also use a GitHub App for operations involving multiple repositories.&lt;/p&gt;

&lt;p&gt;Instead of relying on a long-lived personal access token with broad permissions, the automation uses short-lived installation access tokens.&lt;/p&gt;

&lt;p&gt;This allows permissions to be restricted to the operations the application actually needs.&lt;/p&gt;

&lt;p&gt;For example, my .NET repository inventory separates repository discovery from code inspection.&lt;/p&gt;

&lt;p&gt;The discovery stage uses credentials to identify eligible repositories. The inspection stage receives only the information needed to process selected public repositories, without receiving the GitHub App's private key.&lt;/p&gt;

&lt;p&gt;This reduces credential exposure during code inspection.&lt;/p&gt;

&lt;p&gt;It's a practical application of the principle of least privilege: each component receives only the access required to perform its responsibility.&lt;/p&gt;

&lt;h2&gt;
  
  
  Automating .NET repository maintenance
&lt;/h2&gt;

&lt;p&gt;Beyond shared policies, I implemented automation to help maintain my .NET repositories.&lt;/p&gt;

&lt;p&gt;One example is SDK version synchronization.&lt;/p&gt;

&lt;p&gt;The workflow identifies eligible repositories, checks their root-level &lt;code&gt;global.json&lt;/code&gt; files, and determines whether an update is available under the configured compatibility policy.&lt;/p&gt;

&lt;p&gt;When an applicable update is found, it prepares the change in a branch and opens a pull request.&lt;/p&gt;

&lt;p&gt;The automation doesn't merge directly into the default branch. Each repository retains its normal review and integration process.&lt;/p&gt;

&lt;h3&gt;
  
  
  Building a centralized .NET inventory
&lt;/h3&gt;

&lt;p&gt;Another workflow produces an inventory of .NET projects across repositories accessible to the configured GitHub App.&lt;/p&gt;

&lt;p&gt;The goal isn't to modify projects but to obtain a consolidated view of their metadata.&lt;/p&gt;

&lt;p&gt;The inventory uses DotNetRepoInspector to inspect .NET repositories using effective MSBuild metadata rather than relying exclusively on direct &lt;code&gt;.csproj&lt;/code&gt; parsing.&lt;/p&gt;

&lt;p&gt;This integration illustrates an architectural principle I wanted to preserve.&lt;/p&gt;

&lt;p&gt;Each project retains a specific responsibility.&lt;/p&gt;

&lt;p&gt;DotNetRepoInspector performs the inspection. The &lt;code&gt;.github&lt;/code&gt; repository coordinates execution across multiple repositories and consolidates the results.&lt;/p&gt;

&lt;p&gt;I didn't need to move the inspection implementation into the central repository to reuse its capabilities.&lt;/p&gt;

&lt;h2&gt;
  
  
  Automation needs engineering, too
&lt;/h2&gt;

&lt;p&gt;Maintenance scripts often start small.&lt;/p&gt;

&lt;p&gt;A few lines of Bash solve a problem, become part of a workflow, and continue running for months.&lt;/p&gt;

&lt;p&gt;Things change when that same script starts modifying multiple repositories.&lt;/p&gt;

&lt;p&gt;At that point, it deserves the same engineering attention we give other software components.&lt;/p&gt;

&lt;p&gt;That's why my &lt;code&gt;.github&lt;/code&gt; repository includes regression tests, contract validation, and quality checks using tools such as &lt;code&gt;actionlint&lt;/code&gt; and &lt;code&gt;ShellCheck&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;I also implemented mechanisms for handling failures during batch operations.&lt;/p&gt;

&lt;p&gt;If an update fails for one repository, processing can continue for the remaining repositories when it's safe to do so. Failures must still be explicitly reported.&lt;/p&gt;

&lt;p&gt;Continuing after a recoverable error shouldn't mean hiding that error.&lt;/p&gt;

&lt;h3&gt;
  
  
  Automation branch ownership
&lt;/h3&gt;

&lt;p&gt;Another concern involves the ownership of branches created by automation.&lt;/p&gt;

&lt;p&gt;The existence of a branch named &lt;code&gt;chore/sync-dotnet-sdk&lt;/code&gt; doesn't automatically mean a workflow can assume that branch belongs to it.&lt;/p&gt;

&lt;p&gt;Someone may have created it manually, or it may contain changes that shouldn't be overwritten.&lt;/p&gt;

&lt;p&gt;For that reason, the automation performs additional ownership and pull request state checks before reusing or updating an existing branch.&lt;/p&gt;

&lt;p&gt;These safeguards become particularly relevant when scripts can modify multiple repositories.&lt;/p&gt;

&lt;h2&gt;
  
  
  Managing shared instructions for AI development agents
&lt;/h2&gt;

&lt;p&gt;More recently, I encountered another form of shared configuration: instructions used by AI development agents.&lt;/p&gt;

&lt;p&gt;Tools capable of inspecting code, implementing issues, and reviewing pull requests need to understand the rules and conventions of the projects they work on.&lt;/p&gt;

&lt;p&gt;These instructions may cover architecture, testing strategies, security policies, and implementation procedures.&lt;/p&gt;

&lt;p&gt;When maintaining multiple repositories, some instructions naturally overlap.&lt;/p&gt;

&lt;p&gt;Copying the same files between projects, however, creates the same configuration drift problem we see with workflows.&lt;/p&gt;

&lt;p&gt;To address this, I created an &lt;code&gt;agent-governance&lt;/code&gt; directory inside the central repository.&lt;/p&gt;

&lt;p&gt;It contains shared instructions, profiles, reusable skills, a manifest, and its own version file.&lt;/p&gt;

&lt;p&gt;The available skills cover activities such as bug investigation, issue implementation, pull request review, security analysis, refactoring, and test coverage analysis.&lt;/p&gt;

&lt;p&gt;The goal is to provide shared instructions while allowing individual projects to extend them according to their specific needs.&lt;/p&gt;

&lt;h3&gt;
  
  
  Distributing instructions to consuming repositories
&lt;/h3&gt;

&lt;p&gt;Unlike community health files, AI agent instructions aren't automatically inherited from the &lt;code&gt;.github&lt;/code&gt; repository.&lt;/p&gt;

&lt;p&gt;A separate process is required to manage their evolution and distribution.&lt;/p&gt;

&lt;p&gt;I implemented workflows that validate the central registry, synchronize selected skills from a controlled upstream source, and distribute approved updates to consuming repositories.&lt;/p&gt;

&lt;p&gt;When the automation identifies a difference between the approved central version and the version used by a consumer, it can prepare a pull request containing the update.&lt;/p&gt;

&lt;p&gt;This preserves change review, version history, and the ability to maintain repository-specific instructions.&lt;/p&gt;

&lt;p&gt;The same principle used for reusable workflows applies here:&lt;/p&gt;

&lt;p&gt;Centralize what is shared without removing control from the consuming projects.&lt;/p&gt;

&lt;h2&gt;
  
  
  What do we gain from this approach?
&lt;/h2&gt;

&lt;p&gt;The main benefit isn't simply having fewer files.&lt;/p&gt;

&lt;p&gt;It's reducing the number of places where the same decision must be maintained.&lt;/p&gt;

&lt;p&gt;When a security policy has several independent copies, each copy can evolve differently.&lt;/p&gt;

&lt;p&gt;With a central source and a controlled mechanism for reuse or distribution, the problem changes.&lt;/p&gt;

&lt;p&gt;Instead of asking:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;How do I keep ten configurations identical?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;We can ask:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;How do I maintain one shared policy while preserving compatibility with its consumers?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The second problem isn't trivial, but it's more explicit and easier to manage systematically.&lt;/p&gt;

&lt;p&gt;It also becomes easier to distinguish responsibilities that belong to the broader repository ecosystem from those that should remain within individual projects.&lt;/p&gt;

&lt;p&gt;Not every configuration should be centralized.&lt;/p&gt;

&lt;p&gt;A workflow supporting a specific application's deployment process may have little value for other repositories. Similarly, some AI agent instructions may depend on architectural decisions unique to a particular project.&lt;/p&gt;

&lt;p&gt;Centralizing everything can introduce unnecessary coupling.&lt;/p&gt;

&lt;p&gt;That's why I treat the &lt;code&gt;.github&lt;/code&gt; repository as a shared governance layer rather than a universal configuration repository.&lt;/p&gt;

&lt;h2&gt;
  
  
  The trade-offs of centralization
&lt;/h2&gt;

&lt;p&gt;A centralized structure introduces responsibilities of its own.&lt;/p&gt;

&lt;p&gt;An incorrect change to a shared policy may affect multiple repositories. An incompatible workflow update can break consuming pipelines. Automation with excessive permissions can increase the impact of a security incident.&lt;/p&gt;

&lt;p&gt;This is why versioning, validation, review, and access control need to evolve alongside centralization.&lt;/p&gt;

&lt;p&gt;Different types of configuration also require different sharing mechanisms.&lt;/p&gt;

&lt;p&gt;Community health files can use GitHub's native default-file behavior. Reusable workflows must be explicitly called by consumers. Other configurations require dedicated distribution processes.&lt;/p&gt;

&lt;p&gt;Each mechanism has its own limitations.&lt;/p&gt;

&lt;p&gt;The goal isn't to eliminate every difference between projects. It's to make sure those differences are intentional rather than the result of neglected maintenance.&lt;/p&gt;

&lt;h2&gt;
  
  
  Key takeaways
&lt;/h2&gt;

&lt;p&gt;Building this repository reinforced an important architectural principle: centralization and autonomy don't have to be opposing concepts.&lt;/p&gt;

&lt;p&gt;We can establish shared standards without preventing individual projects from making their own decisions.&lt;/p&gt;

&lt;p&gt;Reuse also requires governance. Shared workflows need versioning, automation needs testing, and distribution mechanisms need traceability and review.&lt;/p&gt;

&lt;p&gt;Security deserves particular attention when a tool operates across multiple repositories. Short-lived credentials, restricted permissions, and separation of responsibilities help reduce the risks associated with centralized automation.&lt;/p&gt;

&lt;p&gt;Finally, AI development instructions should be treated like other engineering artifacts. They require maintenance, versioning, and controlled update mechanisms.&lt;/p&gt;

&lt;p&gt;The main lesson is simple: centralize policies that are genuinely shared, and keep project-specific decisions within the projects that own them.&lt;/p&gt;

&lt;p&gt;Even a personal portfolio can provide a practical environment for exploring Platform Engineering, Developer Experience, and software governance.&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;p&gt;If you want to explore these concepts, the official GitHub documentation is a good starting point.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file" rel="noopener noreferrer"&gt;Creating a default community health file&lt;/a&gt;&amp;nbsp; explains which files can be shared through a &lt;code&gt;.github&lt;/code&gt; repository and how local configurations take precedence.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://docs.github.com/en/actions/sharing-automations/reusing-workflows" rel="noopener noreferrer"&gt;Reusing workflows&lt;/a&gt;&amp;nbsp; covers reusable GitHub Actions workflows, including inputs, secrets, outputs, and reuse limitations.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://docs.github.com/en/actions/reference/security/secure-use" rel="noopener noreferrer"&gt;Secure use reference&lt;/a&gt;&amp;nbsp; describes security considerations for GitHub Actions, including permissions, credentials, and third-party Actions.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://docs.github.com/en/apps/creating-github-apps" rel="noopener noreferrer"&gt;Creating GitHub Apps&lt;/a&gt;&amp;nbsp; provides information about application authentication, installation permissions, and access tokens.&lt;/p&gt;

&lt;p&gt;For a practical implementation, explore the projects linked at the beginning of this article. Their code and documentation are publicly available for anyone who wants to study the implementation, adapt individual components, or contribute.&lt;/p&gt;

&lt;p&gt;If you found this project useful or it gave you an idea for your own repositories, consider leaving a ⭐ on the &lt;a href="https://github.com/rodri-oliveira-dev/.github" rel="noopener noreferrer"&gt;&lt;code&gt;.github&lt;/code&gt; repository&lt;/a&gt;&amp;nbsp;. It's a simple way to support the project.&lt;/p&gt;

&lt;p&gt;Projects covered in this article:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;a href="https://github.com/rodri-oliveira-dev/.github" rel="noopener noreferrer"&gt;&lt;code&gt;.github&lt;/code&gt; — Shared governance and automation&lt;/a&gt;&amp;nbsp;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector" rel="noopener noreferrer"&gt;DotNetRepoInspector — .NET repository inspection and inventory&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>github</category>
      <category>devops</category>
      <category>githubactions</category>
      <category>platformengineering</category>
    </item>
    <item>
      <title>ADR: Recording the Why Behind Decisions and How ADR Guard Helps Keep Architectural History Reliable</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Tue, 22 Sep 2026 15:00:00 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/adr-recording-the-why-behind-decisions-and-how-adr-guard-helps-keep-architectural-history-reliable-10cb</link>
      <guid>https://dev.to/rodri-oliveira-dev/adr-recording-the-why-behind-decisions-and-how-adr-guard-helps-keep-architectural-history-reliable-10cb</guid>
      <description>&lt;p&gt;In projects that live for more than a few years, there is one question that comes up surprisingly often:&lt;/p&gt;

&lt;p&gt;“Why did we build it this way?”&lt;/p&gt;

&lt;p&gt;Maybe it was the decision to choose PostgreSQL instead of MongoDB. Maybe the team decided to use messaging, adopt microservices, keep a modular monolith, introduce distributed caching, or standardize an observability strategy.&lt;/p&gt;

&lt;p&gt;The code usually tells us &lt;strong&gt;what was implemented&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Git tells us &lt;strong&gt;when it changed&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;But neither necessarily explains &lt;strong&gt;why the decision was made&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That is exactly where Architecture Decision Records, or simply &lt;strong&gt;ADRs&lt;/strong&gt;, come in.&lt;/p&gt;

&lt;h2&gt;
  
  
  The problem is not forgetting the technology. It is forgetting the context
&lt;/h2&gt;

&lt;p&gt;Architectural decisions rarely happen in a vacuum.&lt;/p&gt;

&lt;p&gt;Imagine that, a few years ago, a team decided not to use a particular technology. Someone joining the project today might look at the architecture and think:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“This doesn’t make sense. We could simplify all of this by using X.”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Maybe they could.&lt;/p&gt;

&lt;p&gt;But perhaps X had been rejected because the system needed to satisfy a regulatory constraint. Maybe the team did not yet have enough operational maturity. Maybe licensing was a problem. Or perhaps, at the time, the technology simply did not meet an important requirement.&lt;/p&gt;

&lt;p&gt;Without that context, old decisions can look arbitrary.&lt;/p&gt;

&lt;p&gt;Michael Nygard helped popularize ADRs around this exact idea: useful architecture documentation does not have to be a massive document describing the entire system. Small, independent records that explain individual decisions have a much better chance of remaining understandable and useful over time.&lt;/p&gt;

&lt;p&gt;An ADR is essentially a &lt;strong&gt;snapshot of architectural reasoning at a particular point in time&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;It does not try to explain the entire architecture.&lt;/p&gt;

&lt;p&gt;It explains one decision.&lt;/p&gt;

&lt;h2&gt;
  
  
  What goes into an ADR?
&lt;/h2&gt;

&lt;p&gt;There are several ADR templates, but one of the best-known formats is intentionally simple.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Context&lt;/strong&gt; explains the problem, constraints, and forces that created the need for a decision.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Decision&lt;/strong&gt; records what was decided.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Consequences&lt;/strong&gt; describe what changes because of that choice, including benefits, costs, and trade-offs.&lt;/p&gt;

&lt;p&gt;There is usually also a &lt;strong&gt;Status&lt;/strong&gt;, indicating whether the decision is being proposed, has been accepted, has been deprecated, or has been superseded by another decision.&lt;/p&gt;

&lt;p&gt;AWS, for example, recommends using ADRs for architecturally significant decisions involving system structure, non-functional requirements, dependencies, interfaces, and construction techniques.&lt;/p&gt;

&lt;p&gt;That distinction matters because an ADR should not become a development diary.&lt;/p&gt;

&lt;p&gt;“We upgraded a library version” probably does not need an ADR.&lt;/p&gt;

&lt;p&gt;“We standardized every service in the organization on a specific authentication strategy” probably does.&lt;/p&gt;

&lt;p&gt;A useful question is:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Does this decision significantly affect how the system will be built, operated, or evolved?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If the answer is yes, there is probably an architectural decision worth recording.&lt;/p&gt;

&lt;h2&gt;
  
  
  ADRs are less about documentation and more about institutional memory
&lt;/h2&gt;

&lt;p&gt;As ADRs accumulate, they form what is often called a &lt;strong&gt;decision log&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That history becomes especially valuable as people join and leave teams.&lt;/p&gt;

&lt;p&gt;Instead of depending on the one developer who “remembers why we did that in 2023,” the context becomes part of the repository itself.&lt;/p&gt;

&lt;p&gt;There is another benefit that is less obvious: ADRs reduce repeated discussions.&lt;/p&gt;

&lt;p&gt;Without a record, a team can debate the same architectural question multiple times over the years. Someone proposes a technology, the team discusses it, decides against it, and six months later someone else reopens exactly the same discussion because the original reasoning was never documented.&lt;/p&gt;

&lt;p&gt;With an ADR, the conversation can start several steps ahead:&lt;/p&gt;

&lt;p&gt;“We made this decision for these reasons. Have any of those assumptions changed?”&lt;/p&gt;

&lt;p&gt;That is a much better discussion.&lt;/p&gt;

&lt;h2&gt;
  
  
  When the ADRs themselves become a problem
&lt;/h2&gt;

&lt;p&gt;Adopting ADRs sounds easy: create a &lt;code&gt;docs/adr&lt;/code&gt; directory, add a few Markdown files, and you are done.&lt;/p&gt;

&lt;p&gt;In practice, small inconsistencies begin to appear over time.&lt;/p&gt;

&lt;p&gt;One file is called &lt;code&gt;0003-use-redis.md&lt;/code&gt;, another is called &lt;code&gt;adr4-rabbitmq.md&lt;/code&gt;. One ADR uses the status &lt;code&gt;Approved&lt;/code&gt;, another uses &lt;code&gt;Accepted&lt;/code&gt;. Some decisions have no consequences section. Two files accidentally reuse the same ID. One ADR says it was superseded by another decision, but the referenced file no longer exists.&lt;/p&gt;

&lt;p&gt;And perhaps the most common problem: someone creates a manually maintained ADR index that stops being updated after a few months.&lt;/p&gt;

&lt;p&gt;Individually, none of these problems seems particularly serious.&lt;/p&gt;

&lt;p&gt;Together, however, they slowly make the documentation less trustworthy.&lt;/p&gt;

&lt;p&gt;That is exactly the space &lt;strong&gt;&lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard&lt;/a&gt;&lt;/strong&gt; is designed to address.&lt;/p&gt;

&lt;h2&gt;
  
  
  ADR Guard: treating ADRs as verifiable artifacts
&lt;/h2&gt;

&lt;p&gt;ADR Guard is a .NET command-line tool for validating and indexing Architecture Decision Records.&lt;/p&gt;

&lt;p&gt;The idea is straightforward: if certain conventions matter to your architectural documentation, they do not have to remain informal recommendations buried in a README.&lt;/p&gt;

&lt;p&gt;They can become &lt;strong&gt;automatically verifiable invariants&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;By default, ADR Guard expects files such as:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;0001-use-postgresql.md
0002-adopt-opentelemetry.md
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And a structure based on the classic ADR format:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# Use PostgreSQL&lt;/span&gt;

&lt;span class="gu"&gt;## Status&lt;/span&gt;

Accepted

&lt;span class="gu"&gt;## Context&lt;/span&gt;

We need a relational database.

&lt;span class="gu"&gt;## Decision&lt;/span&gt;

Use PostgreSQL.

&lt;span class="gu"&gt;## Consequences&lt;/span&gt;

The team will need operational knowledge of PostgreSQL.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The command:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;adr-guard check docs/adr
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;analyzes the records and validates filenames, IDs, titles, statuses, required sections, and relationships between ADRs.&lt;/p&gt;

&lt;p&gt;The tool currently exposes stable validation codes from &lt;code&gt;ADR001&lt;/code&gt; through &lt;code&gt;ADR009&lt;/code&gt;, covering problems such as duplicate IDs, broken relative references, missing required sections, and &lt;code&gt;Superseded&lt;/code&gt; ADRs that do not correctly reference the decision that replaced them.&lt;/p&gt;

&lt;p&gt;That may sound like a small detail, but stable validation codes make the tool especially useful for automation.&lt;/p&gt;

&lt;h2&gt;
  
  
  The real benefit appears in CI
&lt;/h2&gt;

&lt;p&gt;Running ADR Guard manually is useful.&lt;/p&gt;

&lt;p&gt;Running it in the pipeline is where things become more interesting.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Validate ADRs&lt;/span&gt;
  &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;adr-guard check docs/adr&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;At that point, architectural documentation conventions become part of the same quality workflow already used for source code.&lt;/p&gt;

&lt;p&gt;A pull request that breaks a link between architectural decisions can fail.&lt;/p&gt;

&lt;p&gt;An incomplete ADR can fail.&lt;/p&gt;

&lt;p&gt;Two ADRs using the same identifier can fail.&lt;/p&gt;

&lt;p&gt;Of course, this does not turn architecture into code. ADR Guard cannot tell you whether Kafka is a better architectural choice than RabbitMQ.&lt;/p&gt;

&lt;p&gt;But it can verify something much more objective:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Is the record of that decision still structurally consistent?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;That separation matters.&lt;/p&gt;

&lt;p&gt;Automate what is mechanical so that human attention can remain focused on what actually requires judgment.&lt;/p&gt;

&lt;h2&gt;
  
  
  The index no longer has to be maintained manually
&lt;/h2&gt;

&lt;p&gt;ADR Guard also provides:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;adr-guard index docs/adr
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The command validates the ADR set first and only then generates a deterministic Markdown index.&lt;/p&gt;

&lt;p&gt;That order is intentional.&lt;/p&gt;

&lt;p&gt;ADR Guard itself contains an ADR explaining this choice: generating an index from invalid documents could make an inconsistent set of decisions look authoritative.&lt;/p&gt;

&lt;p&gt;If validation fails, the existing index is left untouched.&lt;/p&gt;

&lt;p&gt;If nothing has changed, the file is not rewritten unnecessarily.&lt;/p&gt;

&lt;p&gt;The result may seem small, but it removes one more manual maintenance task that would otherwise eventually be forgotten.&lt;/p&gt;

&lt;h2&gt;
  
  
  And then AI enters the picture with clear boundaries
&lt;/h2&gt;

&lt;p&gt;One of the more interesting capabilities added to the project is the &lt;code&gt;draft&lt;/code&gt; command.&lt;/p&gt;

&lt;p&gt;ADR Guard can use OpenAI, Anthropic, Gemini, or an OpenAI-compatible endpoint to help generate an initial ADR draft.&lt;/p&gt;

&lt;p&gt;But there is an important architectural principle behind the implementation:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AI does not make architectural decisions on behalf of the team.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Every AI-generated ADR is forced to use the &lt;code&gt;Proposed&lt;/code&gt; status.&lt;/p&gt;

&lt;p&gt;ADR Guard owns the final document structure, validates the generated result, and leaves the transition to &lt;code&gt;Accepted&lt;/code&gt; under human control.&lt;/p&gt;

&lt;p&gt;That distinction is increasingly important.&lt;/p&gt;

&lt;p&gt;Using AI to accelerate documentation is very different from delegating architectural authority to a model.&lt;/p&gt;

&lt;p&gt;The project also deliberately avoids silently ingesting the entire repository.&lt;/p&gt;

&lt;p&gt;Additional context must be explicitly provided, and existing ADRs are only sent to the configured AI provider when &lt;code&gt;--include-existing-adrs&lt;/code&gt; is enabled.&lt;/p&gt;

&lt;p&gt;There is also a preview mode:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nt"&gt;--dry-run&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;which allows the tool to generate, assemble, and validate the ADR without writing anything to disk.&lt;/p&gt;

&lt;p&gt;It is a sensible approach to AI in engineering:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;assistance rather than unrestricted autonomy&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What ADR Guard deliberately does not do
&lt;/h2&gt;

&lt;p&gt;Understanding what a tool does not do can be just as important as understanding what it does.&lt;/p&gt;

&lt;p&gt;ADR Guard does not automatically analyze a Git diff and decide that a change requires an ADR.&lt;/p&gt;

&lt;p&gt;It does not scan the entire source tree looking for architectural decisions.&lt;/p&gt;

&lt;p&gt;It does not perform RAG over the repository.&lt;/p&gt;

&lt;p&gt;It does not automatically accept architectural decisions.&lt;/p&gt;

&lt;p&gt;And it does not attempt to judge whether the recorded decision is architecturally sound.&lt;/p&gt;

&lt;p&gt;That means one responsibility remains firmly with the team:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;recognizing when a decision is significant enough to be recorded.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;ADR Guard starts helping after that human decision has been made.&lt;/p&gt;

&lt;p&gt;And that is a healthy division of responsibility.&lt;/p&gt;

&lt;h2&gt;
  
  
  An interesting detail: ADR Guard uses ADRs to build ADR Guard
&lt;/h2&gt;

&lt;p&gt;The project keeps its own architectural decisions under &lt;code&gt;docs/adr&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Among the decisions currently documented are:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;using conventional Markdown ADRs;&lt;/li&gt;
&lt;li&gt;keeping the CLI free of third-party runtime dependencies;&lt;/li&gt;
&lt;li&gt;validating ADRs before generating the index;&lt;/li&gt;
&lt;li&gt;keeping AI-assisted draft generation provider-agnostic.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In other words, the project applies its own rules to itself.&lt;/p&gt;

&lt;p&gt;Beyond being a good example of dogfooding, this illustrates an important point about ADRs: they are not only for giant decisions such as “monolith versus microservices.”&lt;/p&gt;

&lt;p&gt;Choosing to keep a CLI dependency-free can also be an architectural decision when that choice affects distribution, maintenance, and future evolution.&lt;/p&gt;

&lt;h2&gt;
  
  
  ADRs should not prevent change
&lt;/h2&gt;

&lt;p&gt;This may be the most important point of all.&lt;/p&gt;

&lt;p&gt;An ADR does not exist to say:&lt;/p&gt;

&lt;p&gt;“We decided this once, so we can never change it.”&lt;/p&gt;

&lt;p&gt;Architecture has to evolve.&lt;/p&gt;

&lt;p&gt;When assumptions change, a new decision can replace the previous one. What matters is preserving the history.&lt;/p&gt;

&lt;p&gt;Instead of rewriting the past until it appears consistent with the present, create a new decision and record that it &lt;strong&gt;supersedes&lt;/strong&gt; the previous one.&lt;/p&gt;

&lt;p&gt;That sequence tells a far more useful story about the architecture than any isolated diagram.&lt;/p&gt;

&lt;h2&gt;
  
  
  Key takeaways
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Code records implementation; ADRs record intent and context.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A collection of ADRs creates architectural memory and reduces repeated discussions.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Even simple documentation can suffer from drift, inconsistencies, and broken relationships exactly the kind of problems automation can help prevent.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ADR Guard turns ADR conventions into checks that can run locally and in CI while also keeping the decision index consistent.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AI can accelerate the creation of an initial draft, but architectural decisions remain a human responsibility.&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Perhaps that combination is exactly what makes ADRs so useful.&lt;/p&gt;

&lt;p&gt;They are simple enough to remain human-readable documentation, but structured enough for tools to help keep them healthy.&lt;/p&gt;

&lt;p&gt;ADR Guard follows that philosophy.&lt;/p&gt;

&lt;p&gt;It is not intended to replace architects, code reviews, or technical discussions.&lt;/p&gt;

&lt;p&gt;Its goal is much more pragmatic:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;once a team decides to record its architectural decisions, help ensure that this history remains readable, consistent, and trustworthy as the project grows.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;p&gt;A great place to start is Michael Nygard's &lt;strong&gt;“Documenting Architecture Decisions,”&lt;/strong&gt; the article that helped popularize the modern ADR format.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;Architectural Decision Records&lt;/strong&gt; community maintains a useful collection of concepts, templates, and examples, including alternatives such as MADR for teams that want slightly more detailed records.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;AWS Prescriptive Guidance. Using architectural decision records to streamline technical decision-making&lt;/strong&gt; is also worth reading, especially for its discussion of ADR adoption, lifecycle, and team workflows.&lt;/p&gt;

&lt;p&gt;Another useful reference is &lt;strong&gt;The GDS Way, Documenting architecture decisions&lt;/strong&gt;, from the UK Government Digital Service, which presents a pragmatic approach to keeping architectural decisions close to the code.&lt;/p&gt;

&lt;p&gt;And, of course, you can explore &lt;strong&gt;&lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;ADR Guard&lt;/a&gt;&lt;/strong&gt; itself. Beyond the implementation, the ADRs maintained inside the repository provide small real-world examples of how to document not only what was decided, but also the context and consequences behind each decision.&lt;/p&gt;

&lt;h3&gt;
  
  
  References
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;Michael Nygard — &lt;strong&gt;Documenting Architecture Decisions&lt;/strong&gt;&lt;br&gt;
&lt;a href="https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions" rel="noopener noreferrer"&gt;https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Architectural Decision Records&lt;br&gt;
&lt;a href="https://adr.github.io/" rel="noopener noreferrer"&gt;https://adr.github.io/&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;AWS Prescriptive Guidance — &lt;strong&gt;Architectural Decision Records&lt;/strong&gt;&lt;br&gt;
&lt;a href="https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html" rel="noopener noreferrer"&gt;https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;The GDS Way — &lt;strong&gt;Documenting architecture decisions&lt;/strong&gt;&lt;br&gt;
&lt;a href="https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html" rel="noopener noreferrer"&gt;https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;ADR Guard — GitHub&lt;br&gt;
&lt;a href="https://github.com/rodri-oliveira-dev/adr-guard" rel="noopener noreferrer"&gt;https://github.com/rodri-oliveira-dev/adr-guard&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>architecture</category>
      <category>adr</category>
      <category>documentation</category>
      <category>dotnet</category>
    </item>
    <item>
      <title>Can Big-O Complexity Be Detected at Compile Time?</title>
      <dc:creator>Rodrigo de Oliveira</dc:creator>
      <pubDate>Thu, 17 Sep 2026 20:08:02 +0000</pubDate>
      <link>https://dev.to/rodri-oliveira-dev/can-big-o-complexity-be-detected-at-compile-time-1nk1</link>
      <guid>https://dev.to/rodri-oliveira-dev/can-big-o-complexity-be-detected-at-compile-time-1nk1</guid>
      <description>&lt;p&gt;When we learn algorithm analysis, we usually practice by looking at a piece of code and asking questions such as: how many times does this loop run? Is there another loop inside it? Does this search scan an entire collection? Does this recursion split the problem in half?&lt;/p&gt;

&lt;p&gt;After a while, we start recognizing these patterns almost automatically.&lt;/p&gt;

&lt;p&gt;A &lt;code&gt;for&lt;/code&gt; loop iterating over a collection tends to suggest O(n). Two nested loops may indicate O(n²). Binary search points us toward O(log n). An efficient sorting algorithm usually lands around O(n log n).&lt;/p&gt;

&lt;p&gt;That raises an interesting question:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;If we can recognize these patterns by reading code, could the compiler do the same?&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That is exactly the question that led me to explore building a Roslyn analyzer capable of estimating algorithmic complexity at compile time.&lt;/p&gt;

&lt;p&gt;The short answer is: &lt;strong&gt;yes, to a certain extent&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The more interesting answer is understanding where that “to a certain extent” begins.&lt;/p&gt;




&lt;h2&gt;
  
  
  Big-O does not measure how long a method takes
&lt;/h2&gt;

&lt;p&gt;Before talking about compilers, it is worth clarifying something important.&lt;/p&gt;

&lt;p&gt;Big-O does not measure time in milliseconds.&lt;/p&gt;

&lt;p&gt;When we say an algorithm is O(n²), we are not saying it is necessarily slow. We are describing how its computational cost grows as the input size increases.&lt;/p&gt;

&lt;p&gt;Consider:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Count&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;++)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;Process&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If we assume &lt;code&gt;Process&lt;/code&gt; has constant cost, we have approximately:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;T(n) = n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Therefore:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now add another loop:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;other&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;Compare&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;other&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In this case:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;T(n) = n × n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;which gives us:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n²)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Big-O ignores constants and less relevant details so we can focus mainly on &lt;strong&gt;the rate of growth&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That is why it remains useful even across completely different machines.&lt;/p&gt;

&lt;p&gt;MIT, for example, introduces asymptotic complexity and recurrences early in its algorithms curriculum precisely because they provide a language for reasoning about growth without depending on specific hardware.&lt;/p&gt;

&lt;p&gt;But that abstraction also creates the first challenge for automated analysis: to infer Big-O, we need to understand not only the syntax of the code, but also &lt;strong&gt;the meaning of the operations being executed&lt;/strong&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  The compiler knows much more about our code than it seems
&lt;/h2&gt;

&lt;p&gt;This is where Roslyn makes the idea interesting.&lt;/p&gt;

&lt;p&gt;The C# compiler does not see a source file as plain text.&lt;/p&gt;

&lt;p&gt;It builds a structured representation of the program called a &lt;strong&gt;Syntax Tree&lt;/strong&gt;. The syntax tree represents declarations, expressions, loops, method calls, conditionals, and practically every other language construct.&lt;/p&gt;

&lt;p&gt;That means an analyzer does not need to search for strings such as:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;"foreach"
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It can ask directly:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Is there a &lt;code&gt;ForEachStatementSyntax&lt;/code&gt; here?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;More importantly, Roslyn also provides a &lt;strong&gt;Semantic Model&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That difference is significant.&lt;/p&gt;

&lt;p&gt;Imagine:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Looking only at the text, we do not know very much.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;Contains&lt;/code&gt; could belong to:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;List&amp;lt;T&amp;gt;
HashSet&amp;lt;T&amp;gt;
Dictionary&amp;lt;TKey, TValue&amp;gt;
IEnumerable&amp;lt;T&amp;gt;
MyCustomCollection
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And those operations may have very different costs.&lt;/p&gt;

&lt;p&gt;The Semantic Model can resolve the actual symbol referenced by the expression and reveal types, methods, arguments, and relationships between program elements. Roslyn's own documentation explains that the syntax tree alone is not enough to determine what an identifier actually refers to; that responsibility belongs to the semantic layer.&lt;/p&gt;

&lt;p&gt;It is precisely this combination of &lt;strong&gt;syntax and semantics&lt;/strong&gt; that makes much more sophisticated analysis possible.&lt;/p&gt;




&lt;h2&gt;
  
  
  A seemingly innocent example
&lt;/h2&gt;

&lt;p&gt;Consider this code:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;otherItems&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;Process&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If &lt;code&gt;otherItems&lt;/code&gt; is a &lt;code&gt;List&amp;lt;T&amp;gt;&lt;/code&gt;, &lt;code&gt;Contains&lt;/code&gt; may scan the list looking for the element.&lt;/p&gt;

&lt;p&gt;If &lt;code&gt;items&lt;/code&gt; has &lt;code&gt;n&lt;/code&gt; elements and &lt;code&gt;otherItems&lt;/code&gt; has &lt;code&gt;m&lt;/code&gt;, we can model the cost approximately as:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n × m)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If both collections grow at roughly the same rate:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n²)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now change the data structure:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;HashSet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;otherItems&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The exact same line of code:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;otherItems&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;has a very different expected algorithmic behavior.&lt;/p&gt;

&lt;p&gt;The text barely changed.&lt;/p&gt;

&lt;p&gt;The semantics changed significantly.&lt;/p&gt;

&lt;p&gt;A complexity analyzer therefore needs to resolve the symbol and recognize known operations from the libraries being used.&lt;/p&gt;

&lt;p&gt;In &lt;a href="https://github.com/rodri-oliveira-dev/complexity-analyzers" rel="noopener noreferrer"&gt;&lt;strong&gt;ComplexityAnalysis.Analyzers&lt;/strong&gt;&lt;/a&gt;, this is one of the strategies I use: known BCL and LINQ operations are identified by the &lt;strong&gt;symbol resolved by Roslyn&lt;/strong&gt;, not simply by the method name. This prevents a custom method named &lt;code&gt;Contains&lt;/code&gt; from automatically being treated as if it were &lt;code&gt;List&amp;lt;T&amp;gt;.Contains&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;That detail may seem small, but it is exactly the kind of distinction that separates an interesting demo from a usable analysis tool.&lt;/p&gt;




&lt;h2&gt;
  
  
  Loops are the easy part
&lt;/h2&gt;

&lt;p&gt;Finding loops is relatively straightforward.&lt;/p&gt;

&lt;p&gt;The challenge begins when we need to understand what happens inside them.&lt;/p&gt;

&lt;p&gt;Consider:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;Calculate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What is the complexity?&lt;/p&gt;

&lt;p&gt;We do not know.&lt;/p&gt;

&lt;p&gt;If:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="nf"&gt;Calculate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;is O(1), then we have:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;But if &lt;code&gt;Calculate&lt;/code&gt; scans another collection of size &lt;code&gt;m&lt;/code&gt;, we may have:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n × m)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or perhaps:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n²)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;depending on the relationship between the inputs.&lt;/p&gt;

&lt;p&gt;That is why a more sophisticated analyzer needs to move beyond purely local analysis.&lt;/p&gt;




&lt;h2&gt;
  
  
  Interprocedural analysis
&lt;/h2&gt;

&lt;p&gt;This is where &lt;strong&gt;interprocedural analysis&lt;/strong&gt; comes in.&lt;/p&gt;

&lt;p&gt;Imagine:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;Process&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IEnumerable&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;Search&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;Search&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;values&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;value&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Analyzing only &lt;code&gt;Process&lt;/code&gt; is not enough.&lt;/p&gt;

&lt;p&gt;We need to follow the call to &lt;code&gt;Search&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;We can think of it like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Process
    |
    +-- loop n
            |
            +-- Search
                    |
                    +-- loop m
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Therefore:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n × m)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This kind of analysis can reveal some interesting relationships.&lt;/p&gt;

&lt;p&gt;For example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;A → B O(n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;results in:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;A O(n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;While:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;loop n → B O(n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;results approximately in:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n²)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;ComplexityAnalysis.Analyzers&lt;/code&gt; performs this kind of analysis within defined limits, following reachable methods and substituting called-method parameters with caller inputs when that can be done safely.&lt;/p&gt;

&lt;p&gt;But there is a very important word here:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;limits&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;An analyzer that runs during compilation cannot explore the application's entire call graph indefinitely.&lt;/p&gt;




&lt;h2&gt;
  
  
  The analyzer also needs to be fast
&lt;/h2&gt;

&lt;p&gt;There is an interesting irony in all of this.&lt;/p&gt;

&lt;p&gt;It would be strange to build a performance analyzer that made compilation extremely slow.&lt;/p&gt;

&lt;p&gt;Roslyn analyzers can run while we are writing code and during the build. That means analysis cost matters. Roslyn itself supports concurrent execution of analyzer actions to improve performance, provided the analyzer has been designed to operate safely in parallel.&lt;/p&gt;

&lt;p&gt;A practical tool therefore needs to enforce analysis budgets.&lt;/p&gt;

&lt;p&gt;For example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;maximum call depth = 5
methods analyzed per root = 32
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the analysis exceeds that budget, it needs to stop.&lt;/p&gt;

&lt;p&gt;That decision matters because there is a difference between:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;building a theoretically impressive analyzer&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;and:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;building an analyzer that developers are willing to keep enabled in Visual Studio.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  And then we get to recursion
&lt;/h2&gt;

&lt;p&gt;Recursion makes things even more interesting.&lt;/p&gt;

&lt;p&gt;Consider:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="nf"&gt;Factorial&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="p"&gt;*&lt;/span&gt; &lt;span class="nf"&gt;Factorial&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;We can represent its cost with a recurrence:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;T(n) = T(n - 1) + O(1)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;which gives us:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now consider divide and conquer:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;T(n) = 2T(n/2) + n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Applying the Master Theorem:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n log n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Another example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;T(n) = 3T(n/2) + n
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;results approximately in:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n^1.585)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;So an analyzer can go beyond simply counting loops. It can recognize certain recursive patterns, construct a recurrence, and attempt to solve it.&lt;/p&gt;

&lt;p&gt;In the project I have been developing, support is intentionally limited to known families: simple reduction, some exponential recurrences, forms compatible with the Master Theorem, and a restricted subset of Akra-Bazzi.&lt;/p&gt;

&lt;p&gt;The important word, once again, is &lt;strong&gt;restricted&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Because trying to solve every possible recurrence quickly takes us into very different territory.&lt;/p&gt;




&lt;h2&gt;
  
  
  So why can't we infer everything?
&lt;/h2&gt;

&lt;p&gt;This is where we reach the theoretical limit.&lt;/p&gt;

&lt;p&gt;It is tempting to imagine an analyzer that could receive any program and correctly answer:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;This method is O(1).
This one is O(log n).
This one is O(n).
This one is O(n²).
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For any arbitrary piece of code.&lt;/p&gt;

&lt;p&gt;That is not possible in general.&lt;/p&gt;

&lt;p&gt;Static program analysis runs into fundamental limits related to computability. The halting problem shows that there is no algorithm capable of correctly deciding, for every program and input, whether that program will terminate.&lt;/p&gt;

&lt;p&gt;More general results, such as Rice's theorem, show that non-trivial semantic properties of programs are undecidable in general. Cornell's program analysis material summarizes the practical consequence particularly well: static analyses need to work with &lt;strong&gt;approximations&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That completely changes the question.&lt;/p&gt;

&lt;p&gt;Instead of asking:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“How can we determine the complexity of any program?”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;we should ask:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“For which structures can we produce a sufficiently safe conclusion?”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That is a much more productive question.&lt;/p&gt;




&lt;h2&gt;
  
  
  Sometimes “I don't know” is the best answer
&lt;/h2&gt;

&lt;p&gt;This may be the principle I like most about this kind of tool.&lt;/p&gt;

&lt;p&gt;Consider:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;ExecuteSomething&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If &lt;code&gt;ExecuteSomething&lt;/code&gt; lives in an external library the analyzer knows nothing about, there are several options.&lt;/p&gt;

&lt;p&gt;It could simply assume:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(1)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;But that could be completely wrong.&lt;/p&gt;

&lt;p&gt;It could assume:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(n)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;But that would also be arbitrary.&lt;/p&gt;

&lt;p&gt;A much safer alternative is to return:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Unknown
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In other words:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“I don't have enough information to state the complexity.”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That may sound less impressive, but it is an important characteristic of serious analysis tools.&lt;/p&gt;

&lt;p&gt;Constant false positives destroy trust.&lt;/p&gt;

&lt;p&gt;After a while, developers start ignoring the analyzer.&lt;/p&gt;

&lt;p&gt;That is why I would rather have a tool miss some cases than invent certainty.&lt;/p&gt;

&lt;p&gt;There is an interesting parallel with static analysis in general: when a property cannot be determined precisely, we need to define how we want to approximate it. Compiler and program analysis courses deal directly with this trade-off between precision, decidability, and conservatism.&lt;/p&gt;




&lt;h2&gt;
  
  
  Big-O does not replace other metrics either
&lt;/h2&gt;

&lt;p&gt;Another important point: algorithmic complexity is not the same thing as code quality.&lt;/p&gt;

&lt;p&gt;A method can be:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;O(1)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;and still be almost impossible to understand.&lt;/p&gt;

&lt;p&gt;It may contain dozens of conditionals, multiple levels of nesting, too many responsibilities, and an enormous signature.&lt;/p&gt;

&lt;p&gt;That is why it makes sense to look at different metrics independently.&lt;/p&gt;

&lt;p&gt;Cyclomatic complexity attempts to represent independent control-flow paths.&lt;/p&gt;

&lt;p&gt;Cognitive Complexity attempts to approximate the effort required to understand a given flow. SonarSource created this metric specifically to address aspects of understandability that are not well represented by cyclomatic complexity alone.&lt;/p&gt;

&lt;p&gt;We can also track:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;nesting depth
NLOC
statement count
parameter count
token count
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;None of these metrics replaces the others.&lt;/p&gt;

&lt;p&gt;They answer different questions.&lt;/p&gt;

&lt;p&gt;Big-O essentially asks:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“How does cost grow with the input?”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Cognitive Complexity asks something closer to:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“How difficult is this flow to follow mentally?”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Combining those two ideas into a single score would probably create more confusion than insight.&lt;/p&gt;




&lt;h2&gt;
  
  
  Where this becomes genuinely useful
&lt;/h2&gt;

&lt;p&gt;The goal of detecting complexity at compile time should not be to attach an academic label to every method.&lt;/p&gt;

&lt;p&gt;The real value appears when we can detect &lt;strong&gt;dangerous changes in algorithmic behavior&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Imagine someone writes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;customer&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;customers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;blockedCustomers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="p"&gt;...&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;During development, the dataset is small and everything runs quickly.&lt;/p&gt;

&lt;p&gt;In production:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;customers = 100,000
blockedCustomers = 80,000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now that data structure choice starts to matter.&lt;/p&gt;

&lt;p&gt;If &lt;code&gt;blockedCustomers&lt;/code&gt; is a list, the algorithm may perform an enormous number of comparisons.&lt;/p&gt;

&lt;p&gt;Choosing a more appropriate data structure can completely change the expected behavior.&lt;/p&gt;

&lt;p&gt;The analyzer does not need to prove the system's exact performance.&lt;/p&gt;

&lt;p&gt;It needs to be able to say:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“There is a linear operation inside an iteration that depends on input size. You may want to take a closer look.”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That kind of feedback is valuable precisely because it happens &lt;strong&gt;before production, before benchmarking, and potentially even before code review&lt;/strong&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  Static analysis does not eliminate benchmarks
&lt;/h2&gt;

&lt;p&gt;It is also important not to make a promise the tool cannot keep.&lt;/p&gt;

&lt;p&gt;An O(n) method may be slower than an O(n²) method for small inputs.&lt;/p&gt;

&lt;p&gt;Allocation, cache locality, I/O, branch prediction, concurrency, GC, databases, networks, JIT compilation, and many other factors influence real-world performance.&lt;/p&gt;

&lt;p&gt;Big-O is about asymptotic growth.&lt;/p&gt;

&lt;p&gt;Benchmarking is about concrete behavior under specific conditions.&lt;/p&gt;

&lt;p&gt;Tracing and profiling show what actually happened during execution.&lt;/p&gt;

&lt;p&gt;These tools complement each other.&lt;/p&gt;

&lt;p&gt;I like to think about it this way:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Static analysis
    ↓
Where might there be a problem?

Benchmark
    ↓
What is the actual cost?

Profiling / tracing
    ↓
Where is execution time actually being spent?
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Using one does not eliminate the need for the others.&lt;/p&gt;




&lt;h2&gt;
  
  
  The compiler as an architectural feedback tool
&lt;/h2&gt;

&lt;p&gt;Exploring Big-O through Roslyn led me to a broader conclusion.&lt;/p&gt;

&lt;p&gt;Compilers do not have to exist only to transform source code into assemblies.&lt;/p&gt;

&lt;p&gt;Roslyn turns the compiler into a platform on top of which we can build tools that understand program syntax, symbols, and semantics. Microsoft itself presents this as one of the platform's core goals.&lt;/p&gt;

&lt;p&gt;That lets us move many checks closer to the moment when a decision is made.&lt;/p&gt;

&lt;p&gt;Instead of discovering certain problems in Sonar after a push, in code review a few hours later, or in production weeks later, we can provide feedback while the developer is still writing the method.&lt;/p&gt;

&lt;p&gt;That idea is particularly interesting from an architecture perspective.&lt;/p&gt;

&lt;p&gt;Whenever an architectural rule can be expressed objectively, there is a possibility of turning it into:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;analyzer
architecture test
CI rule
source generator
linter
policy
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It is a shift from passive documentation to &lt;strong&gt;executable feedback&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Not every architectural decision can or should become an automated rule.&lt;/p&gt;

&lt;p&gt;But some certainly can.&lt;/p&gt;




&lt;h2&gt;
  
  
  What I learned while exploring this idea
&lt;/h2&gt;

&lt;p&gt;The original question seemed simple:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“Can Big-O be detected at compile time?”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;After exploring the problem, I think a better formulation is:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;“Which complexity properties can we infer safely enough to provide useful feedback to developers?”&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The difference matters.&lt;/p&gt;

&lt;p&gt;We are not trying to build an oracle.&lt;/p&gt;

&lt;p&gt;We are building a conservative analysis of a known subset of the language.&lt;/p&gt;

&lt;p&gt;Loops, known operations, LINQ, certain interprocedural calls, and some families of recurrences can produce very useful results.&lt;/p&gt;

&lt;p&gt;Dynamic code, difficult-to-resolve dispatch, unknown libraries, complex data dependencies, and structures outside the known model may remain &lt;code&gt;Unknown&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;And that is fine.&lt;/p&gt;

&lt;p&gt;In tools like this, knowing &lt;strong&gt;when not to make a claim&lt;/strong&gt; is part of the quality of the analysis.&lt;/p&gt;




&lt;h2&gt;
  
  
  Key takeaways
&lt;/h2&gt;

&lt;p&gt;Big-O can be partially inferred at compile time because Roslyn provides much more than text: we have syntax trees, symbols, types, and semantic information.&lt;/p&gt;

&lt;p&gt;The problem becomes interesting when we move beyond counting loops and start understanding operations, method calls, and recurrences.&lt;/p&gt;

&lt;p&gt;There is no algorithm, however, that can perfectly determine semantic properties like these for every arbitrary program. Practical tools need to work with known subsets and conservative approximations.&lt;/p&gt;

&lt;p&gt;An &lt;code&gt;Unknown&lt;/code&gt; result can be far better than a fabricated estimate.&lt;/p&gt;

&lt;p&gt;And perhaps most importantly, Big-O analysis does not replace benchmarks, profiling, cyclomatic complexity, or Cognitive Complexity. Each technique answers a different question.&lt;/p&gt;

&lt;p&gt;The real gain is being able to move certain performance and design signals much closer to the moment when code is being written.&lt;/p&gt;




&lt;h2&gt;
  
  
  Where to go next
&lt;/h2&gt;

&lt;p&gt;For anyone who wants to explore the topic in more depth, I would recommend a few directions.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Microsoft Learn — .NET Compiler Platform SDK / Roslyn APIs&lt;/strong&gt;: start with the Syntax Tree, Semantic Model, Symbols, and Diagnostic Analyzer APIs. The official documentation even includes a complete tutorial for building an analyzer and a code fix.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;MIT OpenCourseWare — Introduction to Algorithms&lt;/strong&gt;: excellent material for strengthening your understanding of asymptotic analysis, recurrences, divide and conquer, and algorithm fundamentals.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Introduction to Algorithms — Cormen, Leiserson, Rivest, and Stein (CLRS)&lt;/strong&gt;: still one of the best references for algorithms, asymptotic analysis, and recurrences.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Compilers: Principles, Techniques, and Tools — Aho, Lam, Sethi, and Ullman&lt;/strong&gt;: useful for understanding compilers, intermediate representations, program analysis, and optimization.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cornell Program Analysis materials&lt;/strong&gt;: particularly useful for understanding data-flow analysis, conservative approximations, undecidability, and the theoretical limits of static analysis.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cognitive Complexity by SonarSource&lt;/strong&gt;: a useful read for understanding why algorithmic complexity, cyclomatic complexity, and understandability are related but distinct concerns.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you want to look at a practical implementation of these ideas, &lt;a href="https://github.com/rodri-oliveira-dev/complexity-analyzers" rel="noopener noreferrer"&gt;&lt;strong&gt;ComplexityAnalysis.Analyzers&lt;/strong&gt;&lt;/a&gt; applies this reasoning with Roslyn to Big-O analysis, interprocedural calls, selected forms of recursion, and complementary complexity metrics, always preferring &lt;code&gt;Unknown&lt;/code&gt; when a safe conclusion cannot be reached.&lt;/p&gt;

&lt;p&gt;In the end, perhaps the most interesting part of this exercise is not automatically determining whether a method is O(n) or O(n²).&lt;/p&gt;

&lt;p&gt;It is realizing how much knowledge is available at compile time, and how many engineering decisions we can turn into useful feedback before code ever reaches production.&lt;/p&gt;

</description>
      <category>csharp</category>
      <category>roslyn</category>
      <category>algorithms</category>
      <category>dotnet</category>
    </item>
  </channel>
</rss>
