Architecture problems rarely appear in a single pull request.
A developer adds a new dependency between two projects. Another feature introduces a database call into an application service. Later, a utility project starts referencing infrastructure code. Each change may look reasonable in isolation, but over time the architecture becomes different from what the team originally designed.
This is architecture drift.
For large .NET applications, architecture drift can be particularly difficult to detect because the solution may contain dozens or hundreds of projects, shared libraries, APIs, background workers, infrastructure components, and test projects.
Code reviews can catch some of these problems, but relying entirely on reviewers is not scalable.
A better approach is to turn important architectural rules into automated checks and run them as part of pull requests.
The goal is not to prevent developers from changing the architecture. The goal is to make architectural changes explicit, reviewable, and intentional.
What Is Architecture Drift?
Architecture drift occurs when the implementation gradually moves away from the intended architectural boundaries.
Consider a simple .NET solution:
MyCompany.Application
|
v
MyCompany.Domain
MyCompany.Infrastructure
|
v
MyCompany.Application
|
v
MyCompany.Domain
MyCompany.Api
|
v
MyCompany.Application
The intended dependency direction might be:
API
|
v
Application
|
v
Domain
Infrastructure ---> Application
Infrastructure ---> Domain
Now imagine a developer adds:
MyCompany.Domain
|
v
MyCompany.Infrastructure
The project still compiles.
Tests may still pass.
The application may still work.
But the architecture has changed.
That is exactly the type of problem automated architecture validation should catch.
Why Pull Requests Are a Good Enforcement Point
Architecture checks are particularly useful in pull requests because that is where changes are reviewed.
A typical workflow becomes:
Developer changes code
|
v
Pull Request
|
+--> Build
|
+--> Unit Tests
|
+--> Static Analysis
|
+--> Architecture Tests
|
v
Review
|
v
Merge
If an architectural rule fails, the pull request can be blocked before the violation reaches the main branch.
This is much cheaper than discovering the problem months later.
Architecture Rules Should Be Explicit
Before implementing automation, define the rules.
For example:
Domain must not reference Infrastructure
Domain must not reference Web
Application must not reference Web
API may reference Application
Infrastructure may reference Application
Controllers should not directly access DbContext
Not every rule needs to be automated.
Start with boundaries that are:
Important
Stable
Objective
Easy to verify
A good automated rule should produce a clear answer:
Allowed
or:
Violation
Project References Are a Strong Starting Point
In .NET, project references provide a useful architectural signal.
Suppose the solution contains:
src/
MyApp.Api/
MyApp.Application/
MyApp.Domain/
MyApp.Infrastructure/
The project graph can be represented as:
MyApp.Api
|
v
MyApp.Application
|
v
MyApp.Domain
MyApp.Infrastructure
|
+----> MyApp.Application
|
+----> MyApp.Domain
A dependency from Domain to Infrastructure should therefore be rejected.
Inspecting Project References
A simple approach is to inspect .csproj files.
For example:
<ProjectReference Include="..\MyApp.Domain\MyApp.Domain.csproj" />
The important information is:
Source Project
|
v
Referenced Project
You can build a dependency graph from those relationships.
For larger repositories, it is useful to normalize project names before evaluating rules.
Define Architecture Rules as Data
Avoid scattering architectural rules throughout scripts.
Instead, represent them explicitly.
For example:
{
"rules": [
{
"source": "MyApp.Domain",
"forbidden": [
"MyApp.Infrastructure",
"MyApp.Api"
]
},
{
"source": "MyApp.Application",
"forbidden": [
"MyApp.Api"
]
}
]
}
This has an important advantage.
Developers can review architecture rules independently from the validation engine.
Build a Dependency Graph
The validator can convert project references into a graph:
Project A
|
+----> Project B
|
+----> Project C
For example:
Api
|
+--> Application
|
+--> Infrastructure
Application
|
+--> Domain
Infrastructure
|
+--> Application
+--> Domain
Then compare the actual graph against the allowed dependency model.
A violation becomes a graph problem rather than a subjective code-review discussion.
A Simple C# Dependency Model
A small internal representation is enough for many repositories:
public sealed record ProjectDependency(
string Source,
string Target);
You can then build a collection:
var dependencies = new List<ProjectDependency>
{
new("MyApp.Api", "MyApp.Application"),
new("MyApp.Application", "MyApp.Domain"),
new("MyApp.Infrastructure", "MyApp.Application")
};
The architecture validator can inspect this graph and identify forbidden edges.
Detecting Forbidden Dependencies
A simple validator could look like this:
public sealed record ArchitectureRule(
string Source,
IReadOnlySet<string> ForbiddenTargets);
public static IReadOnlyList<string> Validate(
IEnumerable<ProjectDependency> dependencies,
IEnumerable<ArchitectureRule> rules)
{
var violations = new List<string>();
foreach (var dependency in dependencies)
{
var rule = rules.FirstOrDefault(
x => x.Source.Equals(
dependency.Source,
StringComparison.OrdinalIgnoreCase));
if (rule is null)
continue;
if (rule.ForbiddenTargets.Contains(dependency.Target))
{
violations.Add(
$"{dependency.Source} must not reference " +
$"{dependency.Target}.");
}
}
return violations;
}
The important part is not the implementation itself.
The important part is that the architecture rule becomes executable.
Fail the Pull Request on Violations
The validator should return a non-zero exit code when architecture rules fail.
For example:
var violations = Validate(dependencies, rules);
foreach (var violation in violations)
{
Console.Error.WriteLine(
$"ARCHITECTURE VIOLATION: {violation}");
}
return violations.Count == 0 ? 0 : 1;
The CI pipeline can then treat the result as a failed check.
This turns architecture from documentation into an enforceable engineering constraint.
Architecture Tests Inside the .NET Solution
Another approach is to implement architecture rules as automated tests.
For example:
[Fact]
public void Domain_should_not_reference_infrastructure()
{
var result = ArchitectureAnalyzer
.Analyze("MyApp.Domain");
Assert.DoesNotContain(
result.Dependencies,
dependency =>
dependency.Contains("MyApp.Infrastructure"));
}
The exact architecture-testing mechanism can vary, but the principle is the same:
Architecture rule
|
v
Executable test
|
v
CI
This approach works particularly well when architecture rules need more than simple project-reference checks.
Namespace-Level Architecture Rules
Project dependencies are only one layer.
A project can have internal architectural boundaries based on namespaces.
For example:
MyApp.Application.Commands
MyApp.Application.Queries
MyApp.Application.Services
MyApp.Application.Infrastructure
You may want to prevent:
Commands
|
X
Infrastructure
even though everything exists inside the same project.
Namespace-level rules require deeper analysis of source code and symbol references.
This is where static analysis becomes more useful than simply parsing project files.
API Boundary Rules
Another useful rule is preventing controllers from directly accessing persistence infrastructure.
For example, this may be considered a violation:
public class OrdersController : ControllerBase
{
private readonly AppDbContext _db;
public OrdersController(AppDbContext db)
{
_db = db;
}
}
The preferred architecture might require:
Join the conversation! Your thoughts help the community grow.