Architecture
This page is for engineers evaluating Travsr or contributing to it. It explains how every component fits together.
Overview
git commitCrate structure
Travsr is a Rust workspace. The dependency graph is strictly acyclic:
travsr-core Foundation. Node, Edge, EdgeKind, VName (Kythe address),
NodeId (BLAKE3), and ppr_weight(). No internal deps.
travsr-error Shared error taxonomy (StoreError, IndexError,
TravsrError). No internal deps.
travsr-ipc Control-plane transport (Unix socket / Windows named
pipe) between the CLI and the running daemon. No
internal deps.
travsr-config Layered, typed configuration. Resolution order, highest
precedence first: CLI flag, environment variable,
per-repo .travsr/config.toml, global
~/.travsr/config.toml, built-in default. A pure
resolver: callers do the I/O at the edges and pass
values in, so the same inputs always produce the same
result. No internal deps.
travsr-rerank In-process cross-encoder relevance arbiter. Pure ONNX
inference over (query, candidate) pairs, batched across
rayon's thread pool. No internal deps.
travsr-plugin-protocol Depends on: core, error
Plugin trait, wire message types, length-prefixed frame
codec for sidecars (language and embed).
travsr-plugin-sdk Depends on: plugin-protocol, core
The harness a sidecar binary links against to implement
the protocol.
travsr-analysis Depends on: core
Phase A. Tree-sitter parsers for every language, the AST
"skeleton" builder used for embedding text, snippet
extraction, and data-format parsing (JSON, YAML, TOML,
XML).
travsr-store Depends on: core, error
SQLite (WAL) backend: nodes/edges/files/meta tables, FTS5
search, migrations, RBAC columns.
travsr-indexer Depends on: core, analysis, error
Orchestrates indexing: Phase A parsing, Phase B LSIF/SCIP
runners, the SCIP unifier, the sandbox, and file hashing.
travsr-retrieval Depends on: core, error, store
Algorithms: BFS, PPR (ppr / ppr_weighted), Dijkstra +
λ-corridor execution paths, k-core, BM25, 0-1 knapsack,
and RBAC edge filters.
travsr-plugin-host Depends on: plugin-protocol, core, error, indexer,
analysis, config
Owns the trust boundary. Hosts native and sandboxed
Phase B language analyzers plus the embedding
sidecar/supervisor.
travsr-mcp Depends on: core, error, analysis, retrieval, store,
plugin-host, config, rerank
The Model Context Protocol server (stdio + SSE). The only
external interface.
travsr-daemon Depends on: core, ipc, config, mcp, indexer, retrieval,
store, plugin-host, analysis
Long-running orchestrator: git hook, file watcher,
incremental reindex, Phase B scheduler, query cache.
travsr-cli Depends on: core, ipc, indexer, daemon, mcp, store,
retrieval, plugin-sdk, plugin-host, config
The travsr binary: init, connect, ask, graph, mcp, lang,
embed, rerank, synonym, config, serve, and more.
The edges above are the real ones read from each crate's Cargo.toml, not an
idealized summary. The "no cycles" rule still holds; the web is just richer than a
single spine (for example travsr-mcp uses store, analysis, and plugin-host
directly, not only retrieval).
Sidecar packages live under packages/: travsr-npm (the @travsr.com/travsr
binary wrapper published to npm), travsr-vscode (the VS Code extension),
travsr-lsif-ts (the built-in TypeScript/JavaScript LSIF emitter), and
travsr-lsif-py (the Python LSIF emitter).
Indexing pipeline
1. Tree-sitter (structural layer)
Tree-sitter parses every source file using language grammars into an AST without a compilation step. Travsr extracts:
- Import edges:
import X from Y/use crate::X/from X import Y - Definition nodes: functions, classes, structs, enums, traits, interfaces
- Call expression nodes: unresolved call sites (resolved by LSIF)
- Inheritance edges:
extends,implements,struct ... : Trait
Tree-sitter handles all languages at the structural level. LSIF provides deeper semantic information for supported compilers.
2. Semantic enrichment layer (Phase B)
Tree-sitter is Phase A. A second per-language pass, Phase B, resolves call targets, type references, and cross-module edges, then merges them into the same graph. Phase B is hosted by travsr-plugin-host: TypeScript, JavaScript, Rust, and Python run an in-process native analyzer, while the rest run an external LSIF/SCIP tool in a sandboxed subprocess installed via travsr lang install.
Native Phase B (in-process, runs automatically once its runtime is present):
| Language | Analyzer | Needs | Edges added |
|---|---|---|---|
| TypeScript / JavaScript | travsr-lsif-ts (LSIF, bundled in travsr-lib/) | Node.js | Resolved call targets, type references, DFG |
| Rust | rust-analyzer (LSIF) | Rust toolchain (cargo) | Resolved call targets, trait implementations |
| Python | travsr-lsif-py (LSIF, bundled in travsr-lib/) | Node.js | Resolved call targets, type inference |
These four languages have a native Phase B implementation compiled into the
daemon, so their analyzer output is ingested in-process rather than through a
sandboxed sidecar. They are not zero-install: the TypeScript/JavaScript and
Python emitters ship in the travsr-lib/ directory beside the binary and run
on Node.js, so without Node.js (or without travsr-lib/) those languages get
structural edges only. travsr lang list shows each language's prerequisites.
Rust's rust-analyzer is fetched by travsr lang install rust, which uses
rustup when it is present and otherwise downloads a pinned rust-analyzer
directly.
Installable, Standard sandbox (no network, no dependency downloads):
| Language | Underlying tool |
|---|---|
| Go | scip-go |
| Ruby | scip-ruby |
| PHP | scip-php |
| Swift | travsr-swift-index-emitter |
| Objective-C (macOS) | travsr-lang-objectivec |
Installable, Native IPC sandbox (no network, but needs POSIX message queues and
shared memory for the analyzer's parallel workers, so macOS applies resource
caps instead of sandbox-exec):
| Language | Underlying tool |
|---|---|
| C / C++ | scip-clang |
| Dart | travsr-dart-index-emitter |
Installable, Elevated sandbox (build tool fetches dependencies over an approved host allowlist):
| Language | Underlying tool |
|---|---|
| Java | scip-java |
| Kotlin | kotlin-language-server |
| C# | scip-dotnet |
| Scala | sbt |
Notes:
- Phase B is gated per language against
~/.travsr/lang.toml; a language present in the repo but not registered stays at the Tree-sitter structural graph. - If an external tool is absent from
PATH, the pass is skipped and Travsr falls back to the Phase A structural graph rather than failing the index. - Java and Scala cannot run inside the Windows isolation layer, because their build tools fork workers that fail in it. On Windows they are skipped unless you grant permission with
travsr lang allow-unsandboxed; on macOS and Linux they are unaffected.
Semantic edges go into the same graph as Tree-sitter edges. Nodes are deduplicated by VName.
3. Live semantic resolution (between commits)
Phase B is commit-gated on purpose: re-running full SCIP analysis on every keystroke is not viable, so between commits only Tree-sitter runs, and a cross-file reference is detected but not resolved to a specific symbol (user.save() is known to be a call, not which save). A live lane (RFC-027) closes that window without weakening the commit-gated guarantee, through a strict division of labour:
Tree-sitter -> detects a reference exists (live, cheap, always on)
SCIP graph -> owns node identity (Kythe VName) (durable ground truth)
LSP -> disambiguates a specific position (live, type-aware, optional)
Commit SCIP -> ratifies the region, heals drift (deterministic convergence)
Two resolution paths, both fail-closed:
- Unambiguous lexical resolution. A name with exactly one definition in the graph has only one thing it can mean, so resolving it is a lookup, not a guess, and needs no language server at all.
- LSP-assisted resolution. For an ambiguous name, the editor's own language server (clangd, kotlin-language-server, Intelephense, and so on) is asked what a specific position points at. Travsr maps both ends to existing graph nodes itself; the language server disambiguates a position, it never mints identity.
Anything ambiguous, unmappable, or cross-corpus abstains rather than guessing: a missing edge fails safe (falls back to the structural graph), a wrong edge would fail silent and dangerous, which for a "zero structural hallucinations" product is worse than a missed edge. Edges this lane emits carry provenance='live' and stay unratified until the next commit's Phase B run confirms or heals them, which is why get_architecture_brief and get_subsystem_brief exclude this overlay by default (provenance: 'ratified').
As of v1.3.0 the live lane covers TypeScript, JavaScript, Python, Rust, Go, Dart, Swift, C++, Java, C#, Kotlin, PHP, C, and Objective-C. Ruby and Scala are deliberately left out: ruby-lsp cannot resolve untyped receivers, and Scala's language server needs an sbt compile first. An edit in those two languages still waits for the next commit to re-resolve.
4. Kythe VNames: node identity
Every node is identified by a Kythe VName:
{
"corpus": "github.com/org/repo",
"root": "",
"path": "src/auth/jwt.ts",
"language": "typescript",
"signature": "#sign(string,Claims):string"
}
VName identity includes the corpus, root, path, language, and signature. Enum members are nodes too, with signatures of the form variant:Enum.Member, so a reference to Color.Red resolves to the member itself. It distinguishes matching names in different locations, but renaming or moving a symbol can change its identity. Global MCP queries operate on registered repositories and aggregate their results; they do not imply complete cross-repository call resolution.
Storage
SQLite + WAL
The graph is stored in .travsr/graph.db (SQLite). WAL mode enables concurrent
reads during reindex.
SQLite is the only backend. Kùzu was once planned as a separate production
engine and shipped for a while behind a --features kuzu flag that was never
built by default; it was removed entirely in July 2026, along with the
travsr migrate command and the one-way migration path that went with it.
SQLite + WAL has been sufficient for every target workload. RocksDB remains a
possible future backend for hyperscale, but nothing is built against it today,
and adopting it would mean designing a fresh migration path.
The v1 schema, which every later migration builds on:
CREATE TABLE nodes (
id INTEGER PRIMARY KEY,
corpus TEXT NOT NULL, -- the four VName fields below plus corpus
root TEXT NOT NULL, -- form the node's Kythe address
path TEXT NOT NULL,
language TEXT NOT NULL,
signature TEXT NOT NULL,
kind TEXT NOT NULL -- 'function' | 'class' | 'module' | ...
);
-- The VName is the real identity; the INTEGER id is a compact surrogate that
-- keeps the edge table narrow and its indexes cache-friendly.
CREATE UNIQUE INDEX idx_nodes_vname
ON nodes(corpus, root, path, language, signature);
CREATE TABLE edges (
src INTEGER NOT NULL,
dst INTEGER NOT NULL,
kind TEXT NOT NULL, -- 'calls' | 'imports' | 'inherits' | 'types' | ...
PRIMARY KEY (src, dst, kind)
);
CREATE INDEX idx_edges_src_kind ON edges(src, kind);
CREATE INDEX idx_edges_dst_kind ON edges(dst, kind);
CREATE TABLE files (
path TEXT PRIMARY KEY,
sha256 TEXT NOT NULL,
last_indexed_at INTEGER NOT NULL
);
Migrations run forward from there through a backend-agnostic MigrationRunner.
Later versions add edge provenance and confidence, per-language package
metadata, RBAC columns, an FTS5 index over identifiers with a synonym layer, a
vector table for embeddings, Phase B symbol unification, cached k-core shells,
node tombstones, and a split lexical index for signature and path terms.
travsr status and the get_index_status MCP tool report the schema version
the current graph is on.
Retrieval algorithms
BFS
Breadth-first search from a seed set of nodes to depth 3. Fast, simple, correct for direct neighbours. Used by get_dependencies, get_callers, and get_blast_radius.
Personalized PageRank (PPR)
PPR scores all nodes in the graph relative to a seed set. High-scored nodes are strongly connected to the seed via many short paths. Used by get_context to rank which parts of the graph are most relevant to a query.
Dijkstra + λ-corridor (execution paths)
Backs get_execution_path. A bounded local subgraph is built by bidirectional BFS from the source and sink, Dijkstra finds the lowest-cost path between them, and nodes within λ (0.5, ADR-007) of that optimal cost are added as a corridor of context. When no path exists it falls back to BFS depth 3. This is not Prize-Collecting Steiner Tree, despite the pcst module name and ADR-007's title (issue #527); real PCST is scoped for later and gated on a benchmark showing it beats this.
0-1 Knapsack (token budget)
After PPR ranks the candidates, the knapsack solver selects which nodes to include in the final MCP response given a token budget. Each node has a weight (token count) and a value (PPR score). The solver maximises total value subject to the budget constraint.
k-core decomposition
Assigns every node a shell number: the largest k for which the node survives in a subgraph where every node has at least k neighbours. High-shell nodes are the structural backbone of a codebase, which is what lets retrieval recover the "buried middle" that neither the entry points nor the leaves account for. Shells are computed once and cached in the graph rather than recomputed per query.
Component detection and layering
Backs get_architecture_brief and get_subsystem_brief. Components are one per package where the repository has them (a crate, an npm package) and the containing directory otherwise, language-agnostic. Cross-component dependency edges are condensed into strongly connected components (Tarjan), then each condensed component is assigned a layer equal to the longest path to a sink over that condensation, which is what lets the brief describe foundation-to-entry-point layering and flag true dependency cycles rather than just listing edges. get_subsystem_brief walks the call graph from one entry point instead, by depth, and reports every call that crosses a component boundary. Both tools default to provenance='ratified', so an unconfirmed live-lane edge can never invent a dependency or a call that Phase B has not actually confirmed.
BM25 lexical ranking
Ranks symbols lexically against the query text. It tokenises through the same identifier tokeniser the FTS index uses, so camelCase and snake_case split identically on both sides and a query written either way still matches.
Cross-encoder reranking
An optional last pass. Where the algorithms above score structure and lexical
overlap, the cross-encoder in travsr-rerank scores (query, candidate) pairs
directly and reorders the shortlist, reporting a confidence rather than
guessing. It is a relevance arbiter over candidates the graph already produced,
never a source of candidates itself, so it cannot invent a node or an edge.
Install it with travsr rerank install.
RBAC filtering
Corpus-scoped access control is applied during traversal, not as a filter over the results. Post-filtering would leak the existence of restricted nodes through response timing, so a traversal that is not permitted to see a node never expands it in the first place.
MCP transports
stdio (local)
The default transport. The MCP server reads JSON-RPC from stdin and writes to stdout. Claude Desktop spawns travsr mcp --stdio as a subprocess. A single-repo session (travsr mcp) exposes 28 tools; a global session (travsr mcp --global) exposes 17.
SSE (self-hosted)
travsr serve provides an SSE/HTTP MCP server for remote clients. It serves seven read-only graph tools (get_dependencies, get_callers, get_blast_radius, get_lang_status, search_symbol, get_repo_map, get_execution_path) and has no tools/list. See the serve reference for configuration. This server capability is separate from availability of a managed cloud service.
Incremental reindex
The running daemon watches saved files. Git hooks also reconcile changes after commits, merges, and checkouts through travsr hook-run --from-hook. For a commit, the delta indexer:
- Reads the diff between
HEADandHEAD~1 - Computes the SHA-256 of each changed file's contents and compares it with the hash recorded in the
filestable, so a file the diff lists but whose bytes are unchanged is skipped - Re-parses only the files that actually changed
- Writes only changed nodes and edges to the graph
- Updates the edge index
Because only the changed files are re-parsed, an incremental reindex touches a small fraction of the graph rather than rebuilding it.