Graph Schema

Complete graph schema covering the Digital Thread (L1) and Digital Twin evolution layers (L2-L4)

Table of Contents

  1. Overview
  2. Node Types — Digital Thread (L1)
    1. Requirement
    2. DesignElement
    3. BOMItem
    4. TestProcedure
    5. TestExecution
    6. Evidence
    7. Certification
    8. RiskItem
    9. DecisionRecord
    10. Gate
    11. Session
    12. CAPARecord (P2)
    13. InterfaceContract (P2)
    14. KnowledgeSource (P2)
  3. Node Types — Twin Instance & Simulation (L2-L4)
    1. TwinModel (P2)
    2. DeviceInstance (P2)
    3. TelemetrySource (P3)
    4. BehavioralModel (P3)
    5. SimulationRun (P3)
    6. FleetGroup (P4)
  4. Relationship Types
    1. Digital Thread Relationships (L1)
    2. Cross-Domain Ontology Relationships (L1)
    3. Twin Instance & Simulation Relationships (L2-L4)
  5. Neo4j Constraints & Indexes
    1. Uniqueness Constraints (P1)
    2. Twin Instance Constraints (P2-P3)
    3. Performance Indexes
  6. Example Queries
    1. Traceability: Requirement to Test Evidence (L1)
    2. Gate Readiness Check (L1)
    3. Device Fleet Health (L3-L4)
  7. Related Documents

Overview

The MetaForge graph schema defines the node types, relationships, and constraints that form the Digital Twin’s data model. The schema is layered to support phased delivery:

Layer Phase Scope
L1 — Digital Thread P1 (MVP) Artifact graph, traceability, versioning, constraints
L2 — Operational Twin P2 Device provisioning, test telemetry, CAPA workflows
L3 — Live Twin P3 Real-time device synchronization, telemetry sources
L4 — Simulation Twin P3-P4 Behavioral models, simulation runs, fleet analytics

All nodes carry common base properties:

Property Type Description
id UUID Unique identifier
version Integer Optimistic concurrency version counter
createdAt DateTime Creation timestamp
updatedAt DateTime Last modification timestamp
createdBy String Actor ID (agent code, user ID, or device ID)

Node Types — Digital Thread (L1)

These nodes form the core traceability graph delivered in Phase 1 (MVP).

Requirement

Property Required Type Description
title Yes String Short requirement title
description Yes String Full requirement description
category Yes String Requirement category
priority Yes String Priority level
status Yes Enum draft / active / approved / deprecated
acceptanceCriteria No String Acceptance criteria
source No String Origin of the requirement
rationale No String Justification

DesignElement

Property Required Type Description
name Yes String Element name
domain Yes Enum mechanical / electrical / firmware / system
type Yes String Element type within domain
description No String Description
parameters No Map Key-value parameters

BOMItem

Property Required Type Description
mpn Yes String Manufacturer part number
manufacturer Yes String Manufacturer name
description Yes String Part description
quantity Yes Integer Quantity required
package Yes String Package type
unitPrice No Float Unit price
stock No Integer Available stock
leadTime No String Lead time
lifecycle No String Lifecycle status
specifications No Map Technical specifications

TestProcedure

Property Required Type Description
name Yes String Procedure name
category Yes Enum functional / environmental / emc / safety
requirementIds Yes List Linked requirement IDs
description No String Procedure description
automationLevel No Enum manual / semi / full

TestExecution

Property Required Type Description
procedureId Yes String Linked TestProcedure ID
timestamp Yes DateTime Execution timestamp
status Yes Enum passed / failed / skipped
duration Yes Duration Execution duration
notes No String Execution notes
artifactIds No List Related artifact IDs
commit No String Git commit hash

Evidence

Property Required Type Description
type Yes Enum test-report / certification / analysis
status Yes Enum pending / submitted / approved / rejected
artifactId No String MinIO artifact reference
reviewedBy No String Reviewer ID
reviewNotes No String Review comments

Certification

Property Required Type Description
regime Yes Enum UKCA / CE / FCC / PSTI
standard Yes String Standard reference
market Yes String Target market
status No String Certification status
expiryDate No Date Expiry date
notifiedBody No String Notified body name

RiskItem

