← Back to Main Documentation

Architecture Documentation

Updated: Wed 06 May 2026 17:14:18 CEST — Phase 1 naming migration: reframed Overview to lead with current identification layer; moved Solana commerce to “Future Vision” section; updated repository naming (Plings-Web / Plings-API / Plings-Gateway)

This directory contains comprehensive documentation of the Plings system architecture, covering everything from high-level system design to detailed technical implementation decisions.

Contents

System Design

Future Vision: Solana Commerce (not currently built)

Technical Implementation

Security & Guidelines

Migration Documentation

Overview

The Plings architecture combines a deterministic identification scheme (BIP32 HD wallet paths), a dual-database backend, a transport-agnostic scan layer, and a single GraphQL contract serving all clients (web, native — planned). The HD wallet identification layer is current and production-relevant; long-term commerce features (Solana payments, NFT ownership, on-chain marketplace) are future vision preserved in the architecture but not actively built.

Core Architectural Principles

Verifiable Identity for Every Object

HD Wallet Infrastructure Foundation

One Backend, Many UIs — One GraphQL Interface

Multi-Layer System Architecture

Three-Tier Platform Structure

The Plings ecosystem operates as three coordinated layers:

  1. Client Layer — User Interfaces
    • Plings-Web (current): React + TypeScript PWA at https://plings.io, disk path Plings-Web/
    • Plings-iOS (planned): Native iOS app — calls GraphQL API directly
    • Plings-Android (planned): Native Android app — calls GraphQL API directly
  2. Gateway Layer — Browser-side Scan Routing
    • Repository concept: Plings-Gateway · disk path Plings-Gateway/
    • URL: https://s.plings.io
    • Purpose: Universal scan entry point for browser-based scans (QR / NFC / RFID); routes based on object status, user context, and business rules
  3. Backend Layer — Plings-API
    • Repository concept: Plings-API · disk path Plings-API/
    • URL: https://api.plings.io
    • Purpose: GraphQL contract, business logic, dual-database coordination, HD wallet operations
    • API: Single GraphQL endpoint serving every client

Dual Database System

GraphQL API Integration

Future Vision: Solana Commerce (not currently built)

The bullets below describe long-term commerce capabilities that the HD wallet architecture preserves but are not actively being built. Treat as design context, not as features under current development.

Key Innovations (of the current identification layer)

  1. Hierarchical Delegation: HD paths enable secure manufacturer → plant → batch → instance delegation
  2. Offline + Online Verification: HD wallets enable cryptographic verification without network access
  3. Graph + Relational Hybrid: Leverages strengths of both database paradigms
  4. Future-Compatible Identifiers: Same paths deterministically map to Solana PDAs if commerce launches

Security Model: Verification Authority

Fundamental Security Design: Controlled Verification

Critical Architectural Decision: The Plings system uses hardened HD wallet derivation at all levels, which creates an intentional verification authority model where only specific parties can cryptographically verify identifiers.

Who Can Verify What

Verification Authority Hierarchy:

Plings (Master Authority)
├── Authority: Master key at m/44'/501'/1'
├── Can Verify: Everything in ecosystem  
├── Role: Neutral verification service
└── Trust: Ecosystem coordinator

Manufacturers (Brand Authorities)
├── Authority: Brand-level keys (e.g., m/44'/501'/1'/3' for Coca-Cola)
├── Can Verify: Only their own products
├── Role: Brand authenticity experts  
└── Trust: Self-verification for their products

External Clients (No Authority)
├── Authority: None (by design)
├── Can Verify: Nothing independently
├── Role: Verification consumers
└── Trust: Must rely on authorized authorities

Why External Clients Cannot Verify Independently

Hardened Key Requirement:

Example Path: 1.3.1255.C2.5847.90000
HD Derivation: m/44'/501'/1'/3'/1255'/2'/5847'/90000'
               └──────────────────────────────────────┘
                ALL HARDENED - requires private keys

Missing Keys: External clients lack:

Result: Cannot perform cryptographic verification independently.

Trust Network Architecture

Verification Flow Design

graph TD A[User Scans Object] --> B[Client App] B --> C{Network Available?} C -->|Yes| D[Request Verification] C -->|No| E[Show Limited Info] D --> F[Plings API] D --> G[Manufacturer API] F --> H[Cryptographic Verification] G --> I[Brand Verification] H --> J[Return Attestation] I --> J J --> K[Display Verified Result] E --> L[Path Parsing Only] L --> M[Basic Manufacturer Info]

Security Benefits of Authority Model

Controlled Brand Verification:

System Integrity:

Implementation Implications

For Backend Architecture:

For Frontend Architecture:

For Client Applications:

// Correct approach - use verification authorities
async function verifyProduct(path, instanceKey) {
    const verification = await fetch('/api/verify', {
        method: 'POST',
        body: JSON.stringify({ path, instanceKey })
    });
    return verification.json();
}

