Spatial Predicates Migration - Frontend Guide

Migration Date: 2025-07-03 08:17:03
Affected Components: GraphQL types, spatial relationship handling, drag-and-drop UI
Status: ✅ Complete

Overview

The Plings system has migrated from legacy spatial predicates to a dual predicate system supporting both NORMAL_ (designated locations) and CURRENT_ (actual locations) predicates. This enables enhanced inventory management with misplacement detection capabilities.

Changes Made

1. GraphQL Types Updated

Before:

interface PositionalRelationship {
  relationshipType: 'IN' | 'TO_LEFT' | 'TO_RIGHT' | 'ABOVE' | 'BELOW' | 'SHOULD_BE_IN' | 'NONE';
}

After:

interface PositionalRelationship {
  relationshipType: 'NORMAL_IN' | 'NORMAL_LEFT_OF' | 'NORMAL_RIGHT_OF' | 'NORMAL_ABOVE' | 'NORMAL_UNDER' | 'NORMAL_ON' | 'NORMAL_ATTACHED_TO' | 'NORMAL_NEXT_TO' | 
                   'CURRENT_IN' | 'CURRENT_LEFT_OF' | 'CURRENT_RIGHT_OF' | 'CURRENT_ABOVE' | 'CURRENT_UNDER' | 'CURRENT_ON' | 'CURRENT_ATTACHED_TO' | 'CURRENT_NEXT_TO' |
                   'IN' | 'TO_LEFT' | 'TO_RIGHT' | 'ABOVE' | 'BELOW' | 'SHOULD_BE_IN' | 'NONE'; // Legacy predicates for backward compatibility
}

2. Component Updates

ObjectCardWithDropzones.tsx

  • Updated dropzone mappings to use NORMAL_ predicates by default
  • Added predicate mapping system for legacy compatibility
  • Enhanced relationship labels to distinguish between NORMAL_, CURRENT_, and legacy predicates

SpatialHierarchyView.tsx

  • Updated relationship type mappings to use NORMAL_ predicates
  • Maintained same UI behavior while using new backend predicates

useSpatialHierarchy.ts

  • Updated type definitions to include all predicate variants
  • Maintains backward compatibility with existing data

3. Backend Integration

The backend now:

  • Accepts both NORMAL_ and legacy predicates in GraphQL mutations
  • Automatically maps legacy predicates to NORMAL_ predicates
  • Stores relationships using NORMAL_ predicates in Neo4j
  • Maintains backward compatibility for existing queries

Predicate System Explanation

NORMAL_ Predicates (Current Implementation)

These represent where objects should be - their designated or expected locations:

  • NORMAL_IN: Object’s designated container
  • NORMAL_LEFT_OF: Object’s expected position to the left
  • NORMAL_RIGHT_OF: Object’s expected position to the right
  • NORMAL_ABOVE: Object’s expected position above
  • NORMAL_UNDER: Object’s expected position below
  • NORMAL_ON: Object’s expected surface placement
  • NORMAL_ATTACHED_TO: Object’s expected attachment
  • NORMAL_NEXT_TO: Object’s expected adjacent placement

CURRENT_ Predicates (Future Implementation)

These will represent where objects actually are - their real-time observed locations:

  • CURRENT_IN: Object’s actual current container
  • CURRENT_LEFT_OF: Object’s actual current position to the left
  • And so on…

Legacy Predicates (Backward Compatibility)

These are maintained for compatibility and automatically mapped:

  • IN → NORMAL_IN
  • TO_LEFT → NORMAL_LEFT_OF
  • TO_RIGHT → NORMAL_RIGHT_OF
  • ABOVE → NORMAL_ABOVE
  • BELOW → NORMAL_UNDER
  • SHOULD_BE_IN → NORMAL_IN

Benefits

  1. Misplacement Detection: Future ability to compare NORMAL_ vs CURRENT_ predicates
  2. Inventory Intelligence: Track designated vs actual object locations
  3. Enhanced Organization: Guide users to return objects to designated locations
  4. Backward Compatibility: Existing code continues to work unchanged
  5. Future-Proofing: Foundation for real-time location tracking

Frontend Developer Guidelines

When Creating New Components

  • Use NORMAL_ predicates for new spatial relationship creation
  • Support both NORMAL_ and legacy predicates in display logic
  • Always test with existing data that may use legacy predicates

When Updating Existing Components

  • Maintain backward compatibility with legacy predicate handling
  • Update type definitions to include new predicate options
  • Test thoroughly with mixed predicate data

GraphQL Mutations

  • Can continue using legacy predicates - backend handles mapping
  • Prefer NORMAL_ predicates for new functionality
  • No changes required to existing mutation calls

Migration Impact

✅ No Breaking Changes

  • All existing frontend code continues to work
  • GraphQL mutations accept both old and new predicates
  • Backend automatically handles predicate mapping

✅ Enhanced Capabilities

  • New predicate types available for advanced features
  • Foundation for misplacement detection
  • Improved inventory management capabilities

✅ Future-Ready

  • System prepared for CURRENT_ predicate implementation
  • Real-time location tracking capabilities planned
  • Enhanced spatial intelligence features enabled

Testing Notes

  • Test drag-and-drop operations create NORMAL_ predicates
  • Verify legacy predicate handling in existing data
  • Confirm UI displays correctly for all predicate types
  • Check GraphQL responses include expected predicate values

For questions about this migration, refer to the backend team or check the Neo4j database directly to see the current predicate usage.