We can build software faster than ever now.
With AI-assisted development, scaffolding features, generating components, writing utilities, and even shaping entire flows can happen in a fraction of the time it used to take. That speed is exciting. It lowers the barrier to turning ideas into working products. It helps solo developers move faster. It helps teams prototype more aggressively. It helps side projects become real products. But it also introduces a new kind of risk: we can create code much faster than we can truly understand, review, and sustain over time.
In many projects, especially frontend projects, architectural problems do not appear all at once. They accumulate quietly. A component grows beyond its original responsibility. A shared UI element ends up living in the wrong place. A folder structure starts to drift. Warning signals become scattered. Complexity spreads across the workspace in ways that are easy to miss when all attention is focused on shipping the next feature.
That is the problem space that led me to build Modulens.
The source code and npm package links are available below.
Why I started this project
I kept coming back to the same thought: we already have tools that help us write code faster, but we do not always have equally strong tools to help us see the structural health of a project as it evolves.
When a codebase is still small, many things feel manageable. You can open a few files, navigate by memory, and reason about the whole system in your head. But once a project grows, that changes. The cost of understanding structure increases. Large components become normal. Risky patterns hide inside otherwise “working” code. The project may still compile, the UI may still render, and features may still ship, but maintainability starts to slip.
That is where I felt there was room for a tool focused on visibility.
Modulens is a brand of architecture, structure, and quality analysis tools for frontend workspaces. Right now, the Angular package is the first available implementation, while the broader repository is designed to support more frameworks over time.
What Modulens is
Modulens for Angular is a CLI tool that analyzes Angular workspaces and generates architecture, structure, and quality reports. Its goal is not to replace code review, static analysis, or team judgment. Its goal is to make certain signals more visible: large components, architectural risks, warning hotspots, and areas that may need refactoring.
That distinction matters to me.
I did not want to build a tool that simply says “this is wrong.” I wanted to build something that helps answer questions like:
- Where is complexity accumulating?
- Which parts of this workspace deserve attention first?
- Which components may be carrying too much responsibility?
- Where might maintainability start becoming expensive?
- What deserves investigation before it turns into a larger problem?
In other words, Modulens is meant to support architectural awareness.
Why Angular was the first step
I started with Angular because Angular projects often have a strong sense of structure, and that makes structural drift especially interesting. When the architecture is healthy, Angular workspaces can feel very clear and scalable. But when boundaries start to blur, the project can gradually become harder to reason about.
You might still have a working application, but the internal shape of the codebase may be telling a different story.
That makes Angular a good place to start for a tool like this. There is a lot of value in surfacing structural signals early, before teams normalize complexity just because the project continues to function.
The long-term idea is broader than Angular. The Modulens repository itself is intended as a multi-framework foundation, with Angular available today and future packages for other ecosystems being part of the vision.
How Modulens works today
The current Angular package is intentionally simple to start using.
You can install it globally and run modulens scan, or use it as a one-off command with npx @modulens/angular scan. It can scan the current working directory or a specific Angular workspace path.
npm install -g @modulens/angular
modulens scan
or:
npx @modulens/angular scan
his simplicity was important to me. I wanted the first run experience to be straightforward: point the tool at a workspace and get something useful back quickly.
By default, Modulens writes an HTML report under .modulens/reports/, opens it in the browser after a successful run, and also saves a JSON snapshot under .modulens/snapshots/ from the same analysis run. That means even when HTML is the main experience, the structured machine-readable result is still preserved.
The output philosophy: human-readable first, automation-ready too
One of the design decisions I care about most is the combination of HTML output for people and JSON output for systems.
The default HTML report is there because architecture and maintainability are often easier to understand visually. You want to scan patterns. You want summaries. You want to identify where to look first. You want something that feels explorable, not just a raw dump of data.
At the same time, structured JSON matters because modern workflows are increasingly automated. Teams may want to archive results, inspect them in scripts, use them in CI, or compare outputs over time. Modulens supports JSON output through --format json, lets you control output paths with -o / --output, supports --no-open for HTML generation without opening a browser, and even allows JSON to be written to stdout with --output -. HTML, intentionally, is not supported on stdout.
That split reflects how I think developer tools should behave: they should be useful both in a local developer workflow and in a more automated environment.
What the report is trying to reveal
The real value of a tool like this is not the scan itself. It is the questions the scan helps you ask.
A healthy project is not necessarily a project with zero warnings. A healthy project is one where important signals are visible, understandable, and actionable.
That is why Modulens is focused on surfacing things like:
- large components
- architectural risk signals
- warning hotspots
- areas that may need refactoring
- overall structure and quality patterns across the workspace
On the HTML side, the report includes an Overview section with an executive summary and Priority focus, specifically to make the first reading experience more useful. Instead of throwing the user directly into raw details, the idea is to first answer: What is the scale of what I’m looking at? What looks important? Where should I start?
That framing matters because analysis tools can easily become noisy if they do not guide attention.
Building for real workflows, not just demos
A lot of tools look good in isolated examples but feel harder to trust in day-to-day development. I wanted Modulens to move in the opposite direction.
That means caring about practical details:
- sensible default output behavior
- support for explicit file output paths
- support for JSON pipelines
- browser opening behavior that can be disabled
- a saved workspace snapshot from each successful run
- a public JSON shape with a top-level schemaVersion for compatibility awareness
The schemaVersion detail is especially important. If people want to build automation or downstream tooling on top of Modulens output, they need a stable contract mindset. The README explicitly distinguishes schemaVersion from toolVersion, which helps clarify how consumers should think about parsing compatibility versus tool release history.
That may sound like a small implementation detail, but for tooling, small details often shape trust.
The bigger motivation behind Modulens
I think developer tooling is entering a new phase.
For a long time, many tools focused primarily on syntax correctness, lint rules, formatting, and build pipelines. Those are still important. But the way we write software is changing. AI can help generate more code, more quickly, and with that comes a new pressure point: structural oversight.
The challenge is no longer only “can we produce code?”
It is increasingly “can we understand the system we are producing?”
That is the motivation behind Modulens.
I am interested in tools that help developers reason about software at a higher level:
- structure
- boundaries
- responsibility distribution
- maintainability trends
- architectural signals that are easy to miss when velocity is high
I do not think the answer is more noise. I think the answer is better visibility.
Why this is still an early project
Modulens is still early, and I think that is worth saying clearly.
I would rather publish a useful tool early, let real developers try it, and improve it through actual feedback than wait for some imaginary “perfect” version. Early tools have rough edges. They also have an advantage: they can evolve in direct conversation with the people who might use them.
That is how I want this project to grow.
The current release is focused on Angular workspaces, but the broader idea is intentionally larger. The repository is already framed as a foundation for a family of frontend workspace analysis tools, with Angular available first and React, Vue, and Flutter part of the broader direction I want to explore over time.
Who I think Modulens is for
I think Modulens can be useful for several kinds of developers:
Solo developers who are shipping quickly and want another layer of visibility before complexity gets away from them.
Frontend teams who want a faster way to inspect structural risk and identify where architectural attention is needed.
Tech leads and reviewers who want a higher-level view of maintainability signals across a workspace.
Developers experimenting with AI-assisted workflows who want speed without losing visibility into what the codebase is becoming.
If any of that sounds familiar, then Modulens is built with that kind of workflow in mind.
Try it
I recently released Modulens 0.2.0, and this is still just the beginning.
If you work with Angular and the problem of hidden architectural drift sounds familiar, I’d love for you to try it, inspect the output, and tell me what feels useful, what feels noisy, and what you would want a tool like this to detect next.
npx @modulens/angular scan
The package is available on npm, and the project is open on GitHub. The Angular package is currently the active entry point, and the repository positions Modulens as a growing set of frontend architecture, structure, and quality analysis tools.
If the future of software development is faster, then I think the future of tooling should also help us stay clearer about what we are building.
That is the idea behind Modulens.
GitHub: https://github.com/sinanyilmaz0/Modulens
Npm: https://www.npmjs.com/package/@modulens/angular
Top comments (0)