Property Required Type Description
type Yes Enum single-source / eol / long-lead / safety / cybersecurity
severity Yes String Severity level
description Yes String Risk description
mitigation No String Mitigation strategy
owner No String Risk owner
dueDate No Date Mitigation due date
fmeaId No String FMEA reference

DecisionRecord

Property Required Type Description
title Yes String Decision title
status Yes Enum proposed / accepted / rejected / superseded
date Yes Date Decision date
context No String Decision context
options No List Considered options
outcome No String Chosen outcome
rationale No String Decision rationale

Gate

Property Required Type Description
type Yes Enum EVT / DVT / PVT
status Yes Enum not-ready / at-risk / ready / passed
score No Float Readiness score
blockers No List Blocking items
passedAt No DateTime Gate passage timestamp
approvedBy No String Approver ID

Session

Property Required Type Description
skill Yes String Skill name executed
status Yes String Session status
agentCode Yes String Agent identifier
input No Map Session input data
output No Map Session output data
traces No List Execution trace references

CAPARecord (P2)

Property Required Type Description
type Yes Enum corrective / preventive
severity Yes String Severity level
status Yes String CAPA status
rootCause No String Root cause analysis
action No String Corrective/preventive action
owner No String Action owner
verifiedAt No DateTime Verification timestamp

InterfaceContract (P2)

Property Required Type Description
name Yes String Interface name
fromDomain Yes String Source domain
toDomain Yes String Target domain
protocol Yes String Interface protocol
schema No Map Interface schema definition
version No String Contract version
testIds No List Validation test IDs

KnowledgeSource (P2)

Represents a document or data source that has been ingested into the Knowledge Layer. Each KnowledgeSource maps to one or more embedding fragments in pgvector.

Property Required Type Description
sourceType Yes Enum datasheet / application_note / design_guide / errata
title Yes String Document title
artifactId Yes String MinIO artifact reference
fragmentCount No Integer Number of embedding chunks created
embeddingModel No String Model used for embedding (e.g., all-MiniLM-L6-v2)
status Yes Enum pending / indexing / indexed / failed
indexedAt No DateTime When indexing completed
partNumber No String Associated part number (for datasheets)
metadata No Map Additional metadata (tags, version, etc.)

Node Types — Twin Instance & Simulation (L2-L4)

These nodes extend the graph for device synchronization, behavioral simulation, and fleet analytics.

TwinModel (P2)

Property Required Type Description
name Yes String Product model name
version Yes String Model version
productId Yes String Product identifier
schema Yes Map Model schema definition
behavioralModels No List Linked behavioral model IDs
constraints No List Model-level constraints
syncPolicy No Map Default synchronization policy

DeviceInstance (P2)

Property Required Type Description
serialNumber Yes String Unique serial number
twinModelId Yes String Linked TwinModel ID
status Yes Enum provisioned / active / maintenance / decommissioned
location No String Physical location
firmwareVersion No String Deployed firmware version
deployedAt No DateTime Deployment timestamp
lastSyncAt No DateTime Last synchronization timestamp

TelemetrySource (P3)

Property Required Type Description
instanceId Yes String Linked DeviceInstance ID
sensorType Yes String Sensor type
dataSchema Yes Map Data schema for readings
sampleRate Yes Float Sample rate in Hz
unit No String Measurement unit
range No Map Valid measurement range
calibration No Map Calibration data

BehavioralModel (P3)

Property Required Type Description
name Yes String Model name
modelType Yes Enum differential-equation / transfer-function / thermal-rc / lookup-table
domain Yes String Engineering domain
inputs No List Named inputs with units
outputs No List Named outputs with units
parameters No Map Model constants
validationData No Map Validation dataset reference

SimulationRun (P3)

Property Required Type Description
modelId Yes String Linked BehavioralModel ID
instanceId Yes String Linked DeviceInstance ID
timestamp Yes DateTime Simulation timestamp
status Yes String Run status
type Yes Enum prediction / what-if / validation
inputs No Map Simulation inputs
results No Map Simulation results
duration No Duration Execution duration
accuracy No Float Prediction accuracy metric

FleetGroup (P4)

Property Required Type Description
name Yes String Fleet group name
twinModelId Yes String Linked TwinModel ID
criteria Yes Map Membership criteria
memberCount No Integer Number of members
aggregateMetrics No Map Fleet-level metrics

