Understanding a New Codebase

ix map clusters files into regions based on actual coupling (calls + imports), not folder names. The confidence score tells you how cohesive each grouping is.

ix map

Architectural Map — 140 files · 10 regions

●  SYSTEM  Api  65 files  Moderate 74%
   ├─  MODULE  Context    14 files  Moderate 51%
   └─  MODULE  Map         4 files  Moderate 53%

●  SYSTEM  Cli  75 files  Moderate 73%
   ├─  MODULE  Cli        58 files  Well-defined 75%
   ├─  MODULE  Explain     7 files  Fuzzy 46%
   └─  MODULE  Builder     7 files  Fuzzy 44%

Without opening a single file, you know: 2 major systems (Api, Cli), and the Context module needs attention (51%).

The entities with the most dependents are the concepts you need to understand first.

ix rank --by dependents --kind class --top 10

  1. NodeId              58 dependents   core identifier type
  2. Rev                 48 dependents   versioning type
  3. IxClient            45 dependents   CLI HTTP client
  4. ArangoClient        27 dependents   database layer
  5. Ok                  24 dependents   result type
  6. GraphPatch          14 dependents   mutation model
  7. ClaimId             14 dependents   claim identifier

These are the load-bearing entities. If you’re onboarding, start here.

Take the top results and explain each one. The explain engine uses 18-rule role inference and 4-tier importance scoring.

ix explain IxClient

IxClient (class) — ix-cli/src/client/api.ts

  Role: api-client (high confidence)
    Class with API/client naming and HTTP-like methods
    Used by 30 callers / 45 dependents

  Importance: high — broad-shared-dependency
    45 dependents, 30 callers
    81 downstream dependents across 4 levels

  Members: search, explain, expand, commitPatch, commitPatchBulk,
           ingest, map, smells, subsystems, ... (37 total)

  Used by: registerReadCommand, registerExplainCommand,
           registerPatchesCommand, and 42 others.

Without reading a single line of source: IxClient is the 37-method HTTP bridge between every CLI command and the server. It’s the most important class in the CLI layer.

Use contains to see what’s inside a class.

ix contains ArangoClient

ArangoClient contains:
  execute              method
  query                method
  beginTransaction     method
  commitTransaction    method
  ensureSchema         method
  createDatabase       method
  ... (20 total)

Pick two things that seem related and follow the edges.

ix callers ArangoClient
ix imported-by ArangoClient

ArangoClient is called by:
  Main               (Main.scala)

ArangoClient is imported by:
  ArangoGraphWriteApi.scala  (memory-layer/.../db/)
  ArangoGraphQueryApi.scala  (memory-layer/.../db/)
  BulkWriteApi.scala         (memory-layer/.../db/)
  MapService.scala           (memory-layer/.../map/)
  SmellService.scala         (memory-layer/.../smells/)

The picture emerges: every CLI command imports IxClient → calls REST routes → routes delegate to services → services use ArangoClient → ArangoDB.

All of this was built using 6 commands: map, rank, explain, contains, callers, imported-by. Zero file reading.