Architecture discovery

What source code mapping can reveal—and what it cannot

Repository indexing can expose structure that is hard to see by browsing files one at a time. It can also create a false sense of certainty unless teams keep its evidence and its limits in view.

When you inherit a codebase, a folder tree is only a rough guide. The names may be historical, runtime boundaries may be hidden across configuration, and a service’s most important dependencies may be spread across many files. Source code mapping offers another starting point: process code into a graph of files, symbols, and references, then explore patterns in that graph.

The open-source tld CLI documents tld index for indexing repositories. Its pipeline uses Tree-sitter grammars to parse files and external SCIP indexers or language tooling to resolve symbols and references. It can publish an immutable snapshot and, with --map, group the resulting graph into architectural components. That output is useful evidence, but it is not a complete or self-interpreting architecture description.

What an index can help uncover

A code graph can make some relationships easier to find: symbol references, package or project groupings, and areas where dependencies converge. For an unfamiliar repository, this helps narrow the questions to ask. Which packages seem central? What code refers to a particular interface? Which modules connect two parts of the application?

The project also supports repository snapshots, with a recorded Git revision, so teams can inspect indexed states over time. Its watcher can reindex changes in a Git checkout and produce new snapshots. In supported languages, language servers can help with incremental updates; other languages are reindexed from scratch. These capabilities can support exploration of change, but they should not be described as a guaranteed live view of every runtime interaction.

With mapping enabled, the CLI groups a dependency graph into components and creates a view that can be opened in the editor. This offers building blocks for an architecture diagram: source-linked elements and inferred groupings that can be copied, linked, or refined. The result is a way to start discussion with concrete repository evidence instead of drawing from memory alone.

What source relationships do not prove

A static reference is not automatically a runtime dependency. A package may be linked but unused in a particular deployment. Configuration, reflection, dependency injection, generated code, and network calls can all complicate interpretation. A code graph can miss relationships that happen outside the indexed source or that the available tooling cannot resolve.

Nor does a package boundary necessarily equal a service boundary. A monorepo may contain several deployables in one module tree, while a single deployment can span many packages. Infrastructure files and deployment manifests provide additional evidence, but even they may be environment-specific or stale. Confirm boundaries against build and deployment practices and ask the people who operate the system.

Most importantly, indexing cannot reliably infer ownership, business capability, trust boundaries, design rationale, or whether a coupling is intentional. Those are architectural interpretations. A cluster of related symbols might be a useful subsystem, a legacy tangle, or simply a shared library. Give generated groupings neutral labels until a person verifies what they mean.

How to validate a generated map

1. Check coverage. Confirm the languages and indexers available in your environment. The documentation notes that missing indexers are skipped, and indexing requires external dependencies.
2. Bound the question. Begin with one repository or workflow instead of asking a single view to explain an entire platform.
3. Compare multiple sources. Inspect deployment manifests, configuration, service ownership, and runtime behavior alongside the code graph.
4. Review surprising edges. Look for generated files, test-only dependencies, generic libraries, or references that do not represent deployed communication.
5. Ask maintainers to correct the story. Confirm element names, responsibilities, data flows, and boundaries with people who change and operate the code.
6. Keep only useful detail. Promote verified concepts into the overview and move implementation-level detail into a deeper view when it answers a real question.

Account for operational limits

The current indexing guide cautions that the pipeline is under active development and that large codebases may have rough edges or long runtimes. Starting on a smaller repository or branch makes it easier to establish prerequisites and inspect output. Run tld doctor to check local tool availability, and use the documentation for the supported indexers and exclusions.

Before indexing a large monorepo, exclude generated or vendored paths that add noise. Review what source is included and how the local tld data directory is configured, especially when repository contents are sensitive. Indexing is performed locally, but cloning a remote repository and obtaining indexer dependencies may use the network. Follow your organization’s normal rules for source access.

Turn evidence into an architecture people can use

Use code mapping to accelerate discovery, then shape a separate, intentional view around the audience’s task. A developer may need a package-level path for navigation; an incident review may need only the services and dependencies involved; a stakeholder may need the system boundary and external actors. One generated graph rarely serves all of these purposes without editing.

When a generated map is corrected and maintained alongside code or deployment context, it becomes a more useful entry point for onboarding and change review. Its credibility depends on transparent limitations and human review. The graph can show where to look. The team must decide what the system means.

Read the indexing guide and explore the open-source tld repository for current prerequisites, language support, and workflow details.