← Back to Main Documentation Core Systems Index

Scan Event System

Created: Sön 20 Jul 2025 22:48:12 CEST
Document Version: 1.0 - Initial Scan Event System Specification
Security Classification: Internal Technical Documentation
Target Audience: Backend Developers, Mobile App Developers, Product Managers, UX Designers
Author: Paul Wisén

Overview

The Scan Event System is the central orchestrator for all identifier scanning interactions in Plings. Every time a PlingsIdentifier is scanned—whether through a QR code URL, NFC tap, or within the Plings app—a ScanEvent is created that triggers various workflows based on object status, user permissions, and spatial context.

Core Concepts

What is a Scan Event?

A ScanEvent is a timestamped record created every time a PlingsIdentifier is scanned, capturing:

  • When: Precise timestamp of the scan
  • Where: GPS coordinates of the scan location
  • Who: The user who performed the scan
  • What: The specific identifier that was scanned
  • Context: Object ownership and status at time of scan

Scan Event Triggers

Universal Scanning: Any identifier can be scanned by anyone through multiple methods:

  • QR Code URL: Direct browser access via https://scan.plings.io/s?...
  • Plings Mobile App: In-app scanner with enhanced functionality
  • NFC Tap: Near-field communication on supported devices
  • Third-party Apps: External apps using Plings SDK

Scan Event Workflows

1. Core Data Collection

Every scan event captures:

{
  "timestamp": "2024-07-20T14:30:00Z",
  "latitude": 59.3293,
  "longitude": 18.0686,
  "scanning_user": "user:abc123",
  "owner_at_time_of_scan": "user:def456",
  "scan_method": "qr_url|app_scanner|nfc_tap",
  "device_info": {
    "user_agent": "...",
    "app_version": "1.2.3"
  }
}

2. Object Status-Based Workflows

Lost/Stolen/Missing Object Detection

When an object with status lost, stolen, or missing is scanned:

  1. Immediate Owner Notification: 
    🚨 ALERT: Your [Object Name] was just scanned!
📍 Location: Stockholm, Sweden
🕐 Time: 2 minutes ago
👤 Scanned by: Anonymous user
   
[View Details] [Contact Scanner] [Mark as Found]
  2. Scanner Experience: 
    ⚠️ FOUND ITEM ALERT
This object has been reported lost by its owner.
   
Would you like to help reunite it with them?
[Contact Owner] [Report Location] [More Info]
  3. System Actions:
    • Send push notification to owner
    • Update object’s last_seen_location and last_seen_at
    • Create audit trail for potential recovery
    • Optionally alert authorities if marked as stolen

Active/Normal Object Scanning

For objects with normal status:

  • Update last_seen_at timestamp
  • Update last_seen_location if GPS available
  • Log scan for analytics and usage patterns
  • Trigger appropriate user interface based on permissions

3. User Permission-Based Workflows

Owner/Editor Access

✅ Welcome back!
[Object Name] - Last seen here 2 hours ago

Quick Actions:
🏠 Update Location    📝 Edit Details
📍 Set as Current     🔄 Move Object
📱 Add to Collection  📊 View History

Public/Visitor Access

ℹ️ [Object Name]
Owned by: [Organization Name]
Description: [Public description]

📍 Location: [Current location if public]
🕐 Last seen: [Timestamp if allowed]

[Contact Owner] [Report Issue]

No Access (Private Object)

🔒 Private Object
This item is not publicly visible.

[Report Found Item] [Contact Support]

4. Spatial Relationship Workflows

Spatial Context Detection

When scanning within the Plings app with spatial awareness:

  1. Nearby Object Detection: 
    📍 Spatial Update Available
   
You're near these objects:
• Kitchen Counter (2m away)
• Refrigerator (3m away)
• Dining Table (5m away)
   
Set current location relationship?
[On Counter] [Next to Fridge] [Custom] [Skip]
  2. Container Context Prompts: 
    🏠 Location Context
   
