← Back to Main Documentation

Core Systems Index

Organization Ownership Intelligence System

Overview

The Organization Ownership Intelligence System provides advanced organization selection during object creation by analyzing spatial hierarchy context and user behavior patterns. This system eliminates the need for manual organization selection in most cases by intelligently predicting the most appropriate organization based on the user’s current spatial context and creation history.

Core Principles

1. Spatial Context Awareness

Objects inherit organizational context from their spatial hierarchy. The system recognizes that different spatial roots (home, work, warehouse, etc.) represent distinct organizational landscapes with different ownership patterns.

Key Concepts:

• Spatial Hierarchy Roots: Top-level containers that define organizational boundaries (e.g., home lot, office building, warehouse facility)
• Organizational Territories: Spaces where specific organizations have established presence through object ownership
• Context Inheritance: New objects naturally belong to the same organizational context as their spatial environment

2. User Behavior Intelligence

The system tracks and learns from user creation patterns to provide increasingly accurate recommendations over time.

Behavioral Patterns Tracked:

• Recent Creation History: Organizations used for recent object creation within specific spatial hierarchies
• Workflow Continuity: Tendency to continue working within the same organizational context
• Spatial-Organizational Associations: User’s patterns of organization selection per spatial location

3. Organizational Presence Analysis

The system analyzes which organizations currently have objects within the spatial hierarchy to understand the organizational landscape of each space.

Analysis Components:

• Active Organizations: Organizations that currently own objects in the spatial hierarchy
• Organization Density: Relative presence of each organization within the space
• Hierarchical Distribution: How organizations are distributed across different levels of the spatial hierarchy

Algorithm Priority Logic

The recommendation algorithm applies a three-tier priority system to determine the most appropriate organization for new object creation:

Priority 1: Last Created by User in Spatial Hierarchy

Weight: Highest (90% confidence when recent) Rationale: Users typically continue working within the same organizational context during active workflows Implementation: Track user’s most recent object creation within the current spatial hierarchy (up to root level)

Examples:

• User creates “Hammer” in workshop owned by “PersonalTools” org → Next tool creation defaults to “PersonalTools”
• User creates “Meeting Notes” in office drawer owned by “CompanyA” → Next document creation defaults to “CompanyA”

Priority 2: Organizations with Objects in Current Hierarchy

Weight: Medium (70% confidence) Rationale: Organizations already present in a space are contextually relevant for new objects Implementation: Query all organizations that own objects within the current spatial hierarchy, ranked by object count and recency

Examples:

• Creating object in shared office space → Prioritize companies that already have objects in this office
• Creating object in family kitchen → Prioritize family members who already have objects in kitchen

Priority 3: User’s Other Organizations

Weight: Low (40% confidence) Rationale: Fallback to user’s available organizations when no contextual information is available Implementation: Return user’s organizations ordered by recent usage frequency

Examples:

• User in completely new space → Default to most recently used organization
• No objects exist in current hierarchy → Use user’s primary organization

Container Pattern and Ownership Aggregates

Implicit vs. Explicit Ownership

A core challenge is tracking ownership of bulk items without creating millions of database entries (e.g., for individual cans of soda on a pallet). The system handles this through a “container pattern” that relies on a distinction between implicit and explicit ownership.

• Implicit Ownership: When an entity owns a container (ObjectInstance), they implicitly own all the components defined in that container’s ObjectClass, even if those components do not exist as ObjectInstances in the database.
• Explicit Ownership: When a component is separated from the container to be sold or transferred, a new ObjectInstance is created for it. Its ownership is then explicitly and individually tracked.

Example Flow: A Pallet of Soda

This scenario illustrates how ownership is tracked from the factory to the consumer.

1. Define Classes: The manufacturer defines :ObjectClass nodes for each level:
   • (:ObjectClass {name: 'SodaCanClass'})
   • (:ObjectClass {name: 'BoxOfSodaClass'})
   • (:ObjectClass {name: 'PalletOfSodaClass'})
   • These classes would also contain component requirements, specifying how many of each subclass they contain.
2. Factory Production: The factory produces a pallet.
   • A single :ObjectInstance node is created. It has an owner property set to "Factory:SodaCorp" and an -[:INSTANCE_OF]-> relationship to the PalletOfSodaClass node.
   • At this stage, only one instance node exists in the database. The factory implicitly owns all 2,400 cans.
