How It Works

When you run unfault review or use the VS Code extension, a few things happen under the hood. Understanding this helps explain why Unfault behaves the way it does, and why your source code never leaves your machine.

The Short Version

1. Your code stays local. Unfault parses your code on your machine and builds a semantic graph of how things connect.
2. Only structure goes to the API. The graph (functions, calls, imports, routes) gets sent to the Unfault API. No source code, no string literals, no comments.
3. The API analyzes the graph. Patterns are evaluated against your code’s structure and findings are returned.
4. You see the results. Findings appear in your terminal, editor, or CI output.

Why Client-Side Parsing?

Most analysis tools send your source code to a server. We don’t.

Unfault parses your code locally using Tree-sitter, a fast incremental parser. The CLI and VS Code extension extract semantic information: which functions exist, what they call, what they import, how routes are wired up.

This matters for a few reasons:

• Privacy. Your actual code never leaves your machine. The API only sees the graph structure.
• Speed. Parsing happens in parallel on your hardware.
• Consistency. The same parsing runs in your editor and in CI.

What Gets Extracted

When Unfault parses your code, it builds a graph with nodes and edges:

Nodes represent things in your code:

• Files
• Functions and methods
• Classes
• Imports (both internal and external)
• Framework constructs (routes, middleware, handlers)

Edges represent relationships:

• Contains (file contains function)
• Calls (function A calls function B)
• Imports (file imports module)
• Inherits (class extends another)
• Framework wiring (app registers route, route uses middleware)

This graph captures the structure of your code without the content. The API can reason about “function fetch_user calls requests.get with no timeout” without ever seeing the actual HTTP URL or request body.

The Analysis Flow

Here’s what happens when you run a review:

1. Workspace Detection

Unfault scans your project to understand what it’s looking at:

• Which languages are present (Python, Go, Rust, TypeScript)
• Which frameworks are in use (FastAPI, Express, Gin, Axum)
• Project structure and entry points

2. Parsing and Semantic Extraction

For each source file, Unfault:

• Parses the syntax tree
• Extracts semantic information (functions, classes, calls, imports)
• Detects framework-specific patterns (route decorators, middleware registration)
• Builds the local portion of the code graph

3. Graph Construction

Individual file semantics get merged into a unified graph. This is where Unfault resolves:

• Which function calls go where
• How imports connect files
• Framework topology (which routes exist, what middleware applies)

4. API Analysis

The graph gets serialized and sent to the Unfault API. The API analyzes the structure and produces facts: observations about your code.

The most common fact type is a finding: a pattern detected by a rule. Each finding includes what was detected, where it occurs, why it matters, and a suggested fix when possible.

Other fact types (like SLO state) capture different observations about your codebase.

5. Results

Facts flow back to your CLI or editor, formatted for your chosen output mode.

Graph Persistence

When you run a review, the API can persist your code graph. This enables features like:

• Impact analysis: “What else might break if I change this function?”
• Dependency queries: “What external services does this route depend on?”
• Historical comparison: “What changed since the last review?”

The persisted graph contains only structure, never source code. You can delete it anytime.

What the API Sees

To be concrete about privacy, here’s an example. If you have this code:

def fetch_user(user_id: str) -> dict:
    response = requests.get(f"https://api.example.com/users/{user_id}")
    return response.json()

The API sees something like:

{
  "functions": [{
    "name": "fetch_user",
    "file": "users.py",
    "calls": [{"target": "requests.get", "has_timeout": false}]
  }]
}

No URL. No variable names beyond what’s needed for the graph. No string literals. Just enough structure to identify patterns.

Next Steps

Facts

The observations Unfault produces about your code. Read more

Cognitive Context

Why this architecture enables better insights. Read more

Dimensions

How facts are categorized. Read more

Quick Start

Run your first review. Get started