Search for a command to run...
Joining a MediatR codebase mid-flight means archaeology. What commands exist? Who handles them? Which ones are validated, and by what? The honest answers live scattered across hundreds of files, and the usual tool is grep plus patience. CqrsLens is the tool I wanted instead: point it at a .NET solution and it draws the system — project dependencies, Clean Architecture layers, and the full CQRS surface — as Mermaid diagrams in a single report. It is open source, and it is on NuGet: version 0.2.0 shipped today.
postCompanion article: CQRS without the cargo cult — when MediatR helps and when it hurtsProject dependency graph — every project in the solution and what references what, parsed from the .csproj files.
Layer diagram — projects grouped by Clean Architecture convention (Domain, Application, Infrastructure, Api, Web, UI), with a folder-based fallback.
The CQRS map — every request (command or query), the handler that answers it, and the validators attached to it, in Markdown or as a self-contained HTML report.
Pipeline behaviors — every IPipelineBehavior implementation in the codebase, listed.
DbContext overview — each EF Core context and the DbSets it exposes.
Architecture checks — requests with no handler and layer-rule violations flagged in the report, with a --strict mode that fails CI on errors.
Before trusting it on anyone else's code, I ran CqrsLens on the backend of the site you are reading. It found 5 projects, 62 requests, 63 handlers, 9 validators, 1 pipeline behavior, and 1 DbContext — an exact inventory of the system, produced in about a tenth of a second, without building the solution. The diagram above is that run's project graph; below is an excerpt of its CQRS map (the full map carries all 62 requests).
Version 0.1 linked handlers by simple type name. This codebase contains two different classes both named TogglePostLikeCommand — one in the Likes feature, one in Posts — and the old lens merged them into a single node whose row falsely showed no handler. Version 0.2 links by fully-qualified, namespace-aware names, and the two commands now stand separately, each with its own handler. It is the kind of collision that only shows up on real code, which is exactly why the tool gets run on a real system before every release.
Custom marker interfaces — requests followed through ICommand/IQuery-style hierarchies (--markers), not only textbook IRequest implementations.
Namespace-aware linking — same-named requests in different namespaces keep their own handlers and validators.
Multiple DbContexts in one file — DbSets attributed to their enclosing context class.
HTML reports — --format html produces a self-contained page with stat cards and rendered diagrams.
Architecture checks and --strict — missing handlers and layer violations can fail a CI build (exit code 4).
Parallel scanning — large solutions scan concurrently, with generation time printed in the report.
A GitHub Action — any repository can add CqrsLens to its pipeline in a few lines.
Static analysis only: CqrsLens parses project files as XML and scans C# sources for the MediatR shapes. No compilation of your code, no execution, nothing leaves your machine. The current engine is text-based and honest about it — the Roslyn semantic engine is the next milestone.
CqrsLens ships with a sibling library, Hakim.Pipelines (also on NuGet): production-ready MediatR pipeline behaviors — logging, performance, validation in throwing and Result-based flavors, transactions, and caching — registered with a single AddPipelines() call. The lens draws the systems; the pipelines help build them.
Development is public and paced like a real project — small releases, each closing real issues:
Next: Roslyn semantic analysis (exact symbol resolution), an EF Core ER diagram, and pre-rendered SVG diagrams for zero-JavaScript reports.
Then: an MCP server, so AI coding agents can query the architecture map directly instead of guessing from grep.
Always: correctness on real codebases first — every release is validated against this platform's backend before it ships.
Open source under MIT. If you run a MediatR codebase, I would genuinely like to hear what the lens shows you.