DEV Community: Rodrigo de Oliveira

Dapper FluentMap Is Back: What Changed from Version 2.0 to 3.6?

Rodrigo de Oliveira — Wed, 28 Oct 2026 13:00:00 +0000

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.

Imagine a .NET application that uses Dapper to query a legacy database. In the code, we have a Customer entity with properties such as Id and Name. In the database, the columns follow a different naming convention: customer_id and customer_name.

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.

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.

Dapper FluentMap was originally created to address this kind of problem: mapping .NET properties to database columns without introducing persistence attributes into domain entities.

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.

In 2026, I took over its maintenance.

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.

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.

The First Decision: Preserve What Already Worked

A general-purpose library carries a different kind of responsibility than an application maintained by a single team.

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.

For that reason, I see compatibility as an architectural requirement, not merely a versioning concern.

In FluentMap, the traditional configuration model remains available:

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

public sealed class CustomerMap : EntityMap<Customer>
{
    public CustomerMap()
    {
        Map(x => x.Id).ToColumn("customer_id");
        Map(x => x.Name).ToColumn("customer_name");
    }
}

Registration remains familiar:

FluentMapper.Initialize(config =>
{
    config.AddMap<CustomerMap>();
});

FluentMapper.Validate();

And queries still use Dapper directly:

var customer = connection.QuerySingle<Customer>(
    "SELECT customer_id, customer_name FROM customers WHERE customer_id = @Id",
    new { Id = 10 });

FluentMap establishes the relationship between column names and entity properties. SQL execution, connection management, and basic materialization remain Dapper's responsibility.

Internally, this integration relies on Dapper's type-mapping mechanism, connected to FluentMap's global configuration.

That behavior has been preserved in the 3.x line.

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.

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.

The goal remains to complement Dapper, not replace it.

When Property Mapping Is No Longer Enough

Mapping a database column to a property solves many problems, but domain models are not always made up of simple scalar properties.

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.

FluentMap 3.x introduces specific mechanisms for these scenarios.

An entity can now map a nested property:

public sealed class CustomerMap : EntityMap<Customer>
{
    public CustomerMap()
    {
        Map(x => x.Address.City).ToColumn("city");
    }
}

To materialize that path, we use one of FluentMap's dedicated query APIs:

var customer = connection.QueryMappedSingle<Customer>(
    "SELECT 'Sao Paulo' AS city");

This distinction matters.

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.

Beyond nested objects, the 3.x line introduces mapping profiles, property converters, and explicit construction strategies through ConstructUsing(...).

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.

These features expand the available modeling options, but they also introduce decisions that developers need to make deliberately.

A Dapper TypeHandler<T>, 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.

This is a principle I try to preserve: a new capability does not automatically make an existing approach obsolete.

Global Configuration and Isolation: Two Execution Models

Another important part of FluentMap's evolution concerns configuration.

Historically, FluentMapper.Initialize(...) established a global configuration. This model is straightforward and remains suitable for applications with a single set of mappings.

However, global configuration requires attention in parallel tests, applications with multiple contexts, and scenarios where the same entity may need different mapping definitions.

The 3.x line introduces immutable configuration and isolated FluentMapRuntime instances:

var runtime = new FluentMapConfigurationBuilder()
    .AddMap<CustomerMap>()
    .Build()
    .CreateRuntime();

var customer = runtime.QueryMappedSingle<Customer>(
    connection,
    sql);

In this model, the configuration belongs to the runtime instance used to execute the query.

A separate package, FluentMap.DependencyInjection, also provides integration with .NET's dependency injection container.

But there is an important boundary: isolation applies to materialization APIs controlled by FluentMap.

Standard Dapper.Query<T>() calls continue to use Dapper's globally registered type maps, while Dommel integration remains associated with global configuration.

In other words, introducing dependency injection does not automatically eliminate global state from an application.

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.

Moving Some Work from Runtime to Compile Time

One of the most interesting changes was introducing capabilities that operate during compilation.

FluentMap now provides two additional packages: FluentMap.Analyzers and FluentMap.Generators.

Roslyn Analyzers identify certain configuration problems before the application runs. This helps detect mistakes that might otherwise surface only during initialization or query materialization.

Source Generators provide generated mapping registration and materializers for supported scenarios.

The architectural difference is that some work can move from runtime mechanisms into the compilation process, reducing dependence on reflection in those paths.

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.

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.

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.

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.

Dommel and the Meaning of Persistence Operations

The integration with Dommel has evolved as well.

In the historical version, Ignore() could end up being used as a workaround to prevent certain properties from being written to the database.

However, excluding a property from mapping is not the same as declaring that it can be read but should not participate in an INSERT or UPDATE.

The current version distinguishes these cases through dedicated persistence metadata:

Map(x => x.CreatedAt)
    .ToColumn("created_at")
    .DatabaseDefaultOnInsert();

Map(x => x.UpdatedAt)
    .ToColumn("updated_at")
    .ReadOnly();

Map(x => x.Total)
    .ToColumn("total")
    .Computed();

It is now possible to express whether a column has a database-generated default, is computed, or must be excluded from write operations.

Version 3.5.0 also introduced InsertMapped* and UpdateMapped* operations, which can apply property converters during persistence.

These operations are opt-in and do not automatically change the behavior of traditional Dommel calls.

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.

Compatibility Needs Evidence, Not Assumptions

A recurring challenge with libraries built on ADO.NET is defining what compatibility with a database actually means.

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.

In version 3.6.0, FluentMap introduced documented compatibility levels supported by mandatory integration tests against real database instances.

SQLite, SQL Server, PostgreSQL, MySQL, and MariaDB have certified coverage for both FluentMap Core and Dommel integration.

Oracle and Firebird have Core certification, but not Dommel certification.

SQL Server Compact Edition remains classified as a legacy integration without modern certification.

This separation helps prevent an expectation of compatibility from becoming a guarantee that testing cannot support.

The compatibility matrix also identifies the specific database and provider versions used during validation.

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.

Distributed packages continue to target .NET Standard 2.0, preserving compatibility with a broad range of consuming applications.

Beyond functional tests, project maintenance now includes public API compatibility checks, static analysis, code coverage, release artifacts, and automated compatibility validation.

I don't consider these secondary activities.

For an open-source library, the release process and the ability to detect regressions are part of the reliability we provide to consumers.

Should You Upgrade from Version 2.0?

For applications still using FluentMap 2.0.0, my recommendation is to start with existing behavior rather than the new features.

First, identify how mappings are registered, which Dapper and Dommel versions are installed, and whether any integrations depend on specific behaviors.

Then update FluentMap packages to the same release version, build the application, validate mappings, and run the test suite.

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.

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.

Only after validating the existing application would I consider adopting features such as isolated runtimes, advanced materialization, or Source Generators.

A successful migration does not require using every available feature.

In many cases, the best decision is simply to upgrade the library while leaving most application code unchanged.

What Bringing FluentMap Back Means

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.

But the most important aspect, in my view, is not the number of features added.

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.

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.

For FluentMap, the approach has been to preserve the historical API as the compatibility path and introduce most new behaviors as optional capabilities.

There are still limitations, particularly around global integration isolation and Native AOT support. They are part of the current contract and should remain explicit.

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.

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.

References

Architecture Decisions Shouldn't Get Lost: Introducing ADR Guard for VS Code

Rodrigo de Oliveira — Wed, 21 Oct 2026 14:00:00 +0000

There's a question almost every developer has asked while working on a mature codebase:

"Why was it built this way?"

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.

The code tells us how something was implemented. It rarely tells us why a particular approach was chosen, what alternatives were considered, or which constraints influenced the decision.

And that's a problem.

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.

This is one of the problems I wanted to address when I started building ADR Guard, an open-source tool focused on Architecture Decision Records (ADRs).

More recently, I've been working on bringing that experience directly into Visual Studio Code.

But before discussing the extension, it's worth looking at why architectural decisions deserve more attention in the first place.

Architecture Decisions Are Part of Your System's History

An Architecture Decision Record is a document that captures an important architectural decision, including its context, the approach selected, and its consequences.

The concept is straightforward.

Imagine your team decides to move from synchronous communication between services to an event-driven architecture.

At that moment, everyone probably understands why.

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.

Now imagine someone revisiting that decision two years later.

The system has evolved. The team has changed. New technologies are available, and the original constraints may no longer exist.

Without an ADR, that developer needs to reconstruct the reasoning behind the decision.

With an ADR, they have a starting point.

An ADR isn't meant to prevent architectural decisions from changing. It's meant to make those changes informed and intentional.

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.

The Real Challenge Isn't Writing ADRs

I've noticed that adopting ADRs is often easier than maintaining the practice.

Initially, everything looks promising.

The team creates a docs/adr directory, agrees on a template, and starts documenting important decisions alongside the source code.

A few months later, inconsistencies begin to appear.

Some documents are missing essential sections. Others use different formats. Certain decisions are never updated, even after significant architectural changes.

Eventually, ADRs risk becoming another collection of Markdown files that nobody remembers to consult.

I don't think the problem is necessarily a lack of discipline.

The problem is that we sometimes introduce documentation practices without considering the developer experience around them.

If creating, finding, editing, and validating architectural decisions requires too much effort, the practice becomes increasingly difficult to sustain.

Documentation needs to fit into the development workflow, not compete with it.