3. Sale to Store: The pallet is sold to a retailer.
   • This is a simple transaction: the owner of Instance/Pallet-001 is updated to "Store:SuperMart".
   • The database still only contains the single pallet instance. The store now implicitly owns all cans.
4. Customer Purchase (The “Split”): A customer buys one box of soda.
   • Instantiation-on-Demand: The moment the box is sold, a new :ObjectInstance node is created. Its owner is set to "Customer:Bob" and it has an -[:INSTANCE_OF]-> relationship to the BoxOfSodaClass node.
   • Container Update: A new relationship is created to track the component’s origin: (:ObjectInstance {name: 'Box-ABC'})-[:REMOVED_FROM]->(:ObjectInstance {name: 'Pallet-001'}). This maintains an accurate inventory log.

Resolving Ownership of a Single Can

How do we know who owns a specific can without a database entry for it?

• Scenario A: A can from Bob’s box is scanned.
  1. The system reads the can’s unique identifier.
  2. The point-of-sale system likely first created a :PlingsIdentifier that :IDENTIFIES the :ObjectInstance for the box.
  3. The system can determine that the can’s identifier belongs to the set of identifiers associated with the box instance owned by "Customer:Bob". Conclusion: Bob owns the can.
• Scenario B: A can still on the pallet in the store is scanned.
  1. The system reads the can’s identifier.
  2. It queries the graph for a :PlingsIdentifier node with that value and finds nothing.
  3. Using the identifier’s cryptographic data, the system knows it’s an instance of SodaCanClass from SodaCorp.
  4. Given the context (e.g., scan location), the system can query for :ObjectInstance nodes owned by “SuperMart” that are :INSTANCE_OF PalletOfSodaClass. It finds the pallet instance. Conclusion: The store owns the can.

Real-World Use Cases

Home Environment Scenario

Spatial Hierarchy: Property Lot → House → Kitchen → Drawer Organizations: 6 total

• Individual orgs: Dad, Mom, Teen1, Teen2, Child
• Family org: FamilyShared

Scenario: Dad creates “Measuring Spoons” in kitchen drawer Algorithm Logic:

1. Check Priority 1: Dad’s last creation in house hierarchy was “Coffee Grinder” (FamilyShared org) → Recommend FamilyShared
2. Check Priority 2: Kitchen has objects from FamilyShared (80%), Mom (15%), Dad (5%) → Confirm FamilyShared recommendation
3. Result: Default to FamilyShared with 90% confidence, show Dad and Mom as alternatives

Work Environment Scenario

Spatial Hierarchy: Office Building → Floor 3 → Desk Area → Drawer Organizations: 5 companies sharing space

• TechStartupA, TechStartupB, ConsultingFirm, LawFirm, SharedServices

Scenario: User creates “USB Cable” in desk drawer Algorithm Logic:

1. Check Priority 1: User’s last creation in building was “Laptop Stand” (TechStartupA) → Recommend TechStartupA
2. Check Priority 2: Floor 3 has objects from TechStartupA (60%), TechStartupB (25%), SharedServices (15%) → Confirm TechStartupA
3. Result: Default to TechStartupA with 85% confidence, show TechStartupB and SharedServices as alternatives

Warehouse Environment Scenario

Spatial Hierarchy: Warehouse → Zone A → Rack 15 → Shelf 3 Organizations: 3 companies using shared warehouse

• LogisticsCorp, ManufacturingInc, DistributionLLC

Scenario: User creates “Inventory Scanner” on shelf Algorithm Logic:

1. Check Priority 1: User’s last creation in warehouse was “Shipping Label” (LogisticsCorp) → Recommend LogisticsCorp
2. Check Priority 2: Zone A predominantly contains LogisticsCorp objects (90%) → Confirm LogisticsCorp
3. Result: Default to LogisticsCorp with 95% confidence, minimal alternatives shown

Implementation Requirements

Backend Intelligence Components

1. Spatial Hierarchy Analysis Service

class SpatialHierarchyAnalyzer:
    def get_hierarchy_to_root(object_id: str) -> List[ObjectInstance]
    def find_organizations_in_hierarchy(hierarchy: List[ObjectInstance]) -> Dict[str, OrganizationPresence]
    def calculate_organization_presence_score(org_id: str, hierarchy: List[ObjectInstance]) -> float

2. User Creation History Tracker

class UserCreationTracker:
    def track_creation_event(user_id: str, object_id: str, organization_id: str, spatial_root_id: str)
    def get_recent_creations_in_hierarchy(user_id: str, spatial_root_id: str, limit: int = 10) -> List[CreationEvent]
    def get_most_recent_organization_in_hierarchy(user_id: str, spatial_root_id: str) -> Optional[str]

