AxonAtlas Architecture & Intelligence

What is AxonAtlas

AxonAtlas is a semantic code intelligence engine that transforms raw source code repositories into a queryable, semantically-rich knowledge graph. It goes far beyond surface-level linting or traditional static analysis — AxonAtlas constructs a deep structural and semantic model of an entire codebase, resolving function calls, propagating types, detecting architectural communities, mapping execution flows, and identifying dead code — all within a unified graph that AI agents and developers can query in real time.

Think of AxonAtlas as a Software Knowledge Engine: an always-on intelligence substrate that understands not just what code exists, but how it connects, why it changes together, and where risk concentrates. Traditional tools show you a list of warnings. AxonAtlas shows you the living architecture of your system.

Supported Languages & Frameworks

AxonAtlas provides first-class support for Python and TypeScript/JavaScript, with framework-aware entry point detection that understands the conventions of modern web and CLI frameworks:

Why Code Intelligence Matters

Static Analysis vs. Code Intelligence

The distinction between traditional static analysis and a code intelligence platform is fundamental. Static analysis operates on individual files or narrow scopes. Code intelligence operates on the entire system as a connected graph.

The Developer Productivity Crisis

System Architecture Overview

AxonAtlas is organized into four clearly separated layers, each with distinct responsibilities. This layered architecture ensures that the intelligence pipeline, the storage engine, and the protocol interface can evolve independently without breaking contracts between them.

At the highest level, the MCP Protocol Layer handles all external communication — exposing 17 tools and 3 resources over both stdio and Streamable HTTP transports. Below it, the Intelligence Services layer provides the reasoning engine: query planning, impact analysis, narrative explanations, and risk scoring. The Semantic Core manages symbol indexes, type intelligence, and workspace-level coordination. And at the foundation, the Ingestion Pipeline and Storage Layer convert raw source code into a persistent, queryable knowledge graph.

┌──────────────────────────────────────────────────────────────┐
│                     MCP Protocol Layer                        │
│  ┌──────────┐  ┌────────────┐  ┌────────┐  ┌──────────────┐ │
│  │ 17 Tools │  │ 3 Resources│  │Security│  │ HTTP + stdio │ │
│  └────┬─────┘  └─────┬──────┘  └───┬────┘  └──────┬───────┘ │
└───────┼──────────────┼─────────────┼───────────────┼─────────┘
        │              │             │               │
┌───────┼──────────────┼─────────────┼───────────────┼─────────┐
│       ▼              ▼             ▼               ▼         │
│                Intelligence Services                         │
│  ┌───────────┐  ┌────────┐  ┌─────────┐  ┌─────────────┐    │
│  │ Query     │  │ Impact │  │ Explain │  │ Review Risk │    │
│  │ Planning  │  │Analysis│  │Narrative│  │  Scoring    │    │
│  └─────┬─────┘  └───┬────┘  └────┬────┘  └──────┬──────┘    │
└────────┼────────────┼────────────┼───────────────┼───────────┘
         │            │            │               │
┌────────┼────────────┼────────────┼───────────────┼───────────┐
│        ▼            ▼            ▼               ▼           │
│                  Semantic Core                               │
│  ┌────────────┐  ┌──────────┐  ┌────────────┐               │
│  │ Symbol     │  │ Type     │  │ Workspace  │               │
│  │ Index      │  │ Intel    │  │ Manager    │               │
│  └─────┬──────┘  └────┬─────┘  └─────┬──────┘               │
└────────┼──────────────┼──────────────┼───────────────────────┘
         │              │              │
┌────────┼──────────────┼──────────────┼───────────────────────┐
│        ▼              ▼              ▼                       │
│             Ingestion Pipeline (14 Phases)                   │
│  ┌────────┐ ┌──────┐ ┌───────┐ ┌────────┐ ┌──────────────┐  │
│  │Structure│→│Parse │→│Import │→│TypeFlow│→│  Resolution  │  │
│  └────────┘ └──────┘ └───────┘ └────────┘ └──────┬───────┘  │
│  ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌────────┴──┐       │
│  │Community │ │ Coupling │ │Process  │ │ Dead Code │       │
│  └──────────┘ └──────────┘ └─────────┘ └───────────┘       │
└──────────────────────────────────────────────────────────────┘
         │