That idea became an important part of the ADR Guard project.

ADR Guard: Bringing Structure to Architectural Decisions

ADR Guard is an open-source tool built with .NET to help teams manage Architecture Decision Records throughout their lifecycle.

It doesn't attempt to replace Markdown or introduce a proprietary documentation platform.

ADRs remain regular files in your repository, which means they can be versioned, reviewed through pull requests, and maintained alongside the code they describe.

The CLI supports workflows such as creating records, validating their structure, organizing documentation, and performing incremental checks.

It also supports different ADR formats, including canonical ADRs and MADR 4.0.

The goal is to make architectural documentation more consistent and easier to maintain.

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.

These capabilities can be integrated into CI/CD workflows, making documentation quality part of the development process.

There is, however, an important distinction.

Validating an ADR doesn't mean approving the architectural decision itself.

A tool can verify structure, required sections, and documented conventions. It cannot replace engineering judgment, architectural discussions, or technical reviews.

And it shouldn't try to.

Bringing ADRs Into Visual Studio Code

While the CLI provides the foundation, I wanted to reduce the friction involved in everyday ADR management.

Most developers already spend a significant portion of their day inside their editor.

So why should working with architectural decisions require a completely separate experience?

That's where ADR Guard for VS Code comes in.

The extension provides a visual interface for common ADR workflows while relying on the existing ADR Guard CLI for the underlying operations.

This separation is intentional: the same core behavior can be used from the terminal, VS Code, or automation pipelines.

Finding Architectural Decisions Without Searching Through Folders

One of the first improvements is discoverability.

The ADR Guard visual dashboard provides direct access to architectural decisions and their metadata.

Instead of manually browsing Markdown files, developers can use a visual list displaying information such as ADR identifiers, titles, statuses, and file locations.

The interface supports searching, filtering by status, sorting, and opening documents directly in the editor.

Searching and filtering ADRs makes architectural context easier to discover.

There's also an ADR Explorer integrated into VS Code, providing another way to navigate records and recognized relationships.

These features might sound simple, but I believe discoverability has a direct impact on whether documentation is actually used.

A decision that's easy to find is much more likely to influence future engineering discussions.

Creating ADRs Without Memorizing Templates

Another area I wanted to improve was ADR creation.

Markdown is a great format for technical documentation, but asking every developer to remember the structure of every supported template introduces unnecessary friction.

The extension provides a visual creation form that helps guide the process.

The Minimal template focuses on the essential elements of an architectural decision.

With the Minimal template, developers can focus on three fundamental questions:

What is the context?
What decision are we making?
What are the consequences?

For decisions requiring more detailed analysis, the Extended template includes additional fields, such as decision drivers, alternatives considered, rationale, risks, and references.

The Extended template helps capture more detailed architectural reasoning and trade-offs.

The extension also supports a Markdown preview before creating the document.

The point isn't to automate architectural thinking. It's to remove repetitive tasks so developers can focus on explaining their decisions clearly.

Editing Existing Decisions Safely

Architectural decisions evolve, and documentation needs to reflect that.

The extension provides visual editing for compatible ADR documents, allowing developers to update their content without manually navigating every Markdown section.

Existing ADRs can be edited through a structured interface inside VS Code.

One detail I consider particularly important is how the extension handles external modifications.

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.

This is especially relevant in collaborative repositories where multiple developers may be working on the same documentation.

The goal is to provide convenience without sacrificing predictability or data integrity.

Making Validation Part of the Development Workflow

Another useful capability is integration with VS Code's Problems panel.

ADR validation findings appear alongside other development diagnostics in VS Code.

When an ADR violates a supported structural rule, developers can see the corresponding diagnostic without leaving the editor.

Validation can run explicitly, and automatic validation on save is available as an opt-in setting.

The extension also provides workflows for validating changed ADRs against a local Git reference and checking findings against an existing baseline.

I see this as a useful step toward making architectural documentation part of ordinary engineering feedback loops.

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.

Of course, structural consistency isn't the same thing as architectural correctness. Human review remains essential.

Architecture Governance Shouldn't Become Another Source of Friction

One concern I've had throughout this project is avoiding unnecessary complexity.

It's easy to introduce tools and processes in the name of governance, only to make developers' lives harder.

I believe architecture governance works best when its purpose is clear and its mechanisms are predictable.

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.

It also avoids silently modifying architectural documents during ordinary navigation or validation.

The developer remains responsible for deciding when records should be created or changed.

To me, this is an important principle: good engineering tools should support deliberate decisions, not hide consequential actions behind convenience.

Not Every Technical Decision Needs an ADR

I don't believe every implementation detail should become an architectural record.

That would create unnecessary bureaucracy and eventually reduce the value of the documentation.

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.

Choosing between two local variable names probably doesn't need an ADR.

Deciding how services communicate, how data ownership is defined, or why a particular persistence strategy was adopted probably deserves one.

The objective isn't to produce more documentation.

It's to preserve the context that future engineers will need to make good decisions.

Final Thoughts

Building ADR Guard has reinforced something I strongly believe about software architecture:

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.

An ADR won't solve architectural problems by itself.

But it can preserve valuable engineering context, make trade-offs visible, and provide a foundation for better technical discussions.

ADR Guard for VS Code is one more step toward making that practice easier to adopt and maintain.

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.

Do you use ADRs today? And if so, what's been the biggest challenge in keeping them useful?

Try ADR Guard

Install ADR Guard for VS Code — Get the extension from the Visual Studio Marketplace.

Official VS Code Visual Guide — Explore the interface, screenshots, and supported workflows.

ADR Guard on GitHub — Explore the source code, report issues, or contribute.

The VS Code extension uses the ADR Guard CLI, which must be installed separately. Check the official documentation for installation, compatibility, and configuration details.

GitHub Dotfiles: Treating Your Development Environment Like Code

Rodrigo de Oliveira — Wed, 14 Oct 2026 14:00:00 +0000

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.

At first, they usually live directly inside ~/.bashrc, ~/.gitconfig, random folders under ~/scripts, or maybe inside a note called something like “things to install on a new machine”.

That works surprisingly well — until you change computers.

Or start using GitHub Codespaces.

Or reinstall Linux.

Or realize that the alias you depend on every day exists on one machine but not another.

That is where dotfiles become interesting.

I maintain my development environment in a GitHub repository called dotfiles. 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.

The important part isn't the aliases themselves.

The interesting part is treating your personal development environment with some of the same engineering practices you would use in a production repository.

Dotfiles are configuration as code

On Unix-like systems, configuration files commonly start with a dot: .bashrc, .gitconfig, .vimrc, and so on. Because they are hidden by default, they became known collectively as dotfiles.

Putting them in Git gives you some immediate advantages.

You get history. You can understand why a configuration changed.

You get portability. A new environment can start from a known baseline instead of being rebuilt from memory.

And you get rollback. When an experiment with your shell configuration goes badly, git diff is a much nicer debugging tool than trying to remember what the file looked like yesterday.

But versioning dotfiles is only the first step.

The bigger question is:

What actually belongs in a personal environment repository?

That boundary turned out to be one of the most important design decisions in my setup.

Your dotfiles should not own your projects

My repository deliberately manages developer-level preferences, not project dependencies.

For example, Git behavior and shell aliases belong to the dotfiles repository. A project's .NET SDK version does not.

If a repository requires a particular .NET SDK, that decision belongs in its global.json. NuGet package versions belong in project files or Directory.Packages.props. Local .NET tools belong in .config/dotnet-tools.json.

The same principle applies to the editor. A project may recommend VS Code extensions through .vscode/extensions.json, while personal editor preferences can remain in VS Code Settings Sync.

This separation prevents a surprisingly common problem: your personal workstation configuration slowly becoming an undocumented dependency of the applications you build.

A project should still describe how it wants to be built when another developer clones it.

Your dotfiles should make you more productive while respecting that contract.

A safe installer is more important than a clever installer

The entry point of the repository is intentionally boring:

git clone https://github.com/rodri-oliveira-dev/dotfiles.git "$HOME/dotfiles"
cd "$HOME/dotfiles"
./install.sh
source "$HOME/.bashrc"
dotfiles-doctor

The interesting work happens behind install.sh.

Instead of replacing the entire ~/.bashrc, the installer adds a clearly delimited managed block. That block loads the repository's shell fragments and makes ~/.local/bin available through PATH.

The actual managed configuration lives under:

${XDG_CONFIG_HOME:-$HOME/.config}/rodri-dotfiles

The installer creates links from that stable location to the files stored in the cloned repository.

That distinction matters.

A naïve dotfiles installer might simply copy a new .bashrc 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.

This repository instead tries to own only the portion it created.

If an existing destination is not one of the symlinks the repository expects to manage, installation stops rather than replacing it.

That behavior is slightly less convenient than cp -f.

It is also much harder to regret.

Idempotency changes everything

A setup script becomes considerably more useful when running it twice produces the same result as running it once.

That is the goal here.

Running install.sh repeatedly should not keep appending blocks to .bashrc, duplicating Git configuration, or creating additional links.

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.

The repository can be configured as a GitHub Codespaces dotfiles source, allowing new Codespaces to bootstrap the personal configuration automatically.

At that point, idempotency is no longer just nice engineering hygiene.

It becomes part of the interface.