3. Organization Recommendation Engine

class OrganizationRecommendationEngine:
    def get_recommendation(user_id: str, spatial_context_id: str) -> OrganizationRecommendation
    def calculate_confidence_score(recommendation_factors: RecommendationFactors) -> float
    def generate_alternatives(primary_recommendation: str, available_orgs: List[str]) -> List[AlternativeRecommendation]

Database Schema Requirements

New Tables

-- User creation history per spatial hierarchy
CREATE TABLE user_creation_history (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES auth.users(id),
    object_id UUID REFERENCES object_instances(id),
    organization_id UUID REFERENCES organizations(id),
    spatial_root_id UUID REFERENCES object_instances(id),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    
    INDEX idx_user_spatial_root (user_id, spatial_root_id, created_at DESC),
    INDEX idx_spatial_root_org (spatial_root_id, organization_id)
);

-- Organization presence cache per spatial hierarchy
CREATE TABLE organization_hierarchy_presence (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    spatial_root_id UUID REFERENCES object_instances(id),
    organization_id UUID REFERENCES organizations(id),
    object_count INTEGER DEFAULT 0,
    presence_score DECIMAL(5,4) DEFAULT 0.0000,
    last_updated TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    
    UNIQUE(spatial_root_id, organization_id),
    INDEX idx_spatial_root_presence (spatial_root_id, presence_score DESC)
);

Trigger Functions

-- Auto-update creation history when objects are created
CREATE OR REPLACE FUNCTION track_object_creation()
RETURNS TRIGGER AS $$
BEGIN
    -- Find spatial root for the new object
    -- Insert creation history record
    -- Update organization presence cache
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

GraphQL API Design

Primary Query

type Query {
  getRecommendedOrganization(spatialContextId: ID!): OrganizationRecommendation!
}

type OrganizationRecommendation {
  primaryRecommendation: RecommendationResult!
  alternatives: [RecommendationResult!]!
  spatialAnalysis: SpatialHierarchyAnalysis!
  userBehaviorAnalysis: UserBehaviorAnalysis!
}

type RecommendationResult {
  organization: Organization!
  confidence: Float!
  reason: RecommendationReason!
  explanation: String!
}

enum RecommendationReason {
  LAST_CREATED_IN_HIERARCHY
  USER_OBJECTS_IN_HIERARCHY  
  ORGANIZATION_PRESENCE_IN_HIERARCHY
  USER_PRIMARY_ORGANIZATION
  FALLBACK_FIRST_AVAILABLE
}

type SpatialHierarchyAnalysis {
  currentContainer: ObjectInstance!
  hierarchyPath: [ObjectInstance!]!
  spatialRoot: ObjectInstance!
  organizationsPresent: [OrganizationPresence!]!
}

type OrganizationPresence {
  organization: Organization!
  objectCount: Int!
  presenceScore: Float!
  recentActivity: Boolean!
}

type UserBehaviorAnalysis {
  recentCreationsInHierarchy: [CreationEvent!]!
  lastOrganizationUsed: Organization
  creationPatterns: [CreationPattern!]!
}

type CreationEvent {
  object: ObjectInstance!
  organization: Organization!
  createdAt: DateTime!
  spatialLocation: ObjectInstance!
}

Supporting Mutations

type Mutation {
  trackCreationEvent(
    objectId: ID!,
    organizationId: ID!,
    spatialContextId: ID!
  ): Boolean!
  
  updateOrganizationPreference(
    spatialRootId: ID!,
    preferredOrganizationId: ID!
  ): Boolean!
}

User Experience Benefits

Seamless Workflow Integration

Reduced Cognitive Load: Users no longer need to remember which organization they were using or manually select from long lists during active workflows.

Context Preservation: The system maintains organizational context across object creation sessions, supporting natural workflow continuity.

Intelligent Interruption Recovery: When users return to a workspace after interruption, the system remembers their organizational context.

Transparent Intelligence

Clear Explanations: Users see why an organization was recommended with explanations like:

• “Same as your last 3 objects created in this workshop”
• “Most common organization in this office space”
• “Your primary organization (no recent activity detected)”

Easy Override: Users can easily select alternative organizations when the recommendation doesn’t match their intent.

Learning Feedback: System improves recommendations based on user acceptance/rejection patterns.

Adaptive Behavior