Relationship Types

Digital Thread Relationships (L1)

Relationship Source Target Phase Description
SATISFIED_BY Requirement DesignElement P1 Design element satisfies requirement
MANUFACTURED_BY DesignElement BOMItem P1 Design element implemented by BOM parts
TESTED_BY BOMItem / DesignElement TestProcedure P1 Artifact has test procedure
PRODUCES TestProcedure Evidence P1 Test produces evidence
JUSTIFIES Evidence Certification P1 Evidence justifies certification
DERIVED_FROM Requirement Requirement P1 Requirement decomposition
DEPENDS_ON BOMItem BOMItem P1 Component dependency
MITIGATES DesignElement RiskItem P1 Design mitigates risk
BLOCKS RiskItem Gate P1 Risk blocks gate passage
PRODUCED_BY Any Session P1 Provenance: artifact created by session
SUPERSEDES Any Any (same type) P1 Revision chain
APPROVED_BY Gate / DecisionRecord User P1 Governance trail
EXECUTED_IN TestExecution TestProcedure P1 Execution of procedure
RAISES TestExecution CAPARecord P1 Failed test raises CAPA

Cross-Domain Ontology Relationships (L1)

These relationships encode physical and logical couplings between design elements across engineering domains. They are the foundation for cross-domain constraint propagation.

Relationship Source Target Description
THERMALLY_COUPLED_TO DesignElement DesignElement Thermal path between components (conduction, convection, radiation)
ELECTRICALLY_CONNECTED_TO DesignElement DesignElement Electrical connection (power rail, signal trace, ground plane)
MOUNTED_TO DesignElement DesignElement Physical mounting relationship (component on PCB, PCB in enclosure)
CONTROLLED_BY DesignElement DesignElement Control relationship (sensor → MCU, MCU → actuator, firmware → peripheral)
SHARES_RESOURCE DesignElement DesignElement Shared resource contention (SPI bus, power rail, cooling channel)
CONSTRAINS DesignElement DesignElement One element constrains another (keep-out zone, timing dependency, voltage level)

Example: Cross-domain coupling for a motor driver

-- The MOSFET is thermally coupled to the heatsink
MATCH (mosfet:DesignElement {name: 'Q1_MOSFET'})-[:THERMALLY_COUPLED_TO]->(heatsink:DesignElement {name: 'HS1'})

-- The MOSFET is electrically connected to the motor rail
MATCH (mosfet)-[:ELECTRICALLY_CONNECTED_TO]->(rail:DesignElement {name: 'VMOTOR_RAIL'})

-- The MOSFET is controlled by the MCU via PWM
MATCH (mosfet)-[:CONTROLLED_BY]->(mcu:DesignElement {name: 'MCU_STM32'})

-- The MCU firmware controls the PWM output
MATCH (mcu)-[:CONTROLLED_BY]->(pwm_driver:DesignElement {domain: 'firmware', name: 'pwm_driver'})

These ontology relationships enable the constraint engine to answer questions like:

  • “If the ambient temperature rises, which components exceed thermal limits?” (traverse THERMALLY_COUPLED_TO)
  • “If we change the MCU, which firmware modules and peripherals are affected?” (traverse CONTROLLED_BY)
  • “Which components share this power rail and what’s the total current draw?” (traverse ELECTRICALLY_CONNECTED_TO + SHARES_RESOURCE)

Twin Instance & Simulation Relationships (L2-L4)

Relationship Source Target Phase Description
INSTANCE_OF DeviceInstance TwinModel P2 Device is an instance of a product model
FEEDS TelemetrySource DeviceInstance P3 Sensor feeds data to twin instance
SIMULATED_BY DeviceInstance BehavioralModel P3 Device behavior predicted by model
CALIBRATED_FROM BehavioralModel TestExecution P3 Model calibrated from real test data
MEMBER_OF DeviceInstance FleetGroup P4 Device belongs to fleet group

Neo4j Constraints & Indexes

Uniqueness Constraints (P1)