Git configuration without replacing `.gitconfig`

Git gets the same treatment.

Rather than owning the user's complete global configuration, the installer adds an include.path pointing at the managed Git configuration.

The repository currently defines defaults such as:

[init]
    defaultBranch = main

[fetch]
    prune = true

[push]
    autoSetupRemote = true

[rerere]
    enabled = true

[diff]
    algorithm = histogram

These are personal defaults, not project policies.

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.

That composability is something I now consider essential in a dotfiles repository.

Small aliases are useful. Context-aware helpers are better.

Of course, the repository still contains the usual conveniences.

For Git, I use aliases such as gs, gd, and gl. For .NET, there are shortcuts such as dr for restore, db for build, and dt for tests.

Those save keystrokes.

The more interesting commands are the repository-aware helpers.

For example:

dotnet-context

can inspect the current Git repository and report conventions such as global.json, Directory.Build.props, Directory.Packages.props, local tool manifests, and solution files.

Another command:

dotnet-repo-doctor

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.

There is also:

dotnet-deps vulnerable

for dependency diagnostics, and:

dotnet-why Microsoft.CodeAnalysis.Common

for answering one of those wonderfully annoying questions:

Why is this package even in my dependency graph?

And before pushing a change, I can run:

dotnet-verify

which coordinates restore, build, formatting verification, and tests using the repository's own configuration.

The goal is not to hide the .NET CLI.

It is to encode the repetitive discovery and safety checks that normally happen before invoking it.

Respecting `global.json` is a small but important detail

One temptation when creating a developer bootstrap repository is installing your favorite SDK and tool versions globally.

I intentionally avoided that.

Different projects may target different SDK feature bands. Your dotfiles should not silently decide that every repository on your machine needs the same one.

The helpers therefore resolve the SDK from the repository context instead of trying to impose one globally.

The same idea applies to .NET tools.

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.

This is a subtle architectural boundary, but it dramatically improves reproducibility.

Diagnostics deserve a first-class command

Automated setup is great until something becomes slightly wrong.

That is why the repository includes:

dotfiles-doctor

The doctor checks the assumptions that make the environment work: shell integration, managed symlinks, PATH, Git includes, repository hooks, helper commands, Bash, Git, and the available .NET SDK.

This is one of my favorite patterns in developer tooling.

Installation says:

Here is how the environment should look.

A doctor command says:

Here is whether it still looks that way.

That difference becomes increasingly valuable as the environment evolves.

Instead of telling someone to inspect four configuration files and three symlinks manually, you give the environment an executable health check.

Updates are a trust boundary

Updating dotfiles sounds trivial.

You could simply run:

git pull

and then execute the installer again.

But there is a security detail hiding inside that workflow: the repository contains executable shell scripts.

Updating the repository therefore changes code that you may execute automatically.

The dotfiles-update helper treats that as a trust boundary.

It requires a clean worktree, verifies the expected main branch and origin/main upstream, validates that origin 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.

Afterward, it runs dotfiles-doctor.

This does not magically make remote code trustworthy. That would be an unrealistic claim.

It does make the transition from one trusted local revision to another much more explicit.

That is a useful distinction whenever an updater ends by executing newly downloaded code.

Uninstalling cleanly is part of installation design

There is another feature that configuration scripts often forget:

./uninstall.sh

The uninstaller removes what the repository owns and leaves unrelated configuration alone.

That requirement influences the entire architecture.

If you cannot identify which lines, files, symlinks, and Git configuration entries belong to your installer, safely removing them later becomes difficult.

In other words, a good uninstall story is usually evidence of a good ownership model.

Dotfiles can leak more than you expect

There is one rule worth repeating whenever dotfiles and GitHub appear in the same sentence:

Do not commit secrets.

Shell configuration is exactly the kind of place where credentials tend to accumulate over time.

A quick export API_KEY=... can become permanent history surprisingly easily.

The repository therefore treats secret scanning as part of CI rather than relying purely on memory.

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.

Shell scripts are additionally checked using Bash syntax validation, ShellCheck, and shfmt.

The important lesson is not that every dotfiles repository needs exactly those tools.

The lesson is that configuration repositories can execute code and can contain credentials, which means they deserve a security model too.

Yes, I test my dotfiles

This may sound excessive until you consider what an installer does.

It modifies shell startup behavior, Git configuration, symlinks, executable paths, and potentially every development environment you create.

That is worth testing.

The repository uses Bats to verify behavior such as installer idempotency, lifecycle operations, repository discovery, updater behavior, and the .NET helpers.

It also builds a clean Ubuntu test container.

That container verifies the lifecycle from a fresh environment: installation, diagnostics, idempotency, repository hooks, and uninstall.

There is even a deny-by-default Docker context so unrelated local files are not accidentally copied into the lifecycle image.

At some point, dotfiles stop being “some configuration files”.

They become a small software product whose user happens to be you.

And once you see them that way, tests stop looking strange.

What I would recommend starting with

You absolutely do not need all of this on day one.

Start with the configuration that causes friction when you move between machines.

Put your Git preferences and shell aliases in a repository. Add a simple bootstrap script. Make it safe to execute twice.

Then resist the temptation to turn the repository into a universal package manager for your entire workstation.

Add automation only when you repeatedly encounter a problem worth automating.

The repository should grow with your workflow, not become another environment you have to maintain for its own sake.

Quick takeaways

If you remember only a few things from this article:

Treat dotfiles as personal configuration as code, not as a replacement for project configuration.
Make installation idempotent and conservative; avoid overwriting configuration you do not own.
Keep SDKs, packages, tools, and other project dependencies inside the project that needs them.
Give automated environments a doctor command so assumptions can be verified later.
Consider updates to executable dotfiles a trust boundary.
Never store credentials in a public dotfiles repository, and consider automated secret scanning.
Once your installer starts changing important parts of your environment, test it like software.

Where to go next

If you want to explore the implementation discussed here, the complete repository is available at rodri-oliveira-dev/dotfiles on GitHub. The most interesting places to start are README.md, install.sh, bin/dotfiles-doctor, bin/dotfiles-update, shell/, git/config, .github/workflows/validate.yml, and tests/.

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 include.path approach used here, while ShellCheck is worth studying if you maintain non-trivial Bash scripts.

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.

The main idea, however, is simpler than any particular tool.

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.

And that is a much nicer place to be.

What Happens After the Commit?

Rodrigo de Oliveira — Wed, 07 Oct 2026 13:01:00 +0000

Saving a record to a database is relatively easy.

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.

Things become much more interesting when the database commit is not the end of the operation.

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.

The first implementation that comes to mind seems perfectly reasonable:

save to database
publish event

But there is an uncomfortable question between those two lines:

What if the database commits successfully and the message broker becomes unavailable immediately afterward?

The transaction exists.

The event does not.

And now two parts of the system are telling different stories.

This is one of the problems I wanted to explore in poc-arquitetura, a repository I use as an executable software architecture laboratory.

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.

What interests me is what happens when these patterns have to work together.

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.

That simple question — what happens after the commit? — opens a much broader discussion about distributed systems.

rodri-oliveira-dev / poc-arquitetura

.NET architecture PoC for distributed services with CQRS, Kafka, PostgreSQL, Outbox, DLQ, observability and CI quality gates.

poc-arquitetura

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.

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.

Este projeto é útil para:

quem está aprendendo arquitetura e quer ver os conceitos aplicados;
desenvolvedores .NET que querem executar, testar e alterar uma stack local;
arquitetos que querem avaliar decisões, limites e riscos;
avaliadores técnicos que querem entender a proposta rapidamente.

Visão geral

flowchart LR
    Client[Cliente ou teste] --> Keycloak[Keycloak OIDC]
    Client --> LedgerApi[LedgerService.Api]
    Client --> BalanceApi[BalanceService.Api]
    Client --> TransferApi[TransferService.Api]
    Client --> PaymentApi[PaymentService.Api]
    Client --> IdentityApi[IdentityService.Api]
    Client --> AuditApi[AuditService.Api]
    LedgerApi -->

…

View on GitHub

Start by separating facts from projections

Two bounded contexts are especially important in this example.

LedgerService owns financial facts.

If a financial transaction happened, the Ledger is where that fact should be recorded.

BalanceService has a different responsibility. It maintains a projection optimized for balance queries.

At a high level, the architecture looks like this:

flowchart LR
    Client[Client] --> LedgerApi[Ledger API]

    LedgerApi --> LedgerDb[(PostgreSQL<br/>Ledger)]

    LedgerDb --> LedgerWorker[Ledger Worker]
    LedgerWorker --> Kafka[(Kafka)]

    Kafka --> BalanceWorker[Balance Worker]
    BalanceWorker --> BalanceDb[(PostgreSQL<br/>Balance)]

    Client --> BalanceApi[Balance API]
    BalanceApi --> BalanceDb

A transaction and a balance are not the same thing.

The transaction is a fact: something happened.

The balance is a model derived from those facts.

Could everything live in a single application and database? Absolutely. Depending on the system, that may even be the better architecture.

But this laboratory deliberately separates those responsibilities so that the consequences of the decision become visible.

One consequence appears immediately.

The balance is no longer updated inside the same database transaction as the Ledger.

We have entered the world of eventual consistency.

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.

That window is not an accident.

It is part of the architecture.

