Software Graph

What is the Software Graph

The Software Graph is a typed, directed property graph that represents a codebase as stable software concepts and their relationships. Unlike AST dumps or raw file listings, it models packages, modules, classes, services, routes, controllers, configuration, and infrastructure as first-class nodes with typed edges between them.

Nodes

Nodes represent stable software concepts. Each node has a deterministic ID (prefixed by type), a name, a source file, a package, an optional span, and metadata. The graph supports 42 node types across six categories.

• Structure — Workspace, Application, Package, Module, Namespace
• Code — Function, Method, Class, Interface, TypeAlias, Enum, Decorator
• Dependencies — Dependency, Import, Export, Script
• Infrastructure — Task, Pipeline, BuildTarget, Configuration, Container, Workflow, Job, Step, Framework
• Architecture — Route, Resource, Operation, Model, Field, Middleware, Provider, Factory, Service, Repository, Controller, Guard
• Runtime — DatabaseTable, EnvironmentVariable, Event, Permission, Exception

Relationships

Directed edges explain how concepts are connected. Every edge has a type, source and target node IDs, a provenance, and deterministic confidence derived from structural evidence. The graph supports 32 relationship types.

• Call graph — CALLS, RETURNS, THROWS, CREATES
• Module system — IMPORTS, EXPORTS, CONTAINS, EXPOSES
• Type system — IMPLEMENTS, EXTENDS, DECORATES
• Dependency — DEPENDS_ON, USES, READS, WRITES, REFERENCES
• Architecture — INJECTS, REGISTERED_IN, REGISTERS, DECLARES, MOUNTS, PROVIDES, CONSUMES
• Configuration — CONFIGURES, EXECUTES, GENERATES, HANDLES, OVERRIDES, AUTHORIZES
• Events — PUBLISHES, SUBSCRIBES, BELONGS_TO

Immutability

The core graph (nodes + relationships) is immutable after a build. All derived artifacts — semantics, evidence, reports, communities — consume the immutable graph and never rewrite core facts. This separation ensures every query runs against a stable snapshot.

Content hash

Every graph build produces a deterministic FNV-1a content hash computed from sorted node and edge IDs. Same source, same config, same version — same hash. Use it as a regression signal in CI pipelines.