-- Core graph uniqueness
CREATE CONSTRAINT req_id IF NOT EXISTS FOR (r:Requirement) REQUIRE r.id IS UNIQUE;
CREATE CONSTRAINT bom_id IF NOT EXISTS FOR (b:BOMItem) REQUIRE b.id IS UNIQUE;
CREATE CONSTRAINT design_id IF NOT EXISTS FOR (d:DesignElement) REQUIRE d.id IS UNIQUE;
CREATE CONSTRAINT test_proc_id IF NOT EXISTS FOR (t:TestProcedure) REQUIRE t.id IS UNIQUE;
CREATE CONSTRAINT gate_id IF NOT EXISTS FOR (g:Gate) REQUIRE g.id IS UNIQUE;
CREATE CONSTRAINT session_id IF NOT EXISTS FOR (s:Session) REQUIRE s.id IS UNIQUE;

Twin Instance Constraints (P2-P3)

CREATE CONSTRAINT device_serial IF NOT EXISTS FOR (d:DeviceInstance) REQUIRE d.serialNumber IS UNIQUE;
CREATE CONSTRAINT twin_model_id IF NOT EXISTS FOR (t:TwinModel) REQUIRE t.id IS UNIQUE;
CREATE CONSTRAINT sim_run_id IF NOT EXISTS FOR (s:SimulationRun) REQUIRE s.id IS UNIQUE;

Performance Indexes

-- Digital Thread indexes
CREATE INDEX req_status IF NOT EXISTS FOR (r:Requirement) ON (r.status);
CREATE INDEX bom_lifecycle IF NOT EXISTS FOR (b:BOMItem) ON (b.lifecycle);
CREATE INDEX bom_mpn IF NOT EXISTS FOR (b:BOMItem) ON (b.mpn);
CREATE INDEX gate_type IF NOT EXISTS FOR (g:Gate) ON (g.type);
CREATE INDEX evidence_status IF NOT EXISTS FOR (e:Evidence) ON (e.status);

-- Twin Instance indexes
CREATE INDEX device_status IF NOT EXISTS FOR (d:DeviceInstance) ON (d.status);
CREATE INDEX device_model IF NOT EXISTS FOR (d:DeviceInstance) ON (d.twinModelId);
CREATE INDEX sim_run_type IF NOT EXISTS FOR (s:SimulationRun) ON (s.type);

Example Queries

Traceability: Requirement to Test Evidence (L1)

MATCH path = (r:Requirement)-[:SATISFIED_BY]->(d:DesignElement)
             -[:MANUFACTURED_BY]->(b:BOMItem)
             -[:TESTED_BY]->(tp:TestProcedure)
             -[:PRODUCES]->(e:Evidence)
WHERE r.id = $requirementId
RETURN path

Gate Readiness Check (L1)

MATCH (g:Gate {type: 'EVT'})
OPTIONAL MATCH (risk:RiskItem)-[:BLOCKS]->(g)
WHERE risk.severity = 'critical'
OPTIONAL MATCH (r:Requirement {status: 'active'})
WHERE NOT (r)-[:SATISFIED_BY]->()
RETURN g, collect(risk) AS blockers, collect(r) AS unmetRequirements

Device Fleet Health (L3-L4)

MATCH (d:DeviceInstance)-[:INSTANCE_OF]->(tm:TwinModel {name: $modelName})
WHERE d.status = 'active'
OPTIONAL MATCH (d)<-[:FEEDS]-(ts:TelemetrySource)
OPTIONAL MATCH (sr:SimulationRun {instanceId: d.id})
WHERE sr.timestamp > datetime() - duration('P1D')
RETURN d.serialNumber, d.lastSyncAt, collect(ts.sensorType) AS sensors,
       collect(sr.results) AS recentSimulations

Document Description
Event Sourcing Event schema and stream architecture for graph mutations
Constraint Engine Engineering constraint evaluation against the graph
Digital Twin Evolution Full twin architecture: sync, simulation, phased delivery
AI Memory & Knowledge Knowledge Layer that embeds graph nodes (DecisionRecord, BOMItem, etc.) into pgvector
System Vision Architectural principles and layered Digital Twin model
ADR-004: Digital Twin Standards AAS alignment decisions and schema additions (globalAssetId, supplier, specification keys)
Digital Twin Standards Landscape Research: industry standards evaluation

Document Version: v1.1 Last Updated: 2026-02-28 Status: Technical Architecture Document

← Architecture Event Sourcing →