The real problem is not Kafka. It is the dual write

Suppose the Ledger does something like this:

sequenceDiagram
    participant C as Client
    participant L as Ledger API
    participant DB as PostgreSQL
    participant K as Kafka

    C->>L: Create transaction
    L->>DB: INSERT LedgerEntry
    DB-->>L: COMMIT
    L->>K: Publish event
    K-->>L: Acknowledged
    L-->>C: 201 Created

    Note over L,K: What happens if the process<br/>fails after COMMIT but before publish?

When everything works, this looks fine.

Now imagine that the database commit succeeds but the process crashes before Kafka acknowledges the event.

The Ledger contains the transaction.

The event may never be published.

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.

This is the dual-write problem.

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.

One option would be some form of distributed transaction.

For this project, I chose a different approach: accept that PostgreSQL and Kafka have independent lifecycles and make the intent to publish durable.

That is where the Transactional Outbox pattern becomes useful.

Outbox: do not publish now, persist the intent to publish

Instead of saving a transaction and immediately depending on Kafka, the Ledger stores both the financial fact and an Outbox message inside the same PostgreSQL transaction.

sequenceDiagram
    participant C as Client
    participant L as Ledger API
    participant DB as PostgreSQL
    participant W as Ledger Worker
    participant K as Kafka

    C->>L: Create transaction

    rect rgb(235, 235, 235)
        L->>DB: BEGIN
        L->>DB: INSERT LedgerEntry
        L->>DB: INSERT OutboxMessage
        L->>DB: COMMIT
    end

    L-->>C: Transaction confirmed

    W->>DB: Fetch pending messages
    DB-->>W: OutboxMessage
    W->>K: Publish LedgerEntryCreated
    K-->>W: Acknowledged
    W->>DB: Mark as processed

Either both records are persisted or neither is.

The HTTP request no longer needs Kafka to be available in order to preserve the intent to publish the event.

A separate worker polls pending Outbox messages and publishes them.

After Kafka confirms publication, the worker updates the Outbox entry.

If Kafka is unavailable, the financial transaction still exists together with durable information that an event still needs to be published.

If the worker crashes, processing can resume later.

This small architectural change has an important effect.

The failure is no longer a tiny invisible window between two independent writes.

It becomes state that the system can observe and recover from.

That, to me, is one of the most useful ways to understand Outbox.

It does not magically turn Kafka and PostgreSQL into a single transaction.

It does not guarantee exactly-once processing.

It turns an otherwise difficult-to-recover failure into something explicitly represented in the system.

Recoverable systems are usually far more interesting than systems designed around the assumption that failures will not happen.

Preventing message loss creates another problem: duplicates

There is a consequence to this design.

Imagine the worker publishes an event successfully, but crashes before marking the Outbox message as processed.

When it restarts, the same message may be published again.

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->>W: Pending message
    W->>K: Publish event
    K-->>W: Success

    Note over W: Worker crashes before<br/>marking the message as processed

    O->>W: Same message again
    W->>K: Republish event

    K->>B: Event
    B->>DB: Was this event_id processed?
    DB-->>B: No
    B->>DB: Update projection and store event_id

    K->>B: Duplicate event
    B->>DB: Was this event_id processed?
    DB-->>B: Yes

    Note over B: Duplicate safely ignored

This is not necessarily a bug.

It is a normal consequence of at-least-once delivery.

The responsibility now moves to the consumer.

BalanceService records processed event identifiers so the same event does not modify the projection twice.

That is idempotency becoming part of the architecture.

Retries are often presented as generic resilience configuration: retry three times, use exponential backoff, done.

But retry is also a business decision.

If executing the same operation twice produces two different side effects, a retry may cause more damage than the original failure.

Before asking:

How many times should we retry?

I think a better question is:

What happens if we execute this operation again?

That question tends to uncover much more important design problems.

Eventual consistency has to exist outside the diagram too

Once Ledger and Balance are separated, this state becomes perfectly valid:

Ledger:
Transaction exists.

Balance:
Transaction has not been projected yet.

There is nothing inherently wrong with that.

The problem appears when the architecture is asynchronous but the rest of the product behaves as though every read must immediately reflect every write.

Different domains solve this in different ways.

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.

There is no universal answer.

The important point is that eventual consistency should be a known business and architectural property, not an accidental side effect of adding Kafka.

Events are APIs too

Once services depend on events, another problem eventually appears:

contracts change.

The project includes an evolution from events such as:

LedgerEntryCreated.v1
LedgerEntryCreated.v2

During a migration period, consumers may need to understand both versions.

That forces us to treat event schemas as real integration contracts.

We already think carefully about HTTP APIs: OpenAPI definitions, breaking changes, versioning, client compatibility.

Events deserve similar care, perhaps even more.

An HTTP response usually exists only during a request.

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.

That changes how we think about compatibility.

Ordering deserves attention too.

Kafka guarantees ordering within a partition, not universal ordering across the entire system.

The message key therefore becomes an architectural decision because it influences which events share a partition and which operations can be processed in parallel.

Details that look small in producer code can have significant consequences for correctness and throughput.

Retry cannot be the final answer

Some failures are temporary.

A broker can become unavailable. A network request can time out. A dependency may take longer than expected to respond.

Retry with backoff makes sense in those cases.

But a structurally invalid event will still be invalid ten seconds later.

An incompatible schema will not suddenly become compatible on attempt number 47.

Retrying forever simply turns one bad message into a permanent consumer of CPU, logs, and operational attention.

That is where a Dead Letter Queue, or DLQ, becomes useful.

A useful DLQ should preserve enough information for investigation and recovery: the original payload, event type, failure classification, source information, and correlation metadata.

But putting something in a DLQ is only half the solution.

The more important question is:

What happens next?

Can the message be safely replayed?

Was the root cause fixed?

Can a projection be rebuilt?

Should the message be discarded?

Does the operation require manual review?

The project explores requeue, replay, and projection rebuild scenarios because recovery is part of the architecture too.

A phrase I keep coming back to is:

A DLQ without a recovery strategy is just a distributed archive of unresolved problems.

Transfers make distributed failures much easier to see

Updating a read projection is relatively straightforward compared with an operation that produces multiple distributed side effects.

Consider a transfer.

At a simplified level, we need to create a debit and then a credit.

Inside one local database transaction, ACID properties solve a lot of problems for us.

Across independent components, those guarantees disappear.

The project models this flow as an orchestrated Saga:

flowchart TD
    A[Transfer Requested] --> B[Create Debit]

    B -->|Success| C[Create Credit]
    B -->|Failure| F[Transfer Failed]

    C -->|Success| D[Transfer Completed]
    C -->|Failure| E[Compensate Debit]

    E --> G[Record Reversal]
    G --> F

This makes something very explicit:

when we distribute an operation, we also distribute its failure modes.

If the debit succeeds and the credit fails, there is no global ROLLBACK statement capable of reversing time across independent services.

We have to define what compensation means.

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.

A Saga does not recreate ACID across services.

It models the states and compensating actions required because that local transaction boundary no longer exists.

That distinction is important.

Circuit breakers do not hide failures. They control them.

Another scenario in the laboratory intentionally takes LedgerService offline while the transfer worker is still running.

Without protection, the worker can keep calling a dependency that is already known to be unavailable.

Retries can make this even worse by multiplying calls against an unhealthy service.

A Circuit Breaker changes that behavior.

stateDiagram-v2
    [*] --> Closed

    Closed: Requests flow normally
    Open: Requests fail fast
    HalfOpen: Limited probe requests

    Closed --> Open: Consecutive failures
    Open --> HalfOpen: Wait period expires
    HalfOpen --> Closed: Dependency recovered
    HalfOpen --> Open: Dependency still unhealthy

When the circuit is open, the system has not somehow recovered.

It has acknowledged the failure and chosen not to waste resources repeatedly exercising the same broken dependency.

After a configured interval, the breaker allows a controlled probe through the half-open state.

If that succeeds, traffic can resume.

This leads to another principle that I think is worth emphasizing:

Resilience does not mean making failures invisible.

Resilience means making failure behavior predictable.

Observability becomes much more important after leaving HTTP

Following a single HTTP request through logs is usually manageable.

Following an asynchronous workflow across several processes is very different.

A single operation may travel through:

flowchart LR
    Request[HTTP Request]
        --> API[Ledger API]
        --> DB[(PostgreSQL)]
        --> Outbox[Outbox]
        --> Worker[Ledger Worker]
        --> Kafka[(Kafka)]
        --> Consumer[Balance Worker]
        --> Projection[(Balance DB)]

    Request -. Correlation ID .-> API
    API -. Trace Context .-> Outbox
    Outbox -. traceparent .-> Worker
    Worker -. Trace Context .-> Kafka
    Kafka -. traceparent .-> Consumer

If every component produces unrelated logs, diagnosing a problem becomes timestamp archaeology.

The project propagates correlation_id, and when OpenTelemetry is enabled, W3C tracing context such as traceparent and tracestate can also travel through the Outbox and Kafka messages.

The observability side can be viewed separately:

flowchart LR
    Client[Client] --> API[Ledger API]
    API --> DB[(PostgreSQL)]
    DB --> Outbox[Outbox]
    Outbox --> Worker[Ledger Worker]
    Worker --> Kafka[(Kafka)]
    Kafka --> Consumer[Balance Worker]
    Consumer --> Balance[(Balance DB)]

    API -.-> OTEL[OpenTelemetry]
    Worker -.-> OTEL
    Consumer -.-> OTEL

    OTEL --> Traces[Traces]
    OTEL --> Metrics[Metrics]

    API -. Logs .-> Logs[Centralized Logs]
    Worker -. Logs .-> Logs
    Consumer -. Logs .-> Logs

The local stack includes OpenTelemetry, Jaeger, Prometheus, Grafana, Loki, and supporting components.

But the tools are not the important part.

The important part is the questions they allow us to answer.

The API is healthy, but is the Outbox backlog growing?

Is the producer failing?

Is consumer processing slowing down?

Are duplicates increasing?

Has the DLQ started receiving messages?

Which original HTTP request produced the event that failed several minutes later in another process?

Once asynchronous processing becomes central to the system, an HTTP health endpoint tells only a very small part of the story.

Test the architecture, not only the classes

A system like this can have excellent unit-test coverage and still fail exactly where the interesting risks are: between components.

That is why the laboratory also contains integration tests and k6 scenarios that exercise complete workflows.

One scenario validates:

Ledger
  -> Outbox
  -> Kafka
  -> Balance

Another exercises the complete Transfer Saga.

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.

I am careful not to describe these tests as production-scale benchmarks.

They run in a controlled local environment.

Their latency thresholds are regression guardrails, not production SLOs.

Running 50 requests per second on Docker Compose does not prove that an architecture can operate at banking scale.

Real capacity depends on infrastructure, partitions, database behavior, network topology, autoscaling, workload characteristics, failure modes, and many other variables.

The tests prove something narrower, but still valuable:

the architectural behavior remains testable under concurrency and controlled failure conditions.

Sometimes the best architecture test is not checking whether a certain method was called.

It is turning a dependency off and observing what the system actually does.

This is a laboratory, not a production reference architecture

Projects that demonstrate microservices, Kafka, Outbox, Sagas, and observability can easily give the impression that they represent a universal production blueprint.

This one does not.

poc-arquitetura is intentionally a laboratory for experimenting with decisions.

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.

That distinction matters.

Software architecture is not the process of fitting as many patterns as possible into a diagram.

It is the process of choosing mechanisms that are proportional to the problems the system actually has.

Quick takeaways

The database commit is often only the beginning of a distributed workflow.

Transactional Outbox does not make PostgreSQL and Kafka a single transaction; it makes the intent to publish durable.

At-least-once delivery means duplicates are expected, which makes idempotency a correctness requirement rather than a nice optimization.

Eventual consistency has to be understood by the product, not hidden behind a message broker.

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.

Circuit Breakers control failures instead of pretending those failures disappeared.

And observability has to cross the same boundaries that events cross.

If I had to reduce the whole experiment to one idea, it would be this:

In distributed systems, we do not design only the successful path. We also design how failures are detected, understood, and recovered.

Where to go next

For a broader view of .NET microservice architecture, Microsoft's “.NET Microservices: Architecture for Containerized .NET Applications” is a useful starting point.

For Transactional Outbox, Saga, Idempotent Consumer, and related distributed-system patterns, Chris Richardson's Microservices Patterns and the Microservices.io pattern catalog are excellent references.

For Kafka, it is worth going beyond basic producer/consumer tutorials and studying the official material on partitions, consumer groups, offsets, ordering, delivery semantics, and transactions.

For distributed tracing and context propagation, the OpenTelemetry documentation provides a vendor-neutral mental model for traces, spans, metrics, baggage, and propagation.

For load and resilience testing, Grafana k6 is approachable enough to start small while still supporting serious workloads.

And if you want to understand the deeper ideas behind transactions, replication, streams, partitioning, and distributed data, Designing Data-Intensive Applications, by Martin Kleppmann, is still one of the books I would put near the top of the list.

The repository behind this article contains the source code, ADRs, event contracts, architecture documentation, tests, and failure scenarios discussed here:

rodri-oliveira-dev / poc-arquitetura

.NET architecture PoC for distributed services with CQRS, Kafka, PostgreSQL, Outbox, DLQ, observability and CI quality gates.

poc-arquitetura

Este projeto é útil para:

quem está aprendendo arquitetura e quer ver os conceitos aplicados;
desenvolvedores .NET que querem executar, testar e alterar uma stack local;
arquitetos que querem avaliar decisões, limites e riscos;
avaliadores técnicos que querem entender a proposta rapidamente.

Visão geral

flowchart LR
    Client[Cliente ou teste] --> Keycloak[Keycloak OIDC]
    Client --> LedgerApi[LedgerService.Api]
    Client --> BalanceApi[BalanceService.Api]
    Client --> TransferApi[TransferService.Api]
    Client --> PaymentApi[PaymentService.Api]
    Client --> IdentityApi[IdentityService.Api]
    Client --> AuditApi[AuditService.Api]
    LedgerApi -->

…

View on GitHub

There is still plenty I want to experiment with.

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.

How I organized security policies, reusable workflows, .NET maintenance, and AI agent governance across my GitHub repositories.

Rodrigo de Oliveira — Tue, 29 Sep 2026 14:30:00 +0000

The challenge of maintaining multiple repositories

When you maintain one or two repositories, duplicating a few configuration files doesn't seem like a big deal.

A CONTRIBUTING.md here, a pull request template there, some security policies, and a few GitHub Actions workflows. Everything works, and development continues.

The problem becomes more noticeable as the number of repositories grows.

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.

Over time, these differences create configuration drift.

I started addressing this problem by evolving my .github repository into a central governance and automation layer for the projects I maintain.

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.

In this article, I'll explain how that structure works, what I implemented, and the architectural decisions behind it.

What makes a `.github` repository special?

GitHub provides special behavior for public repositories named .github.

They can contain default community health files that GitHub uses across other public repositories belonging to the same account or organization.

This includes files such as CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, issue templates, and pull request templates.

When a repository doesn't provide its own version of a supported file, GitHub can use the corresponding default.

The important part is that local configurations take precedence.

If a project requires a different security policy or pull request template, it can maintain its own version.

This creates a useful governance model: shared defaults with local overrides when necessary.

I initially used this functionality to provide consistent contribution guidelines, security policies, and support documentation.

As my projects evolved, I realized several other responsibilities could benefit from a similar approach.

From shared files to a governance layer

Maintaining multiple repositories involves more than keeping documentation consistent.

Dependency updates, SDK versions, security checks, pipeline validation, and recurring maintenance tasks often require similar implementations.

Instead of handling each concern independently, I started using the .github repository as a coordination point.

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.

There is an important distinction here.

GitHub doesn't automatically distribute every file stored in a .github repository to other projects.

Native inheritance applies only to specific supported features. Workflows, Dependabot configurations, custom scripts, and AI agent instructions require their own reuse or distribution mechanisms.

My implementation combines native GitHub features with automation built using GitHub Actions and the GitHub API.

The .github repository provides the foundation, but the broader governance model is something we build on top of it.

Reusable workflows and centralized policies

One of the first responsibilities I centralized was the implementation of policies used by multiple CI/CD pipelines.

GitHub Actions supports reusable workflows, allowing one workflow to call another.

Imagine several repositories that need to perform the same security scan.

Instead of maintaining independent copies of the scanning logic, we can expose a reusable workflow that each project calls from its own pipeline.

A simplified example:

YAML

name: Security

on:
  pull_request:

jobs:
  security:
    uses: owner/.github/.github/workflows/reusable-secret-scan.yml@v1

Here, owner represents the account maintaining the central repository, and v1 represents a published version of the reusable workflow.

The consuming repository decides when the scan runs and how it fits into its development process.

The central repository maintains the shared implementation.

The application still owns its pipeline. The central repository owns the shared policy implementation.

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.

Why versioning matters

When multiple repositories depend on a shared workflow, changes can affect several consumers.

Pointing every repository to the central main branch may be convenient, but it creates a dependency on its latest state.

That's why I implemented an explicit versioning and release process.

The strategy supports semantic versioning, major-version references, and full commit SHA references when strict reproducibility is required.

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.

Reusing code doesn't eliminate coupling. It requires us to manage that coupling deliberately.

Versioning, compatibility, and change review are essential parts of maintaining shared automation.

Securing the automation itself

When a repository starts coordinating operations across other repositories, its role changes.

It can execute code, access repository metadata, create branches, and open pull requests.

This introduces additional security considerations.

One practice I adopted was pinning external GitHub Actions to their full commit SHA, identifying the exact code being executed.

I also configured Dependabot to monitor GitHub Actions dependencies and propose updates through pull requests.

However, automated updates don't mean automated merges.

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.

For this reason, human review remains part of the process.

GitHub Apps and least privilege

I also use a GitHub App for operations involving multiple repositories.

Instead of relying on a long-lived personal access token with broad permissions, the automation uses short-lived installation access tokens.

This allows permissions to be restricted to the operations the application actually needs.

For example, my .NET repository inventory separates repository discovery from code inspection.

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.

This reduces credential exposure during code inspection.

It's a practical application of the principle of least privilege: each component receives only the access required to perform its responsibility.

Automating .NET repository maintenance

Beyond shared policies, I implemented automation to help maintain my .NET repositories.

One example is SDK version synchronization.

