A Claims handler needs information from Submissions. There’s already a repository with the query it needs, so the handler calls it directly. The code compiles, the functional tests pass, and Claims now depends on an implementation detail that Submissions should be free to change. An architecture test can catch that reference. The tricky part is adding the test to a codebase that’s been running for years. If the first run finds 37 violations, fixing all 37 before you can turn on the check makes adoption harder. ArchGuard.NET lets you record those existing violations in a baseline and fail the build when a new one appears.
I’ll use a .NET 10 insurance application to show how to enforce module boundaries and vertical slice isolation in a single xUnit test, then introduce it into CI with a baseline.
Define the boundaries
The application has three modules, Claims, Submissions and Underwriting. Each lives under Insurance.Modules. In Claims, the namespace structure looks like this.
Namespace | What belongs there |
Insurance.Modules.Claims.Contracts
| Public types that other modules can reference |
Insurance.Modules.Claims.Infrastructure
| Persistence and other implementation details owned by Claims |
Insurance.Modules.Claims.Features.RegisterClaim
| The register-claim use case |
Insurance.Modules.Claims.Features.GetClaim
| The get-claim use case |
Apply the same convention to the other two modules. Claims can reference Insurance.Modules.Submissions.Contracts to get submission information. Submissions owns the implementation behind that contract, including database access. There’s a second boundary inside each module. RegisterClaim and GetClaim are separate slices, so one shouldn’t take a direct dependency on the other’s request or handler. Both can still use infrastructure within Claims. That keeps the slice policy compatible with handlers that access persistence directly.
Set up the test project
Create an xUnit project targeting .NET 10 and add the package.
dotnet new xunit -n Insurance.Architecture.Tests --framework net10.0
dotnet add Insurance.Architecture.Tests package ArchGuard.Net --version 1.0.0
Add project references from the test project to Claims, Submissions and Underwriting. The example uses a marker type in each module so the test can explicitly identify the assemblies to scan. Here’s the Claims marker.
namespace Insurance.Modules.Claims;
public sealed class ClaimsAssemblyMarker
{
}
Add equivalent SubmissionsAssemblyMarker and UnderwritingAssemblyMarker types to their respective module namespaces.
Configure the module and slice rules
UseModularMonolith() treats the first namespace segment beneath Insurance.Modules as the module name. The configuration below allows cross-module references through .Contracts. The preset also checks for references to another module’s infrastructure. UseVerticalSlices() works one level further down. With the feature root set to Insurance.Modules.Claims.Features, the next segment identifies the slice. Configure a feature root for each module so the rule checks individual use cases.
using System.IO;
using System.Runtime.CompilerServices;
using ArchGuard;
using Insurance.Modules.Claims;
using Insurance.Modules.Submissions;
using Insurance.Modules.Underwriting;
using Xunit;
public sealed class ArchitectureTests
{
private static ArchitectureRuleBuilder ConfigureRules()
{
var rules = ArchitectureRules
.ForAssemblies(
typeof(ClaimsAssemblyMarker).Assembly,
typeof(SubmissionsAssemblyMarker).Assembly,
typeof(UnderwritingAssemblyMarker).Assembly)
.UseModularMonolith(configuration =>
{
configuration.ModuleNamespaceRoot = "Insurance.Modules";
configuration.AllowedCrossModuleNamespaces = [".Contracts"];
});
string[] modules = ["Claims", "Submissions", "Underwriting"];
foreach (var module in modules)
{
rules.UseVerticalSlices(configuration =>
{
configuration.FeatureNamespaceRoot =
$"Insurance.Modules.{module}.Features";
});
}
return rules;
}
private static string BaselinePath(
[CallerFilePath] string sourceFile = "") =>
Path.Combine(
Path.GetDirectoryName(sourceFile)!,
"architecture-baseline.json");
[Fact]
public void Architecture_should_have_no_new_violations()
{
ConfigureRules()
.WithBaseline(BaselinePath())
.FailOnlyOnNewViolations()
.Assert();
}
[Fact(Skip = "Run explicitly when reviewing baseline changes.")]
public void Update_architecture_baseline()
{
ConfigureRules()
.WithBaseline(BaselinePath())
.UpdateBaseline()
.Assert();
}
}
The two tests share the same rules. The first is the one you run every day. WithBaseline() selects the JSON file, and FailOnlyOnNewViolations() enables the comparison. The second test writes the baseline and stays skipped during ordinary test runs. Include each new module’s assembly in the scan and add its feature root as the application grows. The assembly list controls which code the scanner inspects for outgoing dependencies.
Introduce the baseline
Temporarily remove Skip from the maintenance test and run just that test to capture your starting point.
dotnet test Insurance.Architecture.Tests/Insurance.Architecture.Tests.csproj \
--filter "FullyQualifiedName~Update_architecture_baseline"
Review the generated architecture-baseline.json, restore Skip and commit the baseline alongside the test. The path helper puts the file next to the test source and assumes you build and run in the same checkout. If your CI runs prebuilt tests from another machine, pass a path from the current checkout instead. Suppose the baseline contains 37 violations and a developer adds a reference from Claims to an Underwriting infrastructure type. The test fails on that new dependency. It also fails if the developer fixes one old violation in the same change. The total is still 37, but the new dependency has a different fingerprint. Each fingerprint records the rule and the source and target assemblies and types. That gives the check type-to-type granularity. A second use of a dependency you’ve already accepted can match the same fingerprint, and a type rename can change the fingerprint even when the underlying design stays the same. Remove baseline entries as you fix the corresponding dependencies. ArchGuard reports entries that no longer match as stale and leaves the file as it is during a normal test run. If a stale entry stays in the file, the same dependency could come back and be accepted again.
Run the check in CI
Run the architecture test project alongside your other tests. In a GitHub Actions job that has checked out the repository and installed the .NET 10 SDK, add this step.
- name: Check architecture boundaries
run: >-
dotnet test
Insurance.Architecture.Tests/Insurance.Architecture.Tests.csproj
--configuration Release
Keep baseline updates out of the routine CI run. When the test fails, the rule and the source and target types give you a specific reference to review. In the Claims example, the fix may be to expose the operation through the Submissions contract and keep the query inside Submissions.
Where ArchGuard.NET fits
ArchTestNet gives you a fluent API for expressing type and dependency rules. If you need a few targeted checks or broader framework support, it’s a reasonable choice. For this .NET 10 application, ArchGuard.NET gives me module and slice presets plus a JSON baseline in the same builder. That’s less policy to assemble by hand.The rules use namespaces and inspect compiled dependencies. Moving a file without changing its namespace leaves its classification the same. References resolved through reflection or runtime dispatch can escape these checks, and putting a type in .Contracts makes it eligible for cross-module use under this policy. The team still decides what belongs in that public namespace. I’d start by enforcing the module boundaries and feature roots the team already agrees on. Baseline the existing references once, then remove entries as you fix them. That lets the team start enforcing those decisions in CI while it works through the older dependencies.
ArchGuard.Net on NuGet
ArchTestNet on NuGet
Arun PottiPosted Nov 18, 2026, 11:00 PM
Good Article.