# How the Guided Tour Generator in Understand-Anything Determines Learning Order

> Discover how Understand Anything's guided tour generator creates an optimal learning order by analyzing knowledge graphs complexity and dependencies.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-09

---

**The guided tour generator creates a dependency-aware learning path by analyzing the project's knowledge graph, scoring modules by complexity, and topologically sorting them to ensure foundational concepts appear before dependents.**

The Egonex-AI/Understand-Anything repository features a sophisticated guided tour generator that automatically constructs step-by-step learning paths for complex codebases. This system, implemented primarily by the **tour-builder** agent, determines the optimal learning order by parsing structural relationships and calculating complexity metrics. Understanding this process helps developers customize their onboarding experience and debug tour generation issues.

## Three-Phase Architecture for Determining Learning Order

The guided tour generator operates through a structured three-phase pipeline that transforms raw source code into an ordered educational experience.

### Phase 1: Project Scanning and Knowledge Graph Construction

The process begins with the **project-scanner** agent, which walks the repository and parses source files using **tree-sitter**. This agent extracts symbols, imports, and export relationships from the codebase.

All discovered entities become nodes in a **knowledge graph** stored at [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). Edges in this graph encode *"depends-on"* relationships, where `A → B` indicates that module A imports or depends on module B. This graph structure serves as the foundation for all subsequent ordering decisions.

### Phase 2: Dependency Weighting and Prioritization

Once the graph is constructed, the tour-builder assigns a **complexity score** to each node. The scoring algorithm considers multiple factors:

- **Depth** – The longest path from a leaf node, measuring how many transitive dependencies a module has.
- **Fan-in / Fan-out** – The number of incoming and outgoing edges, where high fan-in indicates a core utility used by many components.
- **File size and type** – Smaller utility files receive lower weights than large components.

Nodes are sorted by descending score, with alphabetical ordering used to break ties and ensure deterministic output.

### Phase 3: Topological Sorting and Tour Generation

The final phase applies a **topological sort** to the weighted graph, ensuring every module appears *after* all of its dependencies. This algorithm respects the dependency relationships established in phase 1 while incorporating the complexity rankings from phase 2.

The sorted list transforms into discrete **tour steps**, each containing a description, code-snippet preview, and link to the file viewer. The complete tour serializes to [`.understand-anything/tour.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/tour.json) and renders in the dashboard's *Info* sidebar via [`src/onboard-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/onboard-builder.ts).

## Key Implementation Files

The guided tour generator relies on several critical components across the codebase:

| Component | File Path | Role |
|-----------|-----------|------|
| Tour-builder logic | [`agents/tour-builder.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/tour-builder.md) | Defines the scoring algorithm and ordering logic. |
| Project scanning | [`agents/project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/project-scanner.md) | Walks the repository and constructs the knowledge graph. |
| Knowledge-graph schema | [`packages/core/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/schema.ts) | Provides TypeScript types for nodes and edges. |
| Dashboard integration | [`src/onboard-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/onboard-builder.ts) | Renders tour steps in the UI. |
| Graph utilities | [`src/context-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/context-builder.ts) | Supplies topological sort and traversal helpers. |

## Triggering Tour Generation

The guided tour workflow activates automatically after a successful `/understand` run. From the CLI, you can trigger full analysis and tour generation with:

```typescript
// Example: invoking a guided tour from the CLI
await runCommand('/understand --full'); // triggers analysis → tour generation

```

This command initiates the project scanning phase and propagates through the complete pipeline to generate the final tour.

## Working with the Tour Data

Developers can interact with the generated tour programmatically. The tour-builder imports graph utilities from [`context-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/context-builder.ts) to perform the topological sorting:

```typescript
// Inside tour-builder (simplified)
import { topologicalSort } from './context-builder';
import { Graph } from '@understand-anything/core';

// Build weighted list
const weighted = graph.nodes.map(n => ({
  id: n.id,
  weight: computeScore(n, graph)   // depth, fan‑in/out, size…
}));

// Sort respecting dependencies
const ordered = topologicalSort(weighted, graph.edges);

```

The resulting ordered array determines the sequence of steps presented to learners.

## Summary

- The **guided tour generator** constructs a **knowledge graph** by parsing the repository with tree-sitter and extracting dependency relationships.
- It calculates **complexity scores** based on depth, fan-in/fan-out, and file size to prioritize learning modules.
- A **topological sort** ensures that every module appears after its dependencies, creating a logical learning progression.
- The final tour serializes to [`.understand-anything/tour.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/tour.json) and renders in the dashboard sidebar.

## Frequently Asked Questions

### What file stores the generated knowledge graph?

The project-scanner agent outputs the dependency graph to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). This file contains all nodes representing code entities and edges encoding "depends-on" relationships used by the tour-builder to determine learning order.

### How does the generator calculate which module to show first?

The tour-builder assigns complexity scores based on three metrics: **depth** (transitive dependency chain length), **fan-in/fan-out** (connectivity to other modules), and **file size**. Modules with the highest scores—typically foundational utilities with high fan-in—appear earliest in the sequence, provided they have no unmet dependencies in the topological sort.

### What ensures that dependencies are learned before dependents?

The **topological sort** algorithm implemented in [`src/context-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/context-builder.ts) guarantees that every module appears in the tour only after all its dependencies have been presented. This respects the directional edges in the knowledge graph where `A → B` indicates A depends on B.

### How do I trigger the guided tour generation process?

The tour generation process triggers automatically following a successful `/understand` command execution. Use the `--full` flag to initiate the complete pipeline from project scanning through tour serialization, as implemented in the CLI command handler.