The workflow identifies eligible repositories, checks their root-level global.json files, and determines whether an update is available under the configured compatibility policy.

When an applicable update is found, it prepares the change in a branch and opens a pull request.

The automation doesn't merge directly into the default branch. Each repository retains its normal review and integration process.

Building a centralized .NET inventory

Another workflow produces an inventory of .NET projects across repositories accessible to the configured GitHub App.

The goal isn't to modify projects but to obtain a consolidated view of their metadata.

The inventory uses DotNetRepoInspector to inspect .NET repositories using effective MSBuild metadata rather than relying exclusively on direct .csproj parsing.

This integration illustrates an architectural principle I wanted to preserve.

Each project retains a specific responsibility.

DotNetRepoInspector performs the inspection. The .github repository coordinates execution across multiple repositories and consolidates the results.

I didn't need to move the inspection implementation into the central repository to reuse its capabilities.

Automation needs engineering, too

Maintenance scripts often start small.

A few lines of Bash solve a problem, become part of a workflow, and continue running for months.

Things change when that same script starts modifying multiple repositories.

At that point, it deserves the same engineering attention we give other software components.

That's why my .github repository includes regression tests, contract validation, and quality checks using tools such as actionlint and ShellCheck.

I also implemented mechanisms for handling failures during batch operations.

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.

Continuing after a recoverable error shouldn't mean hiding that error.

Automation branch ownership

Another concern involves the ownership of branches created by automation.

The existence of a branch named chore/sync-dotnet-sdk doesn't automatically mean a workflow can assume that branch belongs to it.

Someone may have created it manually, or it may contain changes that shouldn't be overwritten.

For that reason, the automation performs additional ownership and pull request state checks before reusing or updating an existing branch.

These safeguards become particularly relevant when scripts can modify multiple repositories.

Managing shared instructions for AI development agents

More recently, I encountered another form of shared configuration: instructions used by AI development agents.

Tools capable of inspecting code, implementing issues, and reviewing pull requests need to understand the rules and conventions of the projects they work on.

These instructions may cover architecture, testing strategies, security policies, and implementation procedures.

When maintaining multiple repositories, some instructions naturally overlap.

Copying the same files between projects, however, creates the same configuration drift problem we see with workflows.

To address this, I created an agent-governance directory inside the central repository.

It contains shared instructions, profiles, reusable skills, a manifest, and its own version file.

The available skills cover activities such as bug investigation, issue implementation, pull request review, security analysis, refactoring, and test coverage analysis.

The goal is to provide shared instructions while allowing individual projects to extend them according to their specific needs.

Distributing instructions to consuming repositories

Unlike community health files, AI agent instructions aren't automatically inherited from the .github repository.

A separate process is required to manage their evolution and distribution.

I implemented workflows that validate the central registry, synchronize selected skills from a controlled upstream source, and distribute approved updates to consuming repositories.

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.

This preserves change review, version history, and the ability to maintain repository-specific instructions.

The same principle used for reusable workflows applies here:

Centralize what is shared without removing control from the consuming projects.

What do we gain from this approach?

The main benefit isn't simply having fewer files.

It's reducing the number of places where the same decision must be maintained.

When a security policy has several independent copies, each copy can evolve differently.

With a central source and a controlled mechanism for reuse or distribution, the problem changes.

Instead of asking:

How do I keep ten configurations identical?

We can ask:

How do I maintain one shared policy while preserving compatibility with its consumers?

The second problem isn't trivial, but it's more explicit and easier to manage systematically.

It also becomes easier to distinguish responsibilities that belong to the broader repository ecosystem from those that should remain within individual projects.

Not every configuration should be centralized.

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.

Centralizing everything can introduce unnecessary coupling.

That's why I treat the .github repository as a shared governance layer rather than a universal configuration repository.

The trade-offs of centralization

A centralized structure introduces responsibilities of its own.

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.

This is why versioning, validation, review, and access control need to evolve alongside centralization.

Different types of configuration also require different sharing mechanisms.

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.

Each mechanism has its own limitations.

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.

Key takeaways

Building this repository reinforced an important architectural principle: centralization and autonomy don't have to be opposing concepts.

We can establish shared standards without preventing individual projects from making their own decisions.

Reuse also requires governance. Shared workflows need versioning, automation needs testing, and distribution mechanisms need traceability and review.

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.

Finally, AI development instructions should be treated like other engineering artifacts. They require maintenance, versioning, and controlled update mechanisms.

The main lesson is simple: centralize policies that are genuinely shared, and keep project-specific decisions within the projects that own them.

Even a personal portfolio can provide a practical environment for exploring Platform Engineering, Developer Experience, and software governance.

ADR: Recording the Why Behind Decisions and How ADR Guard Helps Keep Architectural History Reliable

Rodrigo de Oliveira — Tue, 22 Sep 2026 15:00:00 +0000

In projects that live for more than a few years, there is one question that comes up surprisingly often:

“Why did we build it this way?”

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.

The code usually tells us what was implemented.

Git tells us when it changed.

But neither necessarily explains why the decision was made.

That is exactly where Architecture Decision Records, or simply ADRs, come in.

The problem is not forgetting the technology. It is forgetting the context

Architectural decisions rarely happen in a vacuum.

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:

“This doesn’t make sense. We could simplify all of this by using X.”

Maybe they could.

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.

Without that context, old decisions can look arbitrary.

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.

An ADR is essentially a snapshot of architectural reasoning at a particular point in time.

It does not try to explain the entire architecture.

It explains one decision.

What goes into an ADR?

There are several ADR templates, but one of the best-known formats is intentionally simple.

Context explains the problem, constraints, and forces that created the need for a decision.

Decision records what was decided.

Consequences describe what changes because of that choice, including benefits, costs, and trade-offs.

There is usually also a Status, indicating whether the decision is being proposed, has been accepted, has been deprecated, or has been superseded by another decision.

AWS, for example, recommends using ADRs for architecturally significant decisions involving system structure, non-functional requirements, dependencies, interfaces, and construction techniques.

That distinction matters because an ADR should not become a development diary.

“We upgraded a library version” probably does not need an ADR.

“We standardized every service in the organization on a specific authentication strategy” probably does.

A useful question is:

Does this decision significantly affect how the system will be built, operated, or evolved?

If the answer is yes, there is probably an architectural decision worth recording.

ADRs are less about documentation and more about institutional memory

As ADRs accumulate, they form what is often called a decision log.

That history becomes especially valuable as people join and leave teams.

Instead of depending on the one developer who “remembers why we did that in 2023,” the context becomes part of the repository itself.

There is another benefit that is less obvious: ADRs reduce repeated discussions.

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.

With an ADR, the conversation can start several steps ahead:

“We made this decision for these reasons. Have any of those assumptions changed?”

That is a much better discussion.

When the ADRs themselves become a problem

Adopting ADRs sounds easy: create a docs/adr directory, add a few Markdown files, and you are done.

In practice, small inconsistencies begin to appear over time.

One file is called 0003-use-redis.md, another is called adr4-rabbitmq.md. One ADR uses the status Approved, another uses Accepted. 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.

And perhaps the most common problem: someone creates a manually maintained ADR index that stops being updated after a few months.

Individually, none of these problems seems particularly serious.

Together, however, they slowly make the documentation less trustworthy.

That is exactly the space ADR Guard is designed to address.

ADR Guard: treating ADRs as verifiable artifacts

ADR Guard is a .NET command-line tool for validating and indexing Architecture Decision Records.

The idea is straightforward: if certain conventions matter to your architectural documentation, they do not have to remain informal recommendations buried in a README.

They can become automatically verifiable invariants.

By default, ADR Guard expects files such as:

0001-use-postgresql.md
0002-adopt-opentelemetry.md

And a structure based on the classic ADR format:

# Use PostgreSQL

## Status

Accepted

## Context

We need a relational database.

## Decision

Use PostgreSQL.

## Consequences

The team will need operational knowledge of PostgreSQL.

The command:

adr-guard check docs/adr

analyzes the records and validates filenames, IDs, titles, statuses, required sections, and relationships between ADRs.

The tool currently exposes stable validation codes from ADR001 through ADR009, covering problems such as duplicate IDs, broken relative references, missing required sections, and Superseded ADRs that do not correctly reference the decision that replaced them.

That may sound like a small detail, but stable validation codes make the tool especially useful for automation.

The real benefit appears in CI

Running ADR Guard manually is useful.

Running it in the pipeline is where things become more interesting.

- name: Validate ADRs
  run: adr-guard check docs/adr

At that point, architectural documentation conventions become part of the same quality workflow already used for source code.

A pull request that breaks a link between architectural decisions can fail.

An incomplete ADR can fail.

Two ADRs using the same identifier can fail.

Of course, this does not turn architecture into code. ADR Guard cannot tell you whether Kafka is a better architectural choice than RabbitMQ.

But it can verify something much more objective:

Is the record of that decision still structurally consistent?

That separation matters.

Automate what is mechanical so that human attention can remain focused on what actually requires judgment.

The index no longer has to be maintained manually

ADR Guard also provides:

adr-guard index docs/adr

The command validates the ADR set first and only then generates a deterministic Markdown index.

That order is intentional.

ADR Guard itself contains an ADR explaining this choice: generating an index from invalid documents could make an inconsistent set of decisions look authoritative.