Spatial Learning: System learns organizational patterns specific to different spaces and adjusts recommendations accordingly.

Temporal Adaptation: Recent activity weighs more heavily than historical patterns, adapting to changing workflows.

Multi-Context Support: Handles users who work across multiple organizational contexts without confusion.

Technical Architecture

Performance Considerations

Caching Strategy

• Organization Presence Cache: Pre-computed organization presence scores per spatial hierarchy
• User Pattern Cache: Recent creation history cached per user and spatial root
• Recommendation Cache: Cache recommendations for frequently accessed spatial contexts

Query Optimization

• Spatial Hierarchy Indexing: Optimized indexes for parent relationship traversal
• Time-based Partitioning: Partition creation history by time for performance
• Denormalized Presence Data: Pre-computed organization presence scores

Real-time Updates

• Incremental Updates: Update caches incrementally when objects are created/moved
• Background Processing: Process complex analytics in background jobs
• Event-driven Architecture: Use database triggers for immediate cache updates

Scalability Architecture

Horizontal Scaling

• Service Decomposition: Separate recommendation engine from core object services
• Read Replicas: Use read replicas for recommendation queries
• Microservice Pattern: Isolate recommendation logic for independent scaling

Data Volume Handling

• Historical Data Archival: Archive old creation history data while maintaining recent patterns
• Sampling Strategies: Use statistical sampling for large spatial hierarchies
• Lazy Loading: Load recommendation data only when needed

Security and Privacy Considerations

Data Privacy

• User Consent: Ensure users understand that creation patterns are tracked for recommendations
• Data Retention: Implement policies for creation history data retention
• Anonymization Options: Provide options to disable behavior tracking

Access Control

• Organization Visibility: Ensure users only see organizations they have access to
• Spatial Permissions: Respect spatial access permissions in recommendations
• Cross-Organizational Privacy: Prevent leaking information about other users’ organizational affiliations

Audit Trail

• Recommendation Logging: Log recommendation decisions for debugging and improvement
• User Decision Tracking: Track user acceptance/rejection of recommendations
• Performance Monitoring: Monitor recommendation accuracy and system performance

Future Enhancements

Advanced Intelligence

• Machine Learning Integration: Use ML models to improve recommendation accuracy
• Temporal Pattern Recognition: Detect time-based organizational usage patterns
• Cross-User Learning: Learn from similar users’ organizational patterns (with privacy protection)

Enhanced User Experience

• Recommendation Explanations: More detailed explanations of why organizations were recommended
• Smart Organization Switching: Automatic organization switching based on spatial context changes
• Workflow Integration: Integration with task management and project workflows

Enterprise Features

• Policy-Based Recommendations: Support enterprise policies for organization assignment
• Cost Center Integration: Integrate with cost center and budget management systems
• Compliance Reporting: Generate reports on organizational assignment patterns for compliance

Related Documentation

• Spatial Relationships System: Understanding spatial hierarchy traversal
• Spatial Parent-Child Architecture: Parent relationship rules for hierarchy analysis
• API Requirements: GraphQL API coordination and implementation tracking
• Object Creation Requirements: Frontend integration requirements for organization selection

Implementation Status

✅ Foundation Components

• Organization data model and GraphQL schema
• Basic organization assignment in object creation
• User organization membership queries
• Spatial hierarchy traversal capabilities

🚧 In Development

• Organization recommendation engine design
• API requirements specification
• Backend intelligence system architecture

❌ Planned Implementation

• Spatial hierarchy analysis service
• User creation history tracking
• Organization presence analysis
• Frontend integration with intelligent defaults
• Performance optimization and caching
• User experience enhancements

Migration Strategy

Phase 1: Data Collection (Weeks 1-2)

1. Implement creation history tracking
2. Build organization presence analysis
3. Start collecting user behavior data

Phase 2: Recommendation Engine (Weeks 3-4)

1. Develop recommendation algorithm
2. Implement GraphQL API
3. Create basic recommendation service

Phase 3: Frontend Integration (Weeks 5-6)

1. Update CreateObjectModal with recommendations
2. Add explanation UI components
3. Implement override mechanisms

Phase 4: Optimization (Weeks 7-8)

1. Implement caching strategies
2. Add performance monitoring
3. Refine recommendation accuracy

Phase 5: Advanced Features (Weeks 9-12)

1. Add machine learning components
2. Implement advanced user experience features
3. Add enterprise policy support

This phased approach ensures gradual implementation with immediate value delivery while building toward the full intelligent recommendation system.