// ❌ INCORRECT - clients cannot verify independently
function attemptLocalVerification(path, instanceKey) {
    // This cannot work - requires private keys
    return cryptoVerify(path, instanceKey); 
}

Security vs Decentralization Trade-off

Why Centralized Verification Is Intentional

Alternative Considered: Fully decentralized verification where anyone could verify Problem: Would undermine manufacturer brand control and enable verification chaos Solution: Controlled authority model that balances security with manufacturer needs

Benefits of Authority Model:

Threat Model and Mitigations

Potential Attack Vectors

Authority Compromise:

False Verification:

Network Attacks:

Social Engineering:

Defense in Depth

Layer 1: Cryptographic verification by authorities Layer 2: Cross-verification between multiple authorities Layer 3: Audit trails and anomaly detection Layer 4: User education and trust indicators Layer 5: Incident response and key rotation procedures

Development Strategy for New Developers

Understanding Our Backend Architecture

Key Insight: Plings uses a sophisticated multi-layer architecture with clear separation of concerns:

API Strategy

Repository Structure

Development Flow

  1. Plings-Web Development: Query GraphQL API for all data operations
  2. Plings-API Development: Implement business logic in FastAPI GraphQL resolvers
  3. Database Operations: Use PostgreSQL for security/metadata, Neo4j for relationships
  4. Gateway Routing: Update routing rules in Plings-Gateway/lib/router.ts for browser-side scan flows
  5. (Future) Blockchain Integration: Solana operations would be abstracted through GraphQL mutations when commerce features are built

For Frontend Developers

The architecture enables revolutionary commerce features:

  1. Scan-to-Pay: Instant object purchase through QR code scanning
  2. Service Discovery: Find rental, repair, insurance for any object
  3. Real-time Ownership: Live blockchain-based ownership updates
  4. Offline Verification: Authenticate objects without network connectivity
  5. Payment Integration: Seamless Solana wallet integration
  6. GraphQL Integration: Type-safe data fetching with automatic caching

Key Integration Points:

For Backend Developers

Architecture requires careful implementation of:

  1. HD Wallet Security: Multi-tier key management (Vercel → SoftHSM → Hardware HSM)
  2. Dual Database Sync: Maintain consistency between PostgreSQL and Neo4j
  3. Blockchain Integration: Solana program development and PDA management
  4. Payment Routing: Secure transaction flow through smart contracts
  5. Service Orchestration: Marketplace provider coordination
  6. GraphQL Schema: Type-safe API design with Ariadne

Key Implementation Areas:

Integration Points

Architecture integrates with:

Revolutionary Impact

Global Commerce Transformation

Vision: Replace Visa/Mastercard by making every physical object a payment terminal Path: Build through niche use cases → expand to universal commerce infrastructure Timeline: 5-10 years to global payment infrastructure significance

Market Disruption Potential

Status Legend

Detailed Technical Architecture

Core Components Layer Architecture

Layer Function Technologies
Object Metadata Stores basic identity, type, properties PostgreSQL (e.g., Supabase)
Graph Engine Tracks semantic and structural relationships Neo4j Aura
Vector Search Enables semantic matching and similarity search Qdrant
Embedding Generator Transforms text/images into vector space OpenAI / HuggingFace / CLIP
Geospatial Data Handles physical containment and geolocation PostGIS + Graph
External Integrations Data from marketplaces, manufacturers, catalogs API connectors

Architectural Rationale: Why a Dual-Database System?

The Plings architecture intentionally uses a polyglot persistence model, leveraging two different types of databases to handle specific tasks for which they are best suited. This design is a deliberate choice to maximize security, performance, and scalability.

1. Neo4j Aura (The Graph Engine):

2. Supabase - PostgreSQL (The Ownership & Security Engine):

In summary, the system is designed so that Neo4j manages the graph’s complexity, while Supabase manages the users’ security. The unified ID system provides the critical link between these two specialized systems.

Object Model

ObjectClass and ObjectInstance

The UOGS distinguishes between an object’s blueprint (ObjectClass) and its physical manifestation (ObjectInstance). In Neo4j, these are represented as nodes with labels and properties.

ObjectClass (The Template Node): A node with the label :ObjectClass.

{
  "name": "Mountain Bike",
  "description": "A bicycle designed for off-road cycling.",
  "version": 1,
  "owner": "Plings",
  "capabilities": ["off-road", "sport"]
}

ObjectInstance (The Physical Item Node): A node with the label :ObjectInstance.

{
  "owner": "user:123"
}

PlingsIdentifier (The Pointer Node): A node with the label :PlingsIdentifier.

{
    "value": "plg:44-10012-22-7890-Qmx3D",
    "identifier_type": "QR",
    "status": "active"
}

Key Graph Relations

Relationships in Neo4j are first-class citizens, connecting nodes directly with a specific type.

For detailed schema information, see ../database/neo4j-core-schema.md.