┌────────┼─────────────────────────────────────────────────────┐
│        ▼          Storage Layer                              │
│  ┌────────────────┐  ┌─────────────┐  ┌──────────────────┐  │
│  │  KuzuDB Graph  │  │ Connection  │  │  Repo Router     │  │
│  │  Cypher Engine  │  │ Pool + R/W  │  │  (LRU Pool)     │  │
│  └────────────────┘  └─────────────┘  └──────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Core Module Map

The system comprises 16 core modules, each with a single, well-defined responsibility. This modularity ensures that individual components can be tested, optimized, and replaced without cascading changes across the system.

The Intelligence Pipeline

At the heart of AxonAtlas is a deterministic, multi-phase directed acyclic graph (DAG)with 14 declared phases. This is not a simple sequential script — it is a formally validated pipeline where each phase declares its dependencies, and the execution order is verified at startup using Kahn's algorithm for cycle detection.

This design ensures that phase ordering bugs are caught before any analysis runs. Phases within the same parallel group are verified to have no transitive dependencies among themselves, enabling safe concurrent execution. Optional phases — such as coupling analysis, duplicate detection, and embedding generation — can be skipped without breaking downstream phases, providing graceful degradation when certain data sources (like git history) are unavailable.

                    structure
                       │
                    parsing
                       │
                    imports
                       │
                   type_flow
                   ╱   │   ╲
              calls heritage types    ← parallel_group: "resolution"
                   ╲   │   ╱
                   contracts
                 ╱  │  │  ╲  ╲
        communities │  │  coupling  duplicates  ← parallel_group: "semantic"
                processes │
                   dead_code
                        │
                    embeddings

Phase-by-Phase Breakdown

Each phase builds on the outputs of its predecessors. The early phases establish the structural foundation — file nodes, parsed symbols, import relationships. The middle phases add semantic depth — type propagation, call resolution, class hierarchies. The later phases perform higher-order analysis — community clustering, process flow detection, dead code identification. Finally, the embedding phase generates vector representations for semantic search.

Pipeline Guarantees

The Software Knowledge Graph

The AxonAtlas knowledge graph is a labeled property graph with a precisely defined schema of 11 node types and 17 relationship types. Every entity in the codebase — from a single variable to an entire architectural community — is represented as a typed node with properties. Every connection between entities — a function call, an import, a type reference, a temporal coupling — is represented as a typed, directed edge.

This graph is not an afterthought bolted onto existing analysis. It is the analysis. Every intelligence capability AxonAtlas provides — from impact analysis to community detection to dead code identification — is implemented as a graph traversal or graph algorithm over this unified model.

Node Types

The graph schema distinguishes between structural nodes (representing physical entities in the codebase) and synthetic nodes (representing discovered patterns or computed groupings). Structural nodes are created during the parsing phase. Synthetic nodes emerge from later analysis phases.

Relationship Types

Relationships carry the semantic intelligence. Each edge type models a specific kind of connection with distinct semantics. Some relationships are directional (a function calls another function); others are symmetric (two files are coupledin git history). The diversity of edge types is what makes AxonAtlas queries so expressive — you can ask “who calls this function?” as easily as “which files are temporally coupled with this one?”

Deterministic Identity — The Moniker System

Every node in the AxonAtlas graph receives a deterministic, content-addressable ID called a moniker. Monikers are stable across re-indexes, portable across machines, and globally unique within a workspace. This is the foundational invariant that makes incremental indexing, cross-repository resolution, and graph fingerprinting possible.

# Symbol moniker — encodes label, language, repo, module, and name
function:python:local:src/auth/service:validate_token
class:typescript:local:src/components/App:Dashboard