If validation fails, the existing index is left untouched.

If nothing has changed, the file is not rewritten unnecessarily.

The result may seem small, but it removes one more manual maintenance task that would otherwise eventually be forgotten.

And then AI enters the picture with clear boundaries

One of the more interesting capabilities added to the project is the draft command.

ADR Guard can use OpenAI, Anthropic, Gemini, or an OpenAI-compatible endpoint to help generate an initial ADR draft.

But there is an important architectural principle behind the implementation:

AI does not make architectural decisions on behalf of the team.

Every AI-generated ADR is forced to use the Proposed status.

ADR Guard owns the final document structure, validates the generated result, and leaves the transition to Accepted under human control.

That distinction is increasingly important.

Using AI to accelerate documentation is very different from delegating architectural authority to a model.

The project also deliberately avoids silently ingesting the entire repository.

Additional context must be explicitly provided, and existing ADRs are only sent to the configured AI provider when --include-existing-adrs is enabled.

There is also a preview mode:

--dry-run

which allows the tool to generate, assemble, and validate the ADR without writing anything to disk.

It is a sensible approach to AI in engineering:

assistance rather than unrestricted autonomy.

What ADR Guard deliberately does not do

Understanding what a tool does not do can be just as important as understanding what it does.

ADR Guard does not automatically analyze a Git diff and decide that a change requires an ADR.

It does not scan the entire source tree looking for architectural decisions.

It does not perform RAG over the repository.

It does not automatically accept architectural decisions.

And it does not attempt to judge whether the recorded decision is architecturally sound.

That means one responsibility remains firmly with the team:

recognizing when a decision is significant enough to be recorded.

ADR Guard starts helping after that human decision has been made.

And that is a healthy division of responsibility.

An interesting detail: ADR Guard uses ADRs to build ADR Guard

The project keeps its own architectural decisions under docs/adr.

Among the decisions currently documented are:

using conventional Markdown ADRs;
keeping the CLI free of third-party runtime dependencies;
validating ADRs before generating the index;
keeping AI-assisted draft generation provider-agnostic.

In other words, the project applies its own rules to itself.

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.”

Choosing to keep a CLI dependency-free can also be an architectural decision when that choice affects distribution, maintenance, and future evolution.

ADRs should not prevent change

This may be the most important point of all.

An ADR does not exist to say:

“We decided this once, so we can never change it.”

Architecture has to evolve.

When assumptions change, a new decision can replace the previous one. What matters is preserving the history.

Instead of rewriting the past until it appears consistent with the present, create a new decision and record that it supersedes the previous one.

That sequence tells a far more useful story about the architecture than any isolated diagram.

Key takeaways

Code records implementation; ADRs record intent and context.
A collection of ADRs creates architectural memory and reduces repeated discussions.
Even simple documentation can suffer from drift, inconsistencies, and broken relationships exactly the kind of problems automation can help prevent.
ADR Guard turns ADR conventions into checks that can run locally and in CI while also keeping the decision index consistent.
AI can accelerate the creation of an initial draft, but architectural decisions remain a human responsibility.

Perhaps that combination is exactly what makes ADRs so useful.

They are simple enough to remain human-readable documentation, but structured enough for tools to help keep them healthy.

ADR Guard follows that philosophy.

It is not intended to replace architects, code reviews, or technical discussions.

Its goal is much more pragmatic:

once a team decides to record its architectural decisions, help ensure that this history remains readable, consistent, and trustworthy as the project grows.

Can Big-O Complexity Be Detected at Compile Time?

Rodrigo de Oliveira — Thu, 17 Sep 2026 20:08:02 +0000

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?

After a while, we start recognizing these patterns almost automatically.

A for 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).

That raises an interesting question:

If we can recognize these patterns by reading code, could the compiler do the same?

That is exactly the question that led me to explore building a Roslyn analyzer capable of estimating algorithmic complexity at compile time.

The short answer is: yes, to a certain extent.

The more interesting answer is understanding where that “to a certain extent” begins.

Big-O does not measure how long a method takes

Before talking about compilers, it is worth clarifying something important.

Big-O does not measure time in milliseconds.

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.

Consider:

for (var i = 0; i < items.Count; i++)
{
    Process(items[i]);
}

If we assume Process has constant cost, we have approximately:

T(n) = n

Therefore:

O(n)

Now add another loop:

foreach (var item in items)
{
    foreach (var other in items)
    {
        Compare(item, other);
    }
}

In this case:

T(n) = n × n

which gives us:

O(n²)

Big-O ignores constants and less relevant details so we can focus mainly on the rate of growth.

That is why it remains useful even across completely different machines.

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.

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 the meaning of the operations being executed.

The compiler knows much more about our code than it seems

This is where Roslyn makes the idea interesting.

The C# compiler does not see a source file as plain text.

It builds a structured representation of the program called a Syntax Tree. The syntax tree represents declarations, expressions, loops, method calls, conditionals, and practically every other language construct.

That means an analyzer does not need to search for strings such as:

"foreach"

It can ask directly:

Is there a ForEachStatementSyntax here?

More importantly, Roslyn also provides a Semantic Model.

That difference is significant.

Imagine:

items.Contains(value);

Looking only at the text, we do not know very much.

Contains could belong to:

List<T>
HashSet<T>
Dictionary<TKey, TValue>
IEnumerable<T>
MyCustomCollection

And those operations may have very different costs.

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.

It is precisely this combination of syntax and semantics that makes much more sophisticated analysis possible.

A seemingly innocent example

Consider this code:

foreach (var item in items)
{
    if (otherItems.Contains(item))
    {
        Process(item);
    }
}

If otherItems is a List<T>, Contains may scan the list looking for the element.

If items has n elements and otherItems has m, we can model the cost approximately as:

O(n × m)

If both collections grow at roughly the same rate:

O(n²)

Now change the data structure:

HashSet<int> otherItems;

The exact same line of code:

otherItems.Contains(item);

has a very different expected algorithmic behavior.

The text barely changed.

The semantics changed significantly.

A complexity analyzer therefore needs to resolve the symbol and recognize known operations from the libraries being used.

In ComplexityAnalysis.Analyzers, this is one of the strategies I use: known BCL and LINQ operations are identified by the symbol resolved by Roslyn, not simply by the method name. This prevents a custom method named Contains from automatically being treated as if it were List<T>.Contains.

That detail may seem small, but it is exactly the kind of distinction that separates an interesting demo from a usable analysis tool.

Loops are the easy part

Finding loops is relatively straightforward.

The challenge begins when we need to understand what happens inside them.

Consider:

foreach (var item in items)
{
    Calculate(item);
}

What is the complexity?

We do not know.

If:

Calculate(item);

is O(1), then we have:

O(n)

But if Calculate scans another collection of size m, we may have:

O(n × m)

Or perhaps:

O(n²)

depending on the relationship between the inputs.

That is why a more sophisticated analyzer needs to move beyond purely local analysis.

Interprocedural analysis

This is where interprocedural analysis comes in.

Imagine:

void Process(IEnumerable<int> items)
{
    foreach (var item in items)
    {
        Search(item);
    }
}

And:

void Search(int item)
{
    foreach (var value in values)
    {
        if (value == item)
            return;
    }
}

Analyzing only Process is not enough.

We need to follow the call to Search.

We can think of it like this:

Process
    |
    +-- loop n
            |
            +-- Search
                    |
                    +-- loop m

Therefore:

O(n × m)

This kind of analysis can reveal some interesting relationships.

For example:

A → B O(n)

results in:

A O(n)

While:

loop n → B O(n)

results approximately in:

O(n²)

ComplexityAnalysis.Analyzers 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.

But there is a very important word here:

limits.

An analyzer that runs during compilation cannot explore the application's entire call graph indefinitely.

The analyzer also needs to be fast

There is an interesting irony in all of this.

It would be strange to build a performance analyzer that made compilation extremely slow.

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.

A practical tool therefore needs to enforce analysis budgets.

For example:

maximum call depth = 5
methods analyzed per root = 32

If the analysis exceeds that budget, it needs to stop.

That decision matters because there is a difference between:

building a theoretically impressive analyzer

and:

building an analyzer that developers are willing to keep enabled in Visual Studio.

And then we get to recursion

Recursion makes things even more interesting.

Consider:

int Factorial(int n)
{
    if (n <= 1)
        return 1;

    return n * Factorial(n - 1);
}

We can represent its cost with a recurrence:

T(n) = T(n - 1) + O(1)

which gives us:

O(n)

Now consider divide and conquer:

T(n) = 2T(n/2) + n

Applying the Master Theorem:

O(n log n)

Another example:

T(n) = 3T(n/2) + n

results approximately in:

O(n^1.585)

So an analyzer can go beyond simply counting loops. It can recognize certain recursive patterns, construct a recurrence, and attempt to solve it.

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.

The important word, once again, is restricted.

Because trying to solve every possible recurrence quickly takes us into very different territory.

So why can't we infer everything?

This is where we reach the theoretical limit.

It is tempting to imagine an analyzer that could receive any program and correctly answer:

This method is O(1).
This one is O(log n).
This one is O(n).
This one is O(n²).

For any arbitrary piece of code.

That is not possible in general.

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.

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 approximations.

That completely changes the question.

Instead of asking:

“How can we determine the complexity of any program?”

we should ask:

“For which structures can we produce a sufficiently safe conclusion?”

That is a much more productive question.

Sometimes “I don't know” is the best answer

This may be the principle I like most about this kind of tool.

Consider:

foreach (var item in items)
{
    ExecuteSomething(item);
}

If ExecuteSomething lives in an external library the analyzer knows nothing about, there are several options.

It could simply assume:

O(1)

But that could be completely wrong.

It could assume:

O(n)

But that would also be arbitrary.

A much safer alternative is to return:

Unknown

In other words:

“I don't have enough information to state the complexity.”

That may sound less impressive, but it is an important characteristic of serious analysis tools.

Constant false positives destroy trust.

After a while, developers start ignoring the analyzer.

That is why I would rather have a tool miss some cases than invent certainty.

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.

Big-O does not replace other metrics either

Another important point: algorithmic complexity is not the same thing as code quality.

A method can be:

O(1)

and still be almost impossible to understand.

It may contain dozens of conditionals, multiple levels of nesting, too many responsibilities, and an enormous signature.

That is why it makes sense to look at different metrics independently.

Cyclomatic complexity attempts to represent independent control-flow paths.

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.

We can also track:

nesting depth
NLOC
statement count
parameter count
token count

None of these metrics replaces the others.

They answer different questions.

Big-O essentially asks:

“How does cost grow with the input?”

Cognitive Complexity asks something closer to:

“How difficult is this flow to follow mentally?”

Combining those two ideas into a single score would probably create more confusion than insight.

Where this becomes genuinely useful

The goal of detecting complexity at compile time should not be to attach an academic label to every method.

The real value appears when we can detect dangerous changes in algorithmic behavior.

Imagine someone writes:

foreach (var customer in customers)
{
    if (blockedCustomers.Contains(customer.Id))
    {
        ...
    }
}

During development, the dataset is small and everything runs quickly.

In production:

customers = 100,000
blockedCustomers = 80,000

Now that data structure choice starts to matter.

If blockedCustomers is a list, the algorithm may perform an enormous number of comparisons.

Choosing a more appropriate data structure can completely change the expected behavior.

The analyzer does not need to prove the system's exact performance.

It needs to be able to say:

“There is a linear operation inside an iteration that depends on input size. You may want to take a closer look.”

That kind of feedback is valuable precisely because it happens before production, before benchmarking, and potentially even before code review.

Static analysis does not eliminate benchmarks

It is also important not to make a promise the tool cannot keep.

An O(n) method may be slower than an O(n²) method for small inputs.

Allocation, cache locality, I/O, branch prediction, concurrency, GC, databases, networks, JIT compilation, and many other factors influence real-world performance.

Big-O is about asymptotic growth.

Benchmarking is about concrete behavior under specific conditions.

Tracing and profiling show what actually happened during execution.

These tools complement each other.

I like to think about it this way:

Static analysis
    ↓
Where might there be a problem?

Benchmark
    ↓
What is the actual cost?

Profiling / tracing
    ↓
Where is execution time actually being spent?

Using one does not eliminate the need for the others.

The compiler as an architectural feedback tool

Exploring Big-O through Roslyn led me to a broader conclusion.

Compilers do not have to exist only to transform source code into assemblies.

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.

That lets us move many checks closer to the moment when a decision is made.

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.

That idea is particularly interesting from an architecture perspective.

Whenever an architectural rule can be expressed objectively, there is a possibility of turning it into:

analyzer
architecture test
CI rule
source generator
linter
policy

It is a shift from passive documentation to executable feedback.

Not every architectural decision can or should become an automated rule.

But some certainly can.

What I learned while exploring this idea

The original question seemed simple:

“Can Big-O be detected at compile time?”

After exploring the problem, I think a better formulation is:

“Which complexity properties can we infer safely enough to provide useful feedback to developers?”

The difference matters.

We are not trying to build an oracle.

We are building a conservative analysis of a known subset of the language.

Loops, known operations, LINQ, certain interprocedural calls, and some families of recurrences can produce very useful results.

Dynamic code, difficult-to-resolve dispatch, unknown libraries, complex data dependencies, and structures outside the known model may remain Unknown.

And that is fine.

In tools like this, knowing when not to make a claim is part of the quality of the analysis.

Key takeaways

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.

The problem becomes interesting when we move beyond counting loops and start understanding operations, method calls, and recurrences.

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.

An Unknown result can be far better than a fabricated estimate.

And perhaps most importantly, Big-O analysis does not replace benchmarks, profiling, cyclomatic complexity, or Cognitive Complexity. Each technique answers a different question.

The real gain is being able to move certain performance and design signals much closer to the moment when code is being written.

Where to go next

For anyone who wants to explore the topic in more depth, I would recommend a few directions.

Microsoft Learn — .NET Compiler Platform SDK / Roslyn APIs: 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.
MIT OpenCourseWare — Introduction to Algorithms: excellent material for strengthening your understanding of asymptotic analysis, recurrences, divide and conquer, and algorithm fundamentals.
Introduction to Algorithms — Cormen, Leiserson, Rivest, and Stein (CLRS): still one of the best references for algorithms, asymptotic analysis, and recurrences.
Compilers: Principles, Techniques, and Tools — Aho, Lam, Sethi, and Ullman: useful for understanding compilers, intermediate representations, program analysis, and optimization.
Cornell Program Analysis materials: particularly useful for understanding data-flow analysis, conservative approximations, undecidability, and the theoretical limits of static analysis.
Cognitive Complexity by SonarSource: a useful read for understanding why algorithmic complexity, cyclomatic complexity, and understandability are related but distinct concerns.

If you want to look at a practical implementation of these ideas, ComplexityAnalysis.Analyzers applies this reasoning with Roslyn to Big-O analysis, interprocedural calls, selected forms of recursion, and complementary complexity metrics, always preferring Unknown when a safe conclusion cannot be reached.

In the end, perhaps the most interesting part of this exercise is not automatically determining whether a method is O(n) or O(n²).

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.

DEV Community: Rodrigo de Oliveira

Dapper FluentMap Is Back: What Changed from Version 2.0 to 3.6?

The First Decision: Preserve What Already Worked

When Property Mapping Is No Longer Enough

Global Configuration and Isolation: Two Execution Models

Moving Some Work from Runtime to Compile Time

Dommel and the Meaning of Persistence Operations

Compatibility Needs Evidence, Not Assumptions

Should You Upgrade from Version 2.0?

What Bringing FluentMap Back Means

References

Architecture Decisions Shouldn't Get Lost: Introducing ADR Guard for VS Code

Architecture Decisions Are Part of Your System's History

The Real Challenge Isn't Writing ADRs

ADR Guard: Bringing Structure to Architectural Decisions

Bringing ADRs Into Visual Studio Code

Finding Architectural Decisions Without Searching Through Folders

Creating ADRs Without Memorizing Templates

Editing Existing Decisions Safely

Making Validation Part of the Development Workflow

Architecture Governance Shouldn't Become Another Source of Friction

Not Every Technical Decision Needs an ADR

Final Thoughts

Try ADR Guard

GitHub Dotfiles: Treating Your Development Environment Like Code

Dotfiles are configuration as code

Your dotfiles should not own your projects

A safe installer is more important than a clever installer

Idempotency changes everything

Git configuration without replacing .gitconfig

Small aliases are useful. Context-aware helpers are better.

Respecting global.json is a small but important detail

Diagnostics deserve a first-class command

Updates are a trust boundary

Uninstalling cleanly is part of installation design

Dotfiles can leak more than you expect

Yes, I test my dotfiles

What I would recommend starting with

Quick takeaways

Where to go next

What Happens After the Commit?

rodri-oliveira-dev / poc-arquitetura

.NET architecture PoC for distributed services with CQRS, Kafka, PostgreSQL, Outbox, DLQ, observability and CI quality gates.

poc-arquitetura

Visão geral

Start by separating facts from projections

The real problem is not Kafka. It is the dual write

Outbox: do not publish now, persist the intent to publish

Preventing message loss creates another problem: duplicates

Eventual consistency has to exist outside the diagram too

Events are APIs too

Retry cannot be the final answer

Transfers make distributed failures much easier to see

Circuit breakers do not hide failures. They control them.

Observability becomes much more important after leaving HTTP

Test the architecture, not only the classes

This is a laboratory, not a production reference architecture

Quick takeaways

Where to go next

rodri-oliveira-dev / poc-arquitetura

.NET architecture PoC for distributed services with CQRS, Kafka, PostgreSQL, Outbox, DLQ, observability and CI quality gates.

poc-arquitetura

Visão geral

How I organized security policies, reusable workflows, .NET maintenance, and AI agent governance across my GitHub repositories.

The challenge of maintaining multiple repositories

What makes a .github repository special?

From shared files to a governance layer

Reusable workflows and centralized policies

Why versioning matters

Securing the automation itself

GitHub Apps and least privilege

Automating .NET repository maintenance

Building a centralized .NET inventory

Automation needs engineering, too

Automation branch ownership

Managing shared instructions for AI development agents

Distributing instructions to consuming repositories

What do we gain from this approach?

The trade-offs of centralization

Key takeaways

Git configuration without replacing `.gitconfig`

Respecting `global.json` is a small but important detail

What makes a `.github` repository special?