You're currently in: Kitchen Drawer
Set [Scanned Object] as:
   
✅ IN Kitchen Drawer (current location)
📍 NORMAL_IN Kitchen Drawer (expected location)
[Custom Relationship] [Skip]

Smart Spatial Suggestions

Based on object type and spatial context:

  • Tools → Suggest toolbox or workshop locations
  • Clothing → Suggest closet or dresser locations
  • Kitchen items → Suggest cabinet or counter locations
  • Electronics → Suggest desk or entertainment center locations

5. Lost & Found Workflows

Anonymous Finder Experience

When non-owner scans lost object:

  1. Finder Onboarding: 
    🎯 You found someone's lost item!
   
Help reunite [Object Name] with its owner:
   
📍 Confirm your location
📝 Add optional message
🏆 Earn finder reward points
   
[Help Reunite] [Report Location Only] [Cancel]
  2. Communication Channel: 
    💬 Anonymous Message to Owner
   
"Found your [Object Name] at Starbucks on Main St.
I'll be here for the next hour if you want to collect it."
   
[Send Message] [Share My Contact] [Hand to Staff]

Owner Recovery Flow

When owner receives found notification:

  1. Recovery Coordination: 
    🎉 Great news! Someone found your [Object Name]
   
📍 Last known location: Starbucks, Main St
🕐 Found: 15 minutes ago
💬 Finder says: "I'll be here for an hour"
   
[Contact Finder] [Navigate There] [Arrange Pickup]
  2. Verification Process: 
    🔐 Verify Ownership
   
To confirm you're the rightful owner:
• Scan the secondary/hidden identifier, or
• Answer security question, or
• Provide purchase details
   
[Verify Ownership] [Get Help]

6. Analytics and Intelligence

Usage Pattern Analysis

System learns from scan events:

  • Frequency patterns: How often objects are scanned
  • Location patterns: Where objects typically appear
  • User behavior: Scanning habits and workflows
  • Misplacement detection: Objects appearing in unexpected locations

Predictive Insights

Based on scan history:

  • Maintenance reminders: “This tool hasn’t been scanned in 3 months”
  • Location recommendations: “This type of object is usually stored in…”
  • Security alerts: “Unusual scanning pattern detected”
  • Inventory optimization: “These items are frequently accessed together”

Technical Implementation

Scan Event Database Schema

Neo4j Node: :ScanEvent

CREATE (scan:ScanEvent {
  timestamp: datetime(),
  latitude: 59.3293,
  longitude: 18.0686,
  scanning_user: "user:abc123",
  owner_at_time_of_scan: "user:def456",
  scan_method: "qr_url",
  session_id: "session:xyz789"
})

// Relationships
CREATE (scan)-[:SCANNED]->(identifier:PlingsIdentifier)
CREATE (scan)-[:SCAN_BY]->(user:User)
CREATE (scan)-[:SCAN_LOCATION]->(location:Location)

GraphQL API Design

type ScanEvent {
  id: ID!
  timestamp: DateTime!
  latitude: Float
  longitude: Float
  scanningUser: User!
  ownerAtTimeOfScan: User
  scanMethod: ScanMethod!
  scannedIdentifier: PlingsIdentifier!
  triggeredWorkflows: [WorkflowExecution!]!
}

enum ScanMethod {
  QR_URL
  APP_SCANNER
  NFC_TAP
  SDK_INTEGRATION
}

type Mutation {
  createScanEvent(input: ScanEventInput!): ScanEventResult!
  updateObjectLocationFromScan(
    objectId: ID!,
    scanEventId: ID!,
    relationshipType: SpatialRelationshipType,
    targetObjectId: ID
  ): SpatialUpdateResult!
}

type Query {
  scanHistory(objectId: ID!, limit: Int = 50): [ScanEvent!]!
  recentScansNearLocation(
    latitude: Float!,
    longitude: Float!,
    radiusKm: Float = 1.0
  ): [ScanEvent!]!
}