# Structural moniker — stable file identity
axon://file/src/auth/service.py

KuzuDB — The Storage Engine

Semantic Intelligence Engine

Semantic intelligence is the capability that separates AxonAtlas from every other code analysis tool on the market. Where traditional tools stop at syntactic parsing — extracting function names and detecting import statements — AxonAtlas reconstructs the actual runtime behavior of the code through multi-tier reasoning about calls, types, and dependencies.

This is the layer that transforms a raw syntax tree into a semantic graph — where every function knows its callers and callees, every variable knows its type, and every class knows its place in the inheritance hierarchy. Without semantic intelligence, you would have a directory listing. With it, you have a navigable map of the entire system.

Multi-Tier Call Resolution

Call resolution is the most critical semantic operation in AxonAtlas. When the parser encounters a call expression like service.validate_token(), the resolver must determine which function is actually being invoked. Unlike a compiler, AxonAtlas operates without a symbol table — it must reconstruct call targets from incomplete information, context clues, and heuristic reasoning.

The resolver uses a hierarchical cascade with four tiers, each progressively broader in scope but lower in confidence. This design ensures that the highest-confidence resolution is always preferred, while still providing useful connections even when exact resolution is impossible.

  ┌─────────────────────────────────────────────────────┐
  │  Tier 1: Local Scope Match      (confidence: 1.0)  │
  │  ─── Look for the symbol in the same file           │
  │  ─── Direct name match in local definitions         │
  └──────────────────────┬──────────────────────────────┘
            miss ↓
  ┌──────────────────────┴──────────────────────────────┐
  │  Tier 2: Import Resolution       (confidence: 0.9)  │
  │  ─── Follow import chain to target module           │
  │  ─── Resolve aliased imports (from X import Y as Z) │
  └──────────────────────┬──────────────────────────────┘
            miss ↓
  ┌──────────────────────┴──────────────────────────────┐
  │  Tier 3: Receiver-Method Binding (confidence: 0.7)  │
  │  ─── Trace variable type → class → method lookup    │
  │  ─── Uses type flow results for receiver typing     │
  └──────────────────────┬──────────────────────────────┘
            miss ↓
  ┌──────────────────────┴──────────────────────────────┐
  │  Tier 4: Global Fuzzy Match      (confidence: 0.5)  │
  │  ─── Search all known symbols for best-match name   │
  │  ─── Weighted by scope proximity and name distance  │
  └─────────────────────────────────────────────────────┘

Each resolved call edge carries its confidence score as a property. This is critical for downstream consumers — an AI agent querying callers can distinguish between high-confidence direct calls and lower-confidence fuzzy matches, adjusting its behavior accordingly. Impact analysis uses these scores to weight blast-radius calculations, ensuring that uncertain connections do not produce false alarms.

Worklist-Based Type Propagation

Many symbols in dynamic languages like Python lack explicit type annotations. AxonAtlas addresses this through a worklist-based type propagation algorithm modeled after compiler dataflow analysis. The algorithm constructs a Type Flow Graph (TFG) — a directed graph where nodes represent type-bearing positions (variables, parameters, return values) and edges represent type-flow relationships (assignments, function returns, parameter passing).

The worklist iterates until a fixed point is reached — when no more types can be propagated without violating the monotonicity constraint. This convergence guarantee means the algorithm always terminates and produces the maximally precise result given the available information. The propagated types are then used as input to the call resolution engine, significantly improving receiver-method binding accuracy.

Compiler-Grade Type Intelligence

For codebases that use TypeScript or typed Python, AxonAtlas can optionally invoke external type-checking engines — Pyright for Python and the TypeScript Compiler (tsc) for JavaScript/TypeScript. These engines provide ground-truth type information that supplements the heuristic type flow system.

Advanced Analysis Capabilities

