Product Graph

The Product Graph is the compiler's canonical output - a deterministic JSON structure containing all product nodes, module nodes, typed edges (40+ kinds), and build metadata. It serves as the single source of truth that AI agents, generators, and planners consume.

Format Envelope

product-graph.json

{
  "format": "prodara-product-graph",
  "version": "0.1.0",
  "product": { "name": "task_board", "title": "TaskBoard", "version": "1.0" },
  "modules": [ ... ],
  "edges": [ ... ],
  "metadata": {
    "compiled_at": "2026-03-19T12:00:00Z",
    "compiler_version": "0.1.0",
    "source_files": [
      { "path": "app.prd", "hash": "sha256:a1b2c3..." }
    ]
  }
}

Full Example

Here's a simplified Product Graph for a task board application:

{
  "modules": [
    {
      "id": "board",
      "declarations": [
        {
          "id": "board.entity.task",
          "kind": "entity",
          "name": "task",
          "fields": [
            { "name": "task_id", "type": "uuid" },
            { "name": "title", "type": "string" },
            { "name": "status", "type": { "ref": "board.enum.task_status" }, "default": "todo" }
          ]
        },
        {
          "id": "board.enum.task_status",
          "kind": "enum",
          "name": "task_status",
          "members": ["todo", "in_progress", "done"]
        }
      ]
    }
  ],
  "edges": [
    { "from": "board", "to": "board.entity.task", "kind": "contains" },
    { "from": "board.entity.task", "to": "board.enum.task_status", "kind": "field_type" },
    { "from": "board.workflow.create_task", "to": "board.entity.task", "kind": "writes" }
  ]
}

Node IDs

All nodes use stable semantic IDs following the pattern <module>.<kind>.<name>. These IDs are deterministic and serve as cross-compilation references:

board.entity.task - An entity named "task" in the "board" module
board.workflow.create_task - A workflow in the "board" module
board.surface.board_view - A surface in the "board" module
billing.enum.invoice_status - An enum in the "billing" module

Edge Categories

Edges represent relationships between nodes. With 40+ edge kinds organized into 8 categories, the graph captures the full semantic structure of your product:

Structure

Module membership, entity nesting, field ownership.

contains, imports

Type

Field type references, generic parameters, enum values.

field_type, input_type, return_type, payload_type

Data Flow

Workflow reads/writes, input/output contracts.

reads, writes, uses_rule, calls

Events

Event emission, subscription, scheduling.

emits, triggers_on, notifies, transitions

Invocation

Step calls, workflow triggers, hook bindings.

invokes, binds, exposes_action

Surface

Screen bindings, action links, component composition.

contains_surface, targets_surface, uses_serialization

Governance

Constitution policies, security rules, authorization.

governs, authorized_as, binds_secret, uses_secret

Testing

Test targets, assertion references, preconditions.

tests, attaches_to, product_dependency

Type References

Field types are encoded in the graph as structured references:

Primitives - "string", "integer", "boolean", "datetime", "uuid", etc.
References - { "ref": "core.entity.user" }
Generics - { "generic": "list", "arg": "string" } or { "generic": "optional", "arg": { "ref": "..." } }

Determinism

The same input spec always produces the exact same Product Graph, with the sole exception of the compiled_at timestamp in metadata. Source files are identified by SHA-256 hash, making it safe to use graph equality for caching, diffing, and drift detection.

Generating the Graph

# Emit the Product Graph as JSON
prodara graph --format json ./project

# Save to a specific file
prodara graph --output build/product-graph.json ./project

# Access programmatically
import { buildGraph, serializeGraph } from '@prodara/compiler';