Workflow Engine Integration

Configurable workflow triggers:

class ScanEventProcessor:
    def process_scan(self, scan_event: ScanEvent) -> WorkflowResults:
        workflows = []
        
        # Status-based workflows
        if object.has_status(['lost', 'stolen', 'missing']):
            workflows.append(NotifyOwnerWorkflow(scan_event))
            workflows.append(FoundItemWorkflow(scan_event))
        
        # Permission-based workflows  
        if user.can_edit(object):
            workflows.append(OwnerScanWorkflow(scan_event))
        else:
            workflows.append(PublicScanWorkflow(scan_event))
        
        # Spatial context workflows
        if scan_event.has_spatial_context():
            workflows.append(SpatialUpdateWorkflow(scan_event))
        
        # Always execute
        workflows.append(AnalyticsWorkflow(scan_event))
        workflows.append(LastSeenUpdateWorkflow(scan_event))
        
        return self.execute_workflows(workflows)

Security and Privacy

Privacy Protection

Configurable visibility levels:

  • Private objects: Only show “Private Object” message to non-owners
  • Public objects: Show full details to anyone
  • Organization objects: Show details to organization members only

Location privacy:

  • Object owners control whether GPS locations are stored
  • Scan locations can be anonymized for public objects
  • Precise locations only visible to owners and authorized users

Security Considerations

Anti-abuse measures:

  • Rate limiting on scan events per IP/device
  • Spam detection for repeated scans
  • Malicious scanner identification and blocking

Data protection:

  • Scan event data encrypted at rest
  • GPS coordinates hashed for analytics while preserving location privacy
  • User consent required for location tracking

User Experience Guidelines

Progressive Disclosure

Scan experience optimized by context:

  1. First-time scanner: Simple introduction to Plings system
  2. Return scanner: Quick access to relevant actions
  3. Object owner: Full management interface
  4. Anonymous finder: Guided lost & found workflow

Mobile-First Design

Optimized for smartphone scanning:

  • Large touch targets for spatial relationship selection
  • Quick action buttons for common workflows
  • Offline capability for core scanning functions
  • GPS integration for location-based features

Accessibility

Inclusive scanning experience:

  • Screen reader support for all scan workflows
  • High contrast mode for QR code scanning
  • Voice commands for hands-free operation
  • Alternative text for all visual indicators

Integration Points

External Integrations

Third-party services:

  • Push notification services: Owner alerts for lost items
  • SMS/Email services: Communication with anonymous finders
  • Maps and geocoding: Location context and navigation
  • Analytics platforms: Usage pattern analysis

Future Enhancements

Advanced Workflows

Planned scan event features:

  • AI-powered misplacement detection: Machine learning to identify unusual scan patterns
  • Predictive lost item recovery: Proactive notifications when items might be lost
  • Social recovery networks: Community-based finding and returning systems
  • IoT integration: Automatic scanning via smart environments

Enterprise Features

Business and organizational scanning:

  • Asset tracking integration: ERP and inventory system connections
  • Compliance reporting: Audit trails for regulated industries
  • Batch scanning workflows: High-volume scanning operations
  • Custom workflow engines: Organization-specific scan responses

This document describes the comprehensive scan event system that powers object tracking, lost & found workflows, and spatial intelligence in Plings.

Implementation Status

✅ Currently Available

  • Basic scan event creation and storage
  • Simple owner notification for lost items
  • GPS location capture and storage
  • User permission-based access control

🚧 In Development

  • Advanced spatial relationship prompts
  • Anonymous finder communication workflows
  • Comprehensive analytics dashboard
  • Mobile app scan optimization

❌ Planned Features

  • AI-powered misplacement detection
  • Predictive lost item recovery
  • Social recovery networks
  • Enterprise workflow customization

For technical implementation details, see Neo4j Core Schema and Tag Scanning Integration.