Beyond core call resolution and type inference, AxonAtlas provides four categories of higher-order analysis that transform the knowledge graph from a dependency map into a strategic intelligence layer for engineering decision-making.

  Entry Points (detected)    Known Alive
  ──────────────────────    ────────────
  ├─ main()                 ├─ Decorated functions
  ├─ @app.route(...)        ├─ __init__ methods
  ├─ @click.command(...)    ├─ Protocol implementations
  ├─ test_*()               ├─ __all__ exports
  ├─ layouts / pages        └─ Event handlers
  │
  └─→  BFS Reachability through CALLS edges
       │
       ├─ Reachable symbols → marked alive
       └─ Unreachable symbols → flagged is_dead=true
          │
          └─→ False-positive filter applied
              │
              └─→ Final dead code set returned

Multi-Repository Intelligence

Real-world software systems are rarely contained within a single repository. A typical engineering organization operates with a frontend application, a backend API, shared libraries, infrastructure-as-code, and potentially dozens of microservices — each in its own repository with its own dependency graph and release cycle.

AxonAtlas is architected from the ground up for multi-repository, workspace-level intelligence. The WorkspaceManager coordinates multiple repository indexes, the RepositoryRouter manages per-repo database connections, and the GlobalSymbolIndex provides a unified view across all indexed repositories — enabling queries that span repository boundaries.

  ┌──────────────────────────────────────────────────────────┐
  │                    Workspace Manager                      │
  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐  │
  │  │ Repo        │  │ Topological│  │ Global Symbol      │  │
  │  │ Registry    │  │ Sort Order │  │ Index (cross-repo) │  │
  │  └──────┬─────┘  └──────┬─────┘  └─────────┬──────────┘  │
  └─────────┼───────────────┼───────────────────┼─────────────┘
            │               │                   │
  ┌─────────┼───────────────┼───────────────────┼─────────────┐
  │         ▼               ▼                   ▼             │
  │                 Repository Router                         │
  │  ┌─────────────────────────────────────────────────────┐  │
  │  │  LRU Connection Pool (bounded, per-repo backends)   │  │
  │  └──────┬────────────┬────────────┬────────────────────┘  │
  │         │            │            │                       │
  │    ┌────▼────┐  ┌────▼────┐  ┌────▼────┐                  │
  │    │ Repo A  │  │ Repo B  │  │ Repo C  │  ← KuzuDB each  │
  │    │(backend)│  │(backend)│  │(backend)│                  │
  │    └─────────┘  └─────────┘  └─────────┘                  │
  └───────────────────────────────────────────────────────────┘

The Global Symbol Index

The GlobalSymbolIndex aggregates per-repository symbol indexes into a unified lookup layer. When a query references a symbol by name, the index searches across all registered repositories and returns candidates ranked by relevance. This enables cross-repository operations that would be impossible with single-repo tools.

Consider a common scenario: your frontend application imports types from a shared library, and your backend API consumes the same library. With AxonAtlas, you can ask: “Who consumes the User type across all repositories?” — and the GlobalSymbolIndex will return callers from both the frontend and backend, even though they live in separate repos with separate databases.

Repository Router & Connection Pooling

Each repository gets its own isolated KuzuDB database file, ensuring clean separation of data. The RepositoryRouter manages an LRU-bounded connection pool that keeps frequently accessed repositories warm while automatically evicting stale connections. This design scales efficiently from a single-repo developer setup to a workspace with dozens of indexed repositories.

The router also handles path normalization — resolving symlinks, canonicalizing case-insensitive paths on Windows, and mapping relative paths to absolute repository roots. This seemingly mundane responsibility is critical for ensuring that the same repository is never indexed twice under different path representations.

Cross-Repository Impact Analysis

When the WorkspaceManager detects CROSS_REPO_REFERENCES edges, impact analysis automatically spans repository boundaries. Modifying a utility function in a shared library triggers blast-radius calculation that includes consumers in every repository that depends on it. The topological sort order ensures that upstream repositories are always indexed before their downstream dependents, maintaining consistency across the entire workspace.

MCP Protocol & Agent Integration

