DEV Community: Rodrigo de Oliveira

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

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

Further reading

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

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

What goes into an ADR?

ADRs are less about documentation and more about institutional memory

When the ADRs themselves become a problem

ADR Guard: treating ADRs as verifiable artifacts

The real benefit appears in CI

The index no longer has to be maintained manually

And then AI enters the picture with clear boundaries

What ADR Guard deliberately does not do

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

ADRs should not prevent change

Key takeaways

Further reading

References

Can Big-O Complexity Be Detected at Compile Time?

Big-O does not measure how long a method takes

The compiler knows much more about our code than it seems

A seemingly innocent example

Loops are the easy part

Interprocedural analysis

The analyzer also needs to be fast

And then we get to recursion

So why can't we infer everything?

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

Big-O does not replace other metrics either

Where this becomes genuinely useful

Static analysis does not eliminate benchmarks

The compiler as an architectural feedback tool

What I learned while exploring this idea

Key takeaways

Where to go next

What makes a `.github` repository special?