Graph Layers Reference

One section per layer of the Unified Project Graph — node types, edge types, and example traversal queries for each.

Graph Layers Reference

The Unified Project Graph stores all nodes in context_artifacts and all edges in context_artifact_dependencies. Layers are distinguished by the artifact_type prefix on each node. This page documents each layer individually: its purpose, its node types, its edge types, and an example query showing how to traverse it.

For the full architectural overview, see Unified Project Graph.


Layer 1: Business Intent

Prefix: spec_* (business intent subset) Populated by: The 6-phase elicitation engine (discovery conversations) Purpose: Captures what the product is supposed to do in human terms — the "why" and "what" before any architectural decisions are made.

Node Types

Node TypeWhat It RepresentsKey Metadata Fields
spec_projectThe project itselfname, description, domain, audience
spec_bounded_contextA domain boundaryname, responsibilities[], ubiquitous_language{}
spec_epicA major feature groupname, goal, priority
spec_user_storyA user-facing capabilityas_a, i_want, so_that, priority, story_points
spec_acceptance_criterionA testable condition for a storydescription, is_automated, test_node_id
spec_constraintA non-functional requirementtype (performance/security/compliance/ux), description, measurable
spec_personaA user typename, role, goals[], pain_points[]

Edge Types

Edge TypeFrom → ToMeaning
containsspec_projectspec_bounded_contextProject scope contains this domain
containsspec_bounded_contextspec_epicDomain contains this epic
containsspec_epicspec_user_storyEpic contains this story
has_criteriaspec_user_storyspec_acceptance_criterionStory requires this criterion to be satisfied
governsspec_constraintspec_epic / spec_operationConstraint governs this artifact
rendersspec_ui_pagespec_user_storyThis page is the primary UI for this story

Example Query: Find All Unverified Acceptance Criteria

Returns acceptance criteria with no tests bridge edge — meaning no test case is linked to them.

SELECT ca.id, ca.artifact_key, ca.content
FROM context_artifacts ca
WHERE ca.project_id = :project_id
  AND ca.artifact_type = 'spec_acceptance_criterion'
  AND ca.is_active = true
  AND ca.id NOT IN (
    SELECT cad.depends_on_id
    FROM context_artifact_dependencies cad
    WHERE cad.dependency_type = 'tests'
  )
ORDER BY ca.created_at;

Layer 2: System Structure

Prefix: spec_* (system structure subset) Populated by: Discovery engine domain analysis pass; implementation planner Purpose: Captures the architectural shape of the system — entities, services, APIs, data schemas, and guard conditions. This is where requirements become typed design artifacts.

Node Types

Node TypeWhat It RepresentsKey Metadata Fields
spec_entityA domain objectname, fields[], bounded_context, is_aggregate_root
spec_fieldA property of an entityname, type, required, unique, default
spec_serviceA logical service boundaryname, responsibility, bounded_context
spec_operationAn action a service performsname, parameters[], returns, side_effects[]
spec_endpointAn API surfacemethod, path, auth_required, input_schema, output_schema
spec_schemaA data shape / validationname, fields[], validation_rules[]
spec_guardA security or business rulecondition, type (auth/role/business_rule), failure_behavior

Edge Types

Edge TypeFrom → ToMeaning
containsspec_bounded_contextspec_entityDomain contains this entity
containsspec_bounded_contextspec_serviceDomain contains this service
has_fieldspec_entityspec_fieldEntity has this field
has_operationspec_servicespec_operationService exposes this operation
has_inputspec_endpointspec_schemaEndpoint accepts this input shape
has_outputspec_endpointspec_schemaEndpoint returns this output shape
requiresspec_operationspec_entityOperation requires this entity to exist
guardsspec_guardspec_endpointGuard condition must pass before endpoint executes
guardsspec_guardspec_operationGuard condition must pass before operation executes

Example Query: Find All Endpoints Missing an Auth Guard

Returns spec_endpoint nodes with auth_required = true in their metadata that have no inbound guards edge.

SELECT ca.id, ca.artifact_key, ca.metadata->>'path' AS path, ca.metadata->>'method' AS method
FROM context_artifacts ca
WHERE ca.project_id = :project_id
  AND ca.artifact_type = 'spec_endpoint'
  AND ca.is_active = true
  AND (ca.metadata->>'auth_required')::boolean = true
  AND ca.id NOT IN (
    SELECT cad.artifact_id
    FROM context_artifact_dependencies cad
    JOIN context_artifacts guard_ca ON guard_ca.id = cad.depends_on_id
    WHERE cad.dependency_type = 'guards'
      AND guard_ca.artifact_type = 'spec_guard'
  )
ORDER BY ca.artifact_key;

Layer 3: Behavior

Prefix: spec_* (behavior subset) Populated by: Discovery engine journey analysis; UI planning pass Purpose: Captures how the system behaves at runtime — user journeys, async workflows, and UI structure. This layer is the spec-side equivalent of the code EOG and DFG.

Node Types

Node TypeWhat It RepresentsKey Metadata Fields
spec_flow_stepA step in a user journeydescription, actor, preconditions[], postconditions[]
spec_workflowAn async multi-step processname, trigger, timeout, retry_policy
spec_workflow_stepA step in a workflowname, action, success_next, failure_next
spec_ui_pageA page in the applicationpath, layout, auth_required, data_requirements[]
spec_ui_componentA UI componentname, purpose, data_source, interactions[]
spec_ui_stateA UI state conditionname (loading/error/empty/populated), triggers[]
spec_ui_layoutA layout containername, slots[], responsive_behavior

Edge Types

Edge TypeFrom → ToMeaning
flow_nextspec_flow_stepspec_flow_stepSequential step ordering
flow_branchspec_flow_stepspec_flow_stepConditional branching (condition stored in edge metadata)
workflow_step_ofspec_workflow_stepspec_workflowStep belongs to this workflow
invokesspec_workflow_stepspec_operationWorkflow step invokes this service operation
triggersevent node → spec_workflowThis event triggers this workflow
producesspec_operation → event nodeThis operation produces this event
displaysspec_ui_componentspec_entityComponent displays this entity's data
callsspec_ui_componentspec_endpointComponent calls this API endpoint
managesspec_ui_componentspec_ui_stateComponent manages this state
navigates_tospec_ui_pagespec_ui_pagePage navigates to this page
layout_containsspec_ui_layoutspec_ui_pageLayout contains this page

Example Query: Traverse a User Journey in Sequence Order

Returns all flow steps for a given journey in execution order, with branch conditions.

WITH RECURSIVE journey AS (
  SELECT ca.id, ca.artifact_key, ca.content, cad.dependency_type, cad.metadata->>'condition' AS branch_condition, 1 AS step_order
  FROM context_artifacts ca
  LEFT JOIN context_artifact_dependencies cad ON cad.artifact_id = ca.id
  WHERE ca.project_id = :project_id
    AND ca.artifact_type = 'spec_flow_step'
    AND ca.id = :entry_step_id

  UNION ALL

  SELECT next_ca.id, next_ca.artifact_key, next_ca.content, next_edge.dependency_type, next_edge.metadata->>'condition', j.step_order + 1
  FROM context_artifact_dependencies next_edge
  JOIN context_artifacts next_ca ON next_ca.id = next_edge.artifact_id
  JOIN journey j ON next_edge.depends_on_id = j.id
  WHERE next_edge.dependency_type IN ('flow_next', 'flow_branch')
    AND j.step_order < 50  -- cycle guard
)
SELECT * FROM journey ORDER BY step_order;

Layer 4: Implementation Plan

Prefix: impl_* Populated by: The implementation plan generator (pre-codegen phase) Purpose: The bridge between "what" (spec) and "how" (code). Contains all concrete decisions about file paths, libraries, import patterns, type names, and architectural choices. This layer is what gets handed to code Kits as their primary input.

Node Types

Node TypeWhat It RepresentsKey Metadata Fields
impl_entityImplementation plan for an entityfile_path, orm, table_name, columns[]
impl_serviceImplementation plan for a servicefile_path, class_name, injected_deps[]
impl_operationImplementation plan for an operationfile_path, function_name, imports[], validation_library
impl_endpointImplementation plan for a routefile_path, router_library, middleware[]
impl_guardImplementation plan for a guardfile_path, guard_type, mechanism
impl_workflowImplementation plan for a workflowfile_path, orchestration_library, trigger_event
impl_ui_pageImplementation plan for a pagefile_path, framework, data_fetching_pattern
impl_ui_componentImplementation plan for a componentfile_path, component_library, state_management

Edge Types

Edge TypeFrom → ToMeaning
realizesimpl_*spec_*This plan realizes that spec intent
requiresimpl_*impl_*This plan depends on another plan being generated first
composed-ofimpl_serviceimpl_operationService plan contains this operation plan
capability_interfaceimpl_* → interface contract nodePlan exposes this typed interface

Example Query: Topological Sort for Code Generation Order

Returns impl nodes in batches — each batch can be generated in parallel; all dependencies of a batch are in earlier batches.

WITH RECURSIVE topo AS (
  SELECT ca.id, ca.artifact_key, ca.artifact_type, 0 AS depth
  FROM context_artifacts ca
  WHERE ca.project_id = :project_id
    AND ca.artifact_type LIKE 'impl_%'
    AND ca.is_active = true
    AND ca.id NOT IN (
      SELECT DISTINCT cad.artifact_id
      FROM context_artifact_dependencies cad
      WHERE cad.dependency_type = 'requires'
    )

  UNION ALL

  SELECT ca.id, ca.artifact_key, ca.artifact_type, t.depth + 1
  FROM context_artifact_dependencies cad
  JOIN context_artifacts ca ON ca.id = cad.artifact_id
  JOIN topo t ON t.id = cad.depends_on_id
  WHERE cad.dependency_type = 'requires'
    AND t.depth < 20
)
SELECT DISTINCT id, artifact_key, artifact_type, MAX(depth) AS batch
FROM topo
GROUP BY id, artifact_key, artifact_type
ORDER BY batch, artifact_key;

Layer 5: Code

Prefix: code_* Populated by: Brownfield CPG pipeline (existing code analysis) or the codegen pipeline (generated code) Purpose: Represents what was actually built. Code layer nodes are created from static analysis of source files. They are the "reality" side of the spec-to-code bridge.

Node Types

Node TypeWhat It RepresentsKey Metadata Fields
code_moduleA source filefile_path, language, exports[], import_count
code_classA class definitionfile_path, class_name, methods[], extends, implements[]
code_functionA function or methodfile_path, function_name, parameters[], return_type, complexity
code_endpointAn HTTP route handlermethod, path, file_path, middleware_chain[]
code_tableA database tabletable_name, columns[], indexes[], foreign_keys[]
code_schemaA validation schemafile_path, schema_name, library, fields[]
code_componentA UI componentfile_path, component_name, props[], hooks[]
code_routeA frontend routepath, file_path, layout, data_loading_pattern

Edge Types

Within the code layer, edges come from four CPG sub-layers:

AST (structural):

Edge TypeFrom → ToExample
referencescode_functioncode_functionregister() calls hashPassword()
importscode_modulecode_moduleauth-service.ts imports crypto.ts
extendscode_classcode_classAdminService extends UserService

EOG (execution order):

Edge TypeFrom → ToExample
controls_flow_tocode_functioncode_functionExecution continues from handler to service

DFG (data flow):

Edge TypeFrom → ToExample
data_flows_tocode node → code nodePassword value flows from request body to bcrypt

CDG (control dependence):

Edge TypeFrom → ToExample
controlscode_functioncode_functionAuth middleware controls whether handler executes

Bridge edges (spec ↔ code):

Edge TypeFrom → ToMeaning
implementscode_functionspec_operationThis function implements this operation
exposescode_endpointspec_endpointThis handler exposes this API endpoint
persistscode_tablespec_entityThis table persists this entity
satisfiescode_functionspec_user_storyThis code satisfies this story
drifts_fromcode_functionspec_operationImplementation has diverged from spec
generated_fromcode_*impl_*This code was generated from this plan

Example Query: Find Code Nodes With No Spec Requirement

Returns code layer nodes that have no inbound bridge edge — code that exists but no spec requires.

