Make large codebases small enough to reason about

Large projects do not fail because they have too many packages. They fail when every view shows everything at once. A full dependency graph is useful only after you have made it smaller, or after you have switched to a view that answers a narrower question.

AtlasArc handles large projects by reduction. Set the relevant module, package, or source folder as Current Focus, pin a structural subject when outside relationships matter, contract pass-through package folders, roll deep namespaces up for triage, filter weak or irrelevant dependencies, and switch from the graph to Matrix, Subsystems, Hotspots, or Composition when another lens is more honest about the problem.

Use this page as a field guide. It starts with the moment the graph is too large to read and ends with the exact dependency examples, source files, and exports you need for a review or refactoring ticket.

Start with a readable map

The first mistake on a large codebase is to expand everything. That gives you a diagram of the scanner's completeness, not a map of the architecture. AtlasArc starts from the opposite direction: show the first level where real package relationships are visible, then let you open more detail only where it helps.

• Smart initial expansion opens namespace levels until at least one dependency edge is visible. You do not start at a blank root folder, and you do not start at every leaf package.
• Contracted package folders merge pass-through namespace chains into one labelled path. A chain like org -> example -> util can appear as org.example.util when the intermediate folders carry no separate architectural contract.
• Expansion controls let you open one package, expand the shallowest collapsed level, collapse the deepest expanded level, collapse all, or expand all. On large graphs, risky broad operations are guarded before they redraw too many nodes.
• Package internals can open one visible package/source folder into contained classes or files in the Topology Graph. This is for local evidence after you have found the owner, not something Expand All does across the project.
• Reset takes you back to the same edge-visible baseline after an aggressive filter pass or a dead-end exploration.

Contracted folders are deliberately conservative. AtlasArc does not absorb a leaf package, a direct cycle participant, the current Focus root, a Safe Haven, or a folder with multiple visible children. The point is to remove namespace ceremony, not hide a meaningful boundary.

Start here when the first graph looks either too empty or too dense. Before changing any filters, check whether the default expansion has already found the first useful architectural layer.

Choose what should stay in view

The fastest way to make a large project readable is to stop looking at all of it. Sometimes the question lives inside one module or package. Sometimes one subsystem, boundary, or cycle group is the subject and its outside relationships need to remain visible. AtlasArc gives those different questions different controls.

• Focus names the module, package, or source folder every lens currently opens on. Use it when the question is "what is happening inside com.acme.billing?" rather than "what is happening everywhere?"
• Set as Root is the explicit package or module command that updates Current Focus, so a Root chosen in one lens carries into the next one.
• Show in AtlasArc from the IntelliJ Project tree starts from the package you already selected in the IDE. You do not have to copy a package name into a filter box.
• Pinned subject in Graph shows a package or subsystem with its perimeter neighbours. Use Neighbour links for local blast radius: "what touches this, and what does it touch?"
• Boundary reads emphasize traffic crossing a subsystem perimeter. Use Direction, and Mute cycles when needed, when the question is whether a module boundary is holding.
• Cycle View holds one selected cycle group as the structural question, with enough ancestors expanded to keep the shape readable.
• Breadcrumbs in focus-based lenses let you drill into a subsystem and climb back out without rebuilding the package path in your head.

Use Root when the question stays inside one module, package, or source-folder subtree; use a pinned subject for a local dependency perimeter or boundary read; use Cycle View when the subject is already a strongly connected group. Neighbourhood and Boundary are explanatory readings of a pinned subject, not separate product modes. These are different reductions, not synonyms.

Roll up detail without losing signal

Even after choosing Current Focus, a Java, Kotlin, or TypeScript hierarchy can be deeper than the architectural question. In that case, read the shape first and expand the exact branches later. AtlasArc gives you several ways to reduce depth while preserving the signals that matter.

• Deep Package Rollup groups packages below a selected namespace depth into their visible parent. Lower the depth to inspect the dependency shape at namespace level; raise it again before planning a code edit.
• Contracted package folders remove single-child pass-through chains before they waste visual space. They are useful even when depth rollup is off.
• Collapsed-folder cycle indicators draw a dashed border on a folder whose descendants contain a cycle. You can stay at a high level and still see where hidden tangles live.
• Subsystem rollups attach subtree metrics to folder nodes: architecture-unit count, class or source-file count, lines of code, boundary fan-in, boundary fan-out, cohesion, instability, cycle groups, visibility, abstractness, and complexity.
• Adaptive Treemap shows a meaningful frontier through the package tree. It is more informative than only direct children, and less overwhelming than every leaf package at once.

The important detail is that subsystem health is computed from the repository-scoped structural graph, not from whatever happens to be visible after your current view filters. A filtered view can be narrow; the rollup metrics still describe the in-scope subsystem underneath it.

Progressively reveal the whole project: enable rollup and choose the lowest depth that still separates meaningful hierarchy branches, then use Expand All. The hierarchy is now fully expanded underneath the rollup, so raise Rollup depth one step at a time to reveal the next namespace level beneath Current Focus. Stop as soon as the added detail makes the diagram harder rather than easier to read, then set the suspicious package as Root before drilling further.

