← Back to Main Documentation

Core Systems Documentation

This directory contains documentation for the fundamental business logic and domain models that power the Plings platform.

Contents

Object & Classification System

• Class System - Object classification and type management
• Object Status System - Multi-status lifecycle management
• Plings Identifier - QR codes, NFC tags, and object identification
• Scan Event System - Identifier scanning workflows and automation

Identity & Wallet Management

• Wallet Management Architecture - NEW: Multi-wallet system with incident response capabilities
• HSM Integration Guide - UPDATED: Three-tier key management strategy (Vercel → SoftHSM → Hardware HSM)
• Vercel Key Management - NEW: Initial tier implementation with environment variables for immediate deployment
• SoftHSM Migration Guide - NEW: Next level migration from Vercel to SoftHSM with zero-downtime procedures
• Path Registry - Global object identification system for manufacturers
• Producer Delegation Specification - Range-based quantity control for delegated production
• Plings Identifier Overview - Why identifiers work this way
• Wallet Security Model - Comprehensive security framework and threat model
• Key Compromise Procedures - Incident response procedures for key compromise
• Wallet Lifecycle Management - Operational procedures for wallet lifecycle

Relationship Systems

• Spatial Relationships System - Location and containment relationships
• Functional Relationships System - Purpose and usage relationships
• Spatial Parent-Child Architecture - Hierarchical spatial modeling
• Relationship Decision Guide - Choosing the right relationship type

Ownership & Organization

• Ownership Handling - Multi-level ownership rules and permissions
• Organization Ownership Intelligence - Smart ownership recommendations
• Brand Authority Specification - Brand verification and authority management

Advanced Features

• Misplacement Detection System - Automated discrepancy detection
• Set Object Scanning Workflows - Bulk object processing workflows

Overview

The core systems represent the foundational architecture that enables Plings to manage complex object relationships, ownership models, and organizational structures. These systems provide:

Object Model Foundation

• Flexible Classification: Dynamic object types with extensible properties
• Multi-Status Tracking: Objects can have multiple simultaneous statuses
• Identity Management: Unique identification through QR codes, NFC tags, and digital identifiers
• Wallet-First Architecture: Multi-wallet system enabling clean key rotation and incident response

Relationship Architecture

• Spatial Relationships: Physical location and containment modeling
• Functional Relationships: Purpose, usage, and logical connections
• Hierarchical Organization: Nested spatial and organizational structures

Ownership Intelligence

• Multi-Level Ownership: Personal, organizational, and shared ownership models
• Smart Recommendations: AI-driven suggestions based on context and history
• Permission Inheritance: Automatic permission propagation through hierarchies

Automation & Intelligence

• Misplacement Detection: Automatic identification of objects in unexpected locations
• Workflow Optimization: Streamlined processes for common operations
• Context-Aware Suggestions: Intelligent recommendations based on user behavior and spatial context

For Frontend Developers

These core systems provide the business logic that drives frontend features:

1. Object Creation: Use classification system for type selection and property assignment
2. Relationship Management: Implement spatial and functional relationship UIs
3. Status Updates: Support multi-status workflows with validation
4. Ownership Display: Show ownership hierarchies and permission states
5. Smart Suggestions: Integrate AI recommendations into user workflows

For Backend Developers

Core systems require careful implementation of:

1. Data Consistency: Maintain referential integrity across relationship systems
2. Performance Optimization: Efficient queries for complex relationship traversals
3. Business Rules: Enforce ownership, status, and relationship constraints
4. Event Processing: Handle cascading updates when relationships change
5. Intelligence Services: Implement recommendation algorithms and automation

Integration Points

Core systems integrate with:

• GraphQL Schema: Type definitions and relationship resolvers
• Database Layer: Both PostgreSQL (metadata) and Neo4j (relationships)
• Authentication: User context for ownership and permissions
• Spatial Navigation: Location-based queries and hierarchy traversal
• Image Management: Visual identification and content association

Key Architectural Decisions

1. Dual Database Strategy: PostgreSQL for metadata, Neo4j for relationships
2. Event-Driven Updates: Asynchronous processing for complex operations
3. Flexible Type System: Runtime-configurable object classifications
4. Permission Inheritance: Automatic propagation through ownership hierarchies
5. Context-Aware Intelligence: Location and history-based recommendations