SELECT ca.id, ca.artifact_key, ca.artifact_type, ca.metadata->>'file_path' AS file_path
FROM context_artifacts ca
WHERE ca.project_id = :project_id
  AND ca.artifact_type LIKE 'code_%'
  AND ca.is_active = true
  AND ca.id NOT IN (
    SELECT cad.artifact_id
    FROM context_artifact_dependencies cad
    WHERE cad.dependency_type IN ('implements', 'exposes', 'persists', 'satisfies')
  )
ORDER BY ca.artifact_type, ca.artifact_key;

Layer 6: Verification and Infrastructure

Prefixes: test_*, infra_* Populated by: Test analysis pipeline; infrastructure configuration ingestion Purpose: Captures what proves correctness (test_*) and what the system runs on (infra_*). Test nodes are linked to spec acceptance criteria via tests edges, closing the spec → code → verification loop.

Node Types

Node TypeWhat It RepresentsKey Metadata Fields
test_suiteA test filefile_path, framework, test_count
test_caseA single testname, file_path, line_number, status (passing/failing/skipped)
test_assertionA specific check within a testdescription, type (equality/snapshot/throws)
test_fixtureReusable test dataname, shape, values
infra_serviceA deployed servicename, provider, region, tier
infra_dependencyAn external dependencyname, type (api/queue/cdn), sla, authentication_method
infra_configConfiguration / environment variablekey, required, secret, default

Edge Types

Edge TypeFrom → ToMeaning
teststest_casespec_acceptance_criterionThis test verifies this acceptance criterion
validatestest_casecode_functionThis test directly exercises this function
coverstest_suitecode_moduleThis test file covers this module
mockstest_caseinfra_dependencyThis test mocks this external dependency
uses_fixturetest_casetest_fixtureThis test uses this fixture

Example Query: Find Acceptance Criteria Covered by Tests

Returns criteria with their covering test cases and current test status.

SELECT
  crit.id AS criterion_id,
  crit.artifact_key AS criterion_key,
  crit.content AS criterion_text,
  tc.id AS test_case_id,
  tc.artifact_key AS test_key,
  tc.metadata->>'status' AS test_status
FROM context_artifacts crit
JOIN context_artifact_dependencies cad ON cad.depends_on_id = crit.id AND cad.dependency_type = 'tests'
JOIN context_artifacts tc ON tc.id = cad.artifact_id AND tc.artifact_type = 'test_case'
WHERE crit.project_id = :project_id
  AND crit.artifact_type = 'spec_acceptance_criterion'
  AND crit.is_active = true
ORDER BY crit.artifact_key;

Cross-Layer Reachability Matrix

The following matrix shows which layers can reach which other layers through direct traversal (one edge hop):

From LayerReachesVia Edge Types
Business Intent (L1)System Structure (L2)contains, governs
Business Intent (L1)Behavior (L3)renders
System Structure (L2)Behavior (L3)has_operation, invokes
System Structure (L2)Impl Plan (L4)realizes (reverse)
Behavior (L3)Impl Plan (L4)realizes (reverse)
Impl Plan (L4)Code (L5)generated_from (reverse)
Code (L5)System Structure (L2)implements, exposes, persists, satisfies
Code (L5)Verification (L6)covers (reverse)
Verification (L6)Business Intent (L1)tests
Verification (L6)Code (L5)validates

For multi-hop traversal (e.g., "which business requirements are covered by currently passing tests?"), use the recursive CTE pattern shown in the layer queries above, filtering by dependency_type at each hop.


Reference

TopicLocation
Full architectural overviewUnified Project Graph
Node table schemasrc/db/migrations/194_context_artifacts.sql
Edge table schemasrc/db/migrations/197_context_artifact_dependencies.sql
All edge type valuessrc/db/migrations/427_context_artifact_dependency_types_expand.sql
PIM column additionssrc/db/migrations/362_context_artifacts_pim_columns.sql
GraphQueryServicesrc/services/graph/graph-query-service.ts
Spec-to-impl mappingdocs/scale/specs/SPEC-FULLMAP-001-bidirectional-mapping.md

Command Palette

Search for a command to run...