Blog
Writing about software structure, dependency graphs, coupling, circular dependencies, and different approaches to understanding large codebases.
What Changed Inside the PViz Analyzer, and Why the Service Is Now Free
More languages, compiler-assisted call resolution, honest reporting of what the analyzer cannot see, and why PViz moved from tokens to free use with fair-use limits.
Build Graphs: How Build Systems Know What to Rebuild
How dependency graphs let build systems determine build order, incremental rebuild scope, parallel work, and when an undeclared dependency makes the result unreliable.
Dependency Graphs Were Never Just About Imports
A practical guide to the different kinds of software dependency graphs—from build and module graphs to call, data-flow, deployment, and change-coupling graphs—and the engineering questions each can actually answer.
Onboarding Agents to an Unfamiliar Repo
How to structure an agent's system prompt so it starts with a meaningful working model of a codebase — not a complete one, but enough to reason about what it doesn't know.
Building a Codebase Q&A Pipeline With a PViz Bundle
How to apply retrieval-augmented generation to a PViz dependency bundle for open-ended codebase questions. Covers chunking strategy, embedding, retrieval quality, and generation prompt design.
Change Impact Analysis With an Agent: Scope With Structure, Confirm With Source
A workflow for using a PViz structural bundle and a three-tier evidence framework to scope change impact before a PR ships — with a worked example.
Scoping Agent Context with the Node Graph
Why giving an agent the full dependency bundle is usually the wrong move, and how lazy subgraph scoping keeps codebase context focused, auditable, and useful.
Your First Prompt with a PViz Bundle
How to construct a bundle-grounded LLM prompt for codebase questions — with a worked example using Scrapy.
Why LLMs Struggle With Large Codebases: The Context Problem
LLMs can help with individual code files, but they often struggle with large codebases because raw code is not structured context. Learn why dependency graphs and PViz bundles give AI tools a better map of your software.
Reading the Graph: Using Your Dependency Graph to Find the Hidden Seam
Before you extract a service, look at your dependency graph. The seams are already there — dense clusters, accidental bridges, and boundaries that can become clean internal interfaces or future services.
Reading the Graph: How Helper Modules Become Load-Bearing Walls
utils.py starts as shared helper code, then quietly becomes one of the most imported files in the codebase. Learn how to spot the utility-module anti-pattern with dependency graph fan-in and refactor it safely.
Reading the Graph: The Upward Arrow and Abstraction Layer Violations
How implementation code that reaches into higher-level business logic silently erodes your architecture—and how to find, diagnose, and fix abstraction layer violations using dependency graph analysis.
Reading the Graph: The Island Pattern and the Ownership Vacuum
How isolated clusters in your dependency graph create silent liability—and how to identify whether to integrate, extract, or delete them before they become an incident.
Reading the Graph: The Hourglass Pattern and the Structural Chokepoint
High fan-in above, high fan-out below — the hourglass module sits at a structural pinch point where everything converges. Learn how to find it, recognize it in code review, and decide whether to decompose it or protect it.
Highly Coupled Codebases: How to Recognize and Refactor a Dependency Mesh (Updated 10JUN26)
Learn how highly coupled codebases form dependency meshes, how to identify them with graph analysis, and how to recover structure through seams, SCC reduction, and incremental refactoring.
Reading the Graph: Dependency Chains and Hidden Code Complexity
How long dependency chains in your codebase quietly increase complexity, slow development, and expand blast radius—and how to identify and collapse them using dependency graph analysis.
Reading the Graph: The Star Pattern and the God Module Problem
How to identify and decompose star-shaped dependency patterns before they become the single point of failure your entire codebase revolves around
How to Measure Codebase Complexity for Developer Onboarding (Updated 10JUN26)
Use dependency analysis, fan-in, fan-out, circular dependencies, test coverage, and graph depth to identify which parts of a codebase are hardest for new developers to learn.
Beyond Code Coverage: Dependency Diff Reviews for Catching Architectural Drift
Code coverage tells you whether your code works. Dependency analysis tells you whether your architecture still makes sense. Most teams only automate one.
TypeScript Module Boundaries: Barrel Files vs Clean Architecture
Barrel files look clean but create hidden coupling. Here's how to organize TypeScript modules for real maintainability.
Python Circular Imports: How to Find and Fix Circular Dependencies (Updated 10JUN26)
Learn why Python circular imports happen, how partially initialized modules cause runtime failures, and how dependency graphs help expose and fix architectural cycles.
Technical Debt Archaeology: What Your Dependency Graph Reveals
How dependency graph analysis, circular dependency detection, and co-change analysis help you prioritize technical debt based on measurable impact instead of opinion.
Monolith to Microservices: Finding Your Bounded Contexts
Use dependency graph analysis to identify natural service boundaries instead of guessing
The Hidden Cost of God Objects: A Data-Driven Analysis
Using dependency graphs to measure the real impact of bloated classes on your codebase's maintainability and team velocity
Legacy Code Onboarding in 2 Hours: A Structural Analysis Framework
A practical 2-hour framework for understanding unfamiliar codebases through structural analysis, not comprehensive reading. Learn to identify risk, coupling, and technical debt without reading every line.
Code Coupling: What It Is and How to Reduce It
Learn what code coupling is, why it matters, how to measure it with fan-in/fan-out metrics, and proven strategies to reduce coupling in your codebase.
What Are Circular Dependencies? Cycles, SCCs, and How to Fix Them (Updated 10JUN26)
Learn what circular dependencies are, why strongly connected components matter, how dependency cycles form, and practical strategies for detecting, breaking, and preventing them.
What Is a Code Dependency Graph? A Developer’s Guide (Updated 10JUN26)
Learn what code dependency graphs are, how to read nodes and edges, and how dependency analysis helps developers understand architecture, coupling, cycles, refactoring risk, and onboarding.
The Inherent Difficulty of Trying to Understand New Codebases
Most approaches to understanding new codebases don't work well. Here's what actually happens when you inherit unfamiliar code — and a better way.
Topics
Try PViz on your own codebase
Get dependency graphs, architectural insights, and a compressed bundle ready for your LLM, for GitHub repositories, free with an account.