Filter the noise

On a large project, filters are how you make a question precise enough to answer. Start with a broad scope, then use thresholds and view exclusions until the remaining packages all have a reason to be on screen. Hiding something from the view does not remove it from the analyzed architecture.

• Reference-count range lets you look at dependency weight from both directions. Raise the minimum to keep only strong coupling. Set a low maximum to expose tiny, accidental-looking edges crossing a boundary.
• Fan-in and fan-out ranges find structural roles. High fan-in points at packages many others depend on. High fan-out points at packages that know too much. Low values can expose fragments, hermits, and packages in the wrong place.
• Hide isolated removes packages left with no visible edges after filtering. This keeps a strict filter from leaving visual debris across the canvas.
• Current Focus accepts a package or source-folder prefix and directly narrows the visible structural model to that namespace. It changes navigation without changing the underlying evidence, and it is not an Exclusions pattern.
• View-only patterns hide known-noise families by prefix, suffix, or substring for the current investigation. The underlying packages still contribute to rolled-up metrics and cycle findings. Use them for a temporary reading of generated code, framework adapters, test fixtures, or another namespace you do not need on screen right now.
• Hide this package from view in a package context menu adds one module-aware subtree entry to the View-only list and applies it immediately. It hides the selected package and descendants in that same module without affecting an equal package name owned by another module.
• Search / Spotlight is for orientation rather than scoping. It highlights matches and immediate neighbours while dimming the rest.
• Analysis scope, the second mode in the Exclusions section, summarizes durable repository policy and opens the Governance hub. Use it when a package or TypeScript source folder must stay outside evaluation for every teammate, whole-model report, and CI run. It is applied before metrics and cycles rather than as a screen filter.
• Status Cluster is a fixed strip of indicator lamps that always shows what is narrowing the model and view. Scope discloses committed repository policy; reference/fan filters, local Exclusions, Hide isolated, and Only Cycles expose transient narrowing so it is not mistaken for the whole architecture.
• No-results feedback explains when active Filters have hidden everything and offers a scoped Filters action that neutralizes reference and fan bounds plus Hide isolated. It does not Reset View or clear Current Focus, Cycles, Exclusions, Safe Havens, or lens state.

Do not treat one filter setting as "the architecture." Treat each filter as a hypothesis. For example: "show packages with high fan-in and low fan-out," "show boundary edges with at most two references," or "show only cycle participants under this module." Because the Status Cluster keeps every active filter in view, you can narrow the model hard without losing track of how much you have hidden — the warning arrives while you are still narrowing, not only when the graph is already empty.

Use the right lens for the question

A graph is the right lens when you need shape: paths, neighbours, clusters, and visible cycles. It is not always the right lens for direction, relative size, subsystem comparison, or metric outliers. AtlasArc keeps one shared architecture model underneath the lenses, so switching views changes the question without discarding the scope you already chose.

• Topology Graph answers "how is this connected?" Use it for local neighbourhoods, cycle shape, source-level dependency inspection, and package-local class/file tangles.
• Package Matrix answers "who depends on whom?" Use it when graph layout becomes tangled but direction and bidirectional coupling still matter; its rows and columns remain packages/source folders.
• Subsystems answers "which architectural boundaries are under pressure?" It maps the package or source-folder units currently visible through shared expansion, including terminal units and dashed-ring aggregate parents.
• Hotspots answers "which packages or classes deserve attention first?" Map compares the first four signals directly. Galaxy adds depth and reveals real dependencies between nearby package candidates.
• Composition answers "what is this codebase made of?" Use Treemap, Sunburst, or Circle Pack to see where code mass, complexity, or coverage gaps concentrate in the hierarchy.

The escape route from an unreadable graph is often not "tune the graph harder." If you are checking intended dependency direction, use the Matrix. If you are mapping pressure across visible architecture boundaries, use Subsystems. If you are building a refactoring shortlist, use Hotspots. If you are trying to understand where the code lives, use Composition.

Triage cycles one group at a time

Cycle detection is more than a red highlight. On a large project, the useful question is not "are there cycles?" It is "which cycle group is this, what kind of cycle is it, and what decision does it need?" AtlasArc separates the full structural graph from the problem graph: the subset of packages and edges that participate in unresolved cycle problems.

• Only Cycles removes clean packages and non-cycle edges, leaving cycle-relevant structure instead of the full dependency model.
• Cycle detail levels step from full context to architectural violations only. Use the early levels to understand context; use Architectural when you need the hardest violations without nested or accepted noise.
• Cycle-group navigator walks strongly connected groups one at a time. The point is to make "there are many cycles" become "this is group 3, and these are the packages keeping it alive."
• Cycle groups panel shows group membership and severity badges, and lets you mute groups you have already triaged.
• Classification distinguishes architectural cycles, aggregation cycles, nested-internal cycles, and governed cycles, so loops that disappear when folders are expanded and decisions the team already recorded are not mistaken for new architectural problems.
• Safe Havens remember broad package or source-folder cycle suppression in your workspace. Repository governance gives you precise Intentional/Debt control with a searchable reason, optional ticket, and lifecycle status in .atlasarc/governance/cycles.json. Commit that file when other developers and CI should use the same decisions.

A good cycle triage pass usually has three outcomes: refactor now, record a debt item, or sanction an intentional exception. AtlasArc keeps those decisions visible instead of pretending accepted coupling disappeared.

Useful next steps: run the Find cyclic dependencies workflow for discovery, then use Audit individual cycle groups when the backlog is large enough to need a group-by-group pass.

Prioritize what to fix first

Reduction gets the model small enough to inspect. Prioritization decides where effort pays off. Do not fix the first red node just because it is visible. Compare coupling pressure, stability, size, complexity, coverage, and subsystem context before choosing the next refactor.

• Heatmaps overlay metrics on Topology, Matrix, and Composition: instability, abstractness, distance from the main sequence, relative visibility, fan-in, fan-out, size, complexity, and coverage.
• Metric thresholds keep colour honest. A mostly healthy project should not look dangerous just because one package is the worst in that particular graph.
• Hotspots Map gives you a direct shortlist across four metric channels. Continue that same reading in Galaxy when architectural reach and dependency Routes should help decide which candidate comes first.
• Subsystems curated views focus the map: Boundary Risk for perimeter pressure, Complexity Load for contained complexity, Visibility Surface for public shape, and Internal Tangles for fully contained package-cycle groups.
• Boundary Flow shows the strongest incoming and outgoing neighbours of a selected subsystem. If the boundary is too busy for the glyph, open the Boundary Matrix.
• Coverage and complexity overlays expose complex code whose branches are not protected by tests. That is usually characterization-test work before refactoring work.
• Workflow Wizard recipes turn common investigations into repeatable setup: backbone packages, packages that know too much, accidental boundary leaks, hard-to-change packages, ticking time bombs, and more.

For a first prioritization pass on an unfamiliar large project, start with Show me the backbone, then compare Identify risky hotspots and Understand subsystem coupling. If coverage data is available, add Complex code with weak coverage before committing to a risky refactor.

Drill to evidence and report

A reduced visual finding only matters if it becomes evidence. Once you have narrowed a large project to a package, boundary, cycle, or hotspot, the next step is to inspect the actual dependency examples and produce something the team can act on.

• Edge examples show reference counts and concrete usages behind a dependency. Each example can jump to the exact source line in the IDE.
• Package and metric sidebars keep context in place: dependency lists, cycle warnings, Safe Haven controls, class or source-file counts, lines of code, fan-in, fan-out, complexity, coverage, and metric caveats.
• Source navigation works from bubbles, matrix cells, edge examples, and context menus. Use the visual model to find the issue, then jump to the package or class that needs work.
• Scoped DOT export preserves the focused graph you actually reviewed, including active focus, exclusions, hide-isolated, Only Cycles, and expand/collapse state.
• Data exports let Matrix, Subsystems, and Hotspots leave the IDE as TSV or CSV when a spreadsheet or design note is the next step.
• Architecture Reports turn a project baseline, subject audit, boundary review, cycle triage, or current investigation into browsable HTML with a Printable Version for PDF or meeting packets.

The strongest reports are scoped to a decision. Generate a whole-project baseline when you need trend comparison; generate a subject, boundary, cycle, or current-investigation report when you need evidence for the next action.

Built to stay fast

The reductions above are not cosmetic browser tricks. AtlasArc computes the meaningful reductions in the plugin backend and sends the UI a view model that already reflects Current Focus, filters, cycle detail, rollup, and lens data.

• Large Graph Guard warns before operations that would render too many nodes, such as Expand All or broad layout changes. It suggests cheaper alternatives: Only Cycles, Matrix, Set as Root, Subsystems, Hotspots, or Composition.
• Matrix safety limits cap package count and minimum zoom so a huge matrix does not become unusable by default.
• Backend-computed filters apply reference ranges, fan-in/fan-out ranges, isolated-node removal, exclusions, Only Cycles, and cycle detail levels before the frontend tries to render the result.
• Precomputed composition frontiers make Adaptive Treemap steps cheap. Density and reach controls index into sequences prepared during analysis instead of recalculating the hierarchy in the browser.
• Raw-graph subsystem metrics keep folder health stable even when the visible graph is filtered down for a narrow question.

This is why the large-project strategy is reduction, not force. You should not have to wait for a huge full graph before you can ask a smaller question.

Where to go next

To see the same reduction ideas in the product story, open the product overview. To try them on your own repository, start with Getting started. For guided investigations, use the workflow library: it turns the moves above into concrete questions such as finding cycles, reviewing package boundaries, identifying hotspots, auditing a subsystem, or preparing an architecture health review.