System Maps

A compact, structured index of your entire system that AI agents and tooling can consume instantly.

What Is a System Map?

A system map is a lightweight JSON document that summarizes every module, capability, entity, and unresolved reference in your SysMARA project. It is generated alongside the full system graph but serves a different purpose: while the system graph captures every edge and relationship for validation and diagnostics, the system map provides a flat, scannable index optimized for quick lookups.

Think of it this way: the system graph is the full blueprint of your building, while the system map is the directory in the lobby that tells you which offices are on which floor.

System Map vs. System Graph

SystemMap Structure

The SystemMap JSON document has four top-level fields:

• version — The schema version of the system map format.
• generatedAt — ISO 8601 timestamp of when the map was generated.
• modules — An array of all module names discovered in your specs.
• capabilities — An array of all capability names.
• entities — An array of all entity names.
• unresolved — An array of references that could not be resolved during graph construction. These indicate specs that reference entities, capabilities, or modules that do not exist.

Generating the System Map

The system map is generated as part of the sysmara graph command. This command parses all your spec files, builds the full system graph, and then produces both system-graph.json and system-map.json in your configured generated directory.

npx sysmara graph

You can also generate it as part of the full build pipeline:

npx sysmara build

The build command runs the full pipeline: validate, graph, compile, and diagnose. The system map is produced during the graph phase.

Both commands support the --json flag for machine-readable output:

npx sysmara graph --json

Example Output

Here is an example system-map.json for a billing service with two modules:

{
  "version": "1.0",
  "generatedAt": "2026-03-14T10:30:00.000Z",
  "modules": [
    "billing",
    "customers"
  ],
  "capabilities": [
    "CreateSubscription",
    "CancelSubscription",
    "ChargeInvoice",
    "RegisterCustomer",
    "UpdateCustomerProfile"
  ],
  "entities": [
    "Subscription",
    "Invoice",
    "Customer",
    "PaymentMethod"
  ],
  "unresolved": []
}

If an entity or capability references something that does not exist, it appears in the unresolved array:

{
  "version": "1.0",
  "generatedAt": "2026-03-14T10:30:00.000Z",
  "modules": ["billing"],
  "capabilities": ["CreateSubscription"],
  "entities": ["Subscription"],
  "unresolved": ["entity:Plan"]
}

How AI Agents Use the System Map

When an AI agent needs to work with your codebase, it first reads the system map to understand what exists. This is far more efficient than scanning the file system or parsing YAML files directly. The system map answers questions like:

• What entities exist in this system?
• What capabilities are available?
• Which modules organize this domain?
• Are there any broken references I should know about?

With this information, an agent can then request specific spec files for deeper context, or use the full system graph for relationship traversal. The system map serves as the entry point — the first thing an agent reads to orient itself.

Keeping the Map Current

The system map is a generated artifact. Do not edit it manually. Re-run sysmara graph or sysmara build whenever you change spec files. In a CI/CD pipeline, include the graph step to ensure the map stays in sync:

# In your CI pipeline
npx sysmara validate
npx sysmara graph
# Optionally commit the generated files or use them in subsequent steps

If your unresolved array is non-empty, treat that as a warning. It means your specs reference things that do not exist yet, and AI agents or tooling may produce incomplete or incorrect results.