AI System Graph

A typed, traversable representation of every architectural relationship in your system

What is the AI System Graph?

The AI System Graph is a formal directed graph that encodes your entire system architecture as typed nodes and edges. Every entity, capability, module, policy, invariant, flow, route, and file in your SysMARA project becomes a node. Every relationship between them — ownership, dependency, enforcement, governance — becomes a typed edge.

Unlike documentation or diagrams, the graph is machine-readable. AI agents can traverse it to answer questions like "what breaks if I rename the user entity?" or "which policies govern the create_subscription capability?" without parsing natural language or guessing at project structure.

Node Types

Every node has an id, a type, a name, and a metadata object. The id follows the format {type}:{name}.

Edge Types

Edges encode the semantic relationships between nodes. Each edge has a source, target, type, and optional metadata.

How the Graph is Built

The graph is constructed by the buildSystemGraph() function. It takes your parsed SystemSpecs (all YAML specs combined) and an optional array of RouteSpec objects, then produces a deterministic SystemGraph with sorted nodes and edges.

The build process follows these steps:

1. Create a node for every entity, capability, module, policy, invariant, flow, and route in your specs.
2. Create edges by walking the relationships: module membership, entity references, policy bindings, invariant enforcement, dependency declarations, flow triggers, route exposures, and flow steps.
3. Sort all nodes and edges lexicographically by ID for deterministic output. Two identical specs always produce an identical graph.

Example Graph Output

Here is a partial JSON output from a SaaS billing system graph. Notice how the graph captures that create_subscription uses the subscription entity, is governed by billing_admin_manage_subscriptions, is protected by the no_duplicate_active_subscription invariant, and triggers the workspace_onboarding flow indirectly through its module relationships.

{
  "version": "0.1.0",
  "generatedAt": "2025-03-14T12:00:00.000Z",
  "nodes": [
    {
      "id": "capability:create_subscription",
      "type": "capability",
      "name": "create_subscription",
      "metadata": { "module": "billing" }
    },
    {
      "id": "entity:subscription",
      "type": "entity",
      "name": "subscription",
      "metadata": {}
    },
    {
      "id": "invariant:no_duplicate_active_subscription",
      "type": "invariant",
      "name": "no_duplicate_active_subscription",
      "metadata": { "entity": "subscription" }
    },
    {
      "id": "module:billing",
      "type": "module",
      "name": "billing",
      "metadata": {}
    },
    {
      "id": "policy:billing_admin_manage_subscriptions",
      "type": "policy",
      "name": "billing_admin_manage_subscriptions",
      "metadata": {}
    }
  ],
  "edges": [
    {
      "source": "capability:create_subscription",
      "target": "entity:subscription",
      "type": "uses_entity"
    },
    {
      "source": "capability:create_subscription",
      "target": "policy:billing_admin_manage_subscriptions",
      "type": "governed_by"
    },
    {
      "source": "entity:subscription",
      "target": "module:billing",
      "type": "belongs_to"
    },
    {
      "source": "invariant:no_duplicate_active_subscription",
      "target": "capability:create_subscription",
      "type": "protects"
    },
    {
      "source": "invariant:no_duplicate_active_subscription",
      "target": "entity:subscription",
      "type": "enforces"
    }
  ]
}

Why the Graph Matters for AI Agents

Traditional codebases force AI agents to grep through files, parse imports, and guess at relationships. The AI System Graph eliminates guessing by providing a single, traversable data structure that answers architectural questions directly.

Traversal

An AI agent can walk edges to discover all capabilities that use a given entity, all policies that govern a capability, or all flows triggered by a capability. This makes context gathering deterministic rather than heuristic.

Impact Analysis

Before modifying any spec, an agent can traverse the graph to compute the full impact surface: which modules, invariants, policies, capabilities, routes, flows, tests, and generated artifacts are affected. This drives the Change Protocol's risk classification.

Dependency Understanding

Module dependency edges let agents verify that a proposed change respects module boundaries. If a capability in the billing module needs to reference a user entity from the users module, the agent can check whether users is in billing's allowedDependencies before making the change.

Generating the Graph

Run the following CLI command to generate the graph from your YAML specs:

sysmara graph

This parses all spec files from your configured specDir, builds the graph with buildSystemGraph(), and outputs the JSON. You can pipe it to a file or pass it to downstream tools for visualization or analysis.

AI-Safe Change Workflows

The graph is the foundation of SysMARA's AI-safe change workflows. When an AI agent proposes a change through the Change Protocol, the graph is used to compute impact surfaces, classify risk, identify human review flags, and determine which generated artifacts need to be refreshed. Without the graph, the agent would have no reliable way to assess whether a change is safe to apply automatically or requires human approval.