AxonAtlas is a native Model Context Protocol (MCP) server — the emerging open standard for connecting AI agents to external tools and data sources. This means any MCP-compatible AI system — Claude, GPT, Cursor, Windsurf, or custom agents — can query the AxonAtlas knowledge graph in real time, receiving structured, typed responses that are immediately actionable.

The MCP integration is not a bolt-on API wrapper. The server is built directly into the AxonAtlas runtime, sharing the same graph instances, symbol indexes, and intelligence services as the core pipeline. This eliminates serialization overhead and ensures that agent queries operate on the most current graph state. The server supports both stdio transport (for local IDE integrations) and Streamable HTTP (for remote and team-level deployments)(Soon).

Tool Catalog — 17 Intelligence Tools

Every tool is designed with agent ergonomics in mind. Inputs accept natural identifiers (symbol names, file paths) rather than internal IDs. Outputs are structured with consistent schemas that agents can parse without ambiguity. Error responses include remediation guidance, helping agents self-correct.

Resource Endpoints

In addition to tools, AxonAtlas exposes three MCP resource endpoints that provide contextual data to agents during conversation initialization:

Security Architecture

The MCP server implements a multi-layer security architecture designed for team deployments where repository access must be controlled per-user and per-agent. Authentication is backed by a validated secret, providing JWT-based secret validation with per-repository access control lists (ACLs).

Scalability & Performance Architecture

AxonAtlas is designed to scale from a single developer working on a personal project to an engineering organization with dozens of repositories containing millions of lines of code. Every layer of the system is engineered for predictable performance at scale.

The scalability architecture addresses three distinct dimensions: storage scalability (how the graph grows), query scalability (how fast intelligence is served), and operational scalability (how the system recovers and self-heals).

Concurrency & Thread Safety

The storage layer implements a read-many / write-exclusive lock (ReadWriteLock) that allows unlimited concurrent read queries while serializing write operations. This is the optimal concurrency model for a read-heavy workload — which is exactly the usage pattern for a code intelligence system, where graph mutations happen during indexing (infrequent) and queries happen continuously (frequent).

Incremental Intelligence

Full re-indexing is expensive. For a large repository with thousands of files, a complete pipeline run can take minutes. AxonAtlas solves this with a dependency-aware incremental engine that re-analyzes only the files affected by a change — and their transitive importers.

When a file changes, the incremental engine identifies which symbols are impacted, traces the IMPORTS graph to find all transitive importers, schedules them for re-parsing, and runs only the affected pipeline phases. This cascade strategy ensures that downstream consumers of a modified symbol always receive updated information, while files unrelated to the change are left untouched.

Graph Integrity & Self-Healing

The axon_graph_integrity tool provides a comprehensive structural health check that verifies graph invariants, ingestion consistency, and trust metrics. This is the equivalent of a database CHECKDB — it ensures that the knowledge graph is internally consistent and trustworthy.

Real-World Use Cases

AxonAtlas is designed to serve multiple personas across an engineering organization. Each use case leverages the same underlying knowledge graph — the intelligence is universal, but the value is specific to each role.

Strategic Positioning

AxonAtlas occupies a unique position in the developer tooling ecosystem. It is not a linter. It is not a code search engine. It is not a project management tool. AxonAtlas is a Code Intelligence Platform — a category that is emerging as the critical infrastructure layer for AI-assisted software development.

The platforms that will define the next decade of engineering productivity are those that serve as the intelligence backbone for both human engineers and AI agents. AxonAtlas is built to be that backbone — a continuously updated, semantically rich model of your entire software system that every tool, every agent, and every engineer can query.

Competitive Differentiation

The following comparison maps AxonAtlas against adjacent tool categories. AxonAtlas is not a replacement for any single tool — it is the intelligence layer that makes all other tools more effective.

The Intelligence Stack

AxonAtlas fits into the modern developer toolchain as the intelligence layer between source code and the tools that operate on it. Consider the following layered view: