System Overview

Created: Thu Jul 10 21:47:22 CEST 2025
Last Updated: Wed 06 May 2026 17:14:18 CEST - Phase 1 of naming migration: renamed frontend repo concept (Plings-Web → Plings-Web), added native iOS/Android apps to architecture, reframed Solana commerce as future vision, clarified scan transport-agnosticism (QR / NFC / RFID)
Architecture Version: 4.0 - Multi-UI, One Backend
Document Version: 1.4 - Native-app and naming updates
Security Classification: Public Technical Documentation
Target Audience: Developers, System Architects, Business Stakeholders
Author: Paul Wisén

Platform Goals & Principles

Plings is a Universal Object Graph System that gives every physical object a verifiable digital identity, traceable relationships, and a place in a shared global graph. The platform combines a deterministic identification scheme (BIP32 HD wallet paths) with a dual-database backend and a transport-agnostic scan layer, producing infrastructure that is useful today for object identification and lifecycle management — and ready, when we choose, to carry on-chain commerce in the future.

Core Problem Solved

Traditional object tracking: Identifiers (barcodes, asset tags, serial numbers) point at databases siloed per organisation. There is no portable identity, no cryptographic verification, and no shared graph of relationships across owners and use-cases. Plings approach: A global graph in which every physical object has a deterministic, verifiable identifier. Identifiers derive from BIP32 HD wallet paths, giving Plings a future-proof identification layer that is cryptographically verifiable today and that can carry on-chain commerce when (and if) we choose to build it.

Design Principles

1. Verifiable Identity for Every Object

• Each object has a deterministic identifier derived from a BIP32 HD wallet path
• Manufacturer signatures provide cryptographic proof of origin (offline-verifiable)
• Path delegation lets manufacturers grant specific identifier ranges to subcontractors and plants

2. HD Wallet Infrastructure Foundation

• Critical choice: HD wallets over PKI — chosen for hierarchical delegation, deterministic derivation, and the ability to map paths to Solana Program Derived Addresses (PDAs) when commerce features are eventually built
• Hierarchical paths give us secure delegation of identifier ranges to subcontractors
• The HD wallet identification architecture is active and production-relevant today; do not casually refactor it

3. One Backend, Many UIs — One GraphQL Interface

• The single canonical interface is the GraphQL API at api.plings.io. Every client — web, native, future — talks to it. This is the “one way in”, not the Gateway.
• The Gateway (s.plings.io) is one specific client of the GraphQL API: it serves as the entry point when the user does not have a native app (browser scans, links shared in messaging apps, email, QR codes opened by the camera app, etc.). It looks up the identifier via GraphQL and redirects.
• Native apps (Plings-iOS, Plings-Android — planned) read identifiers locally via Core NFC / android.nfc / camera and call the GraphQL API directly, skipping the Gateway’s redirect roundtrip. This is intentional: native scan UX must be instant.
• Scan transport is abstracted at the URL level: every transport (QR, NFC, RFID) encodes the same s.plings.io URL, and that URL’s parameters are also what native apps parse locally. Switching transport requires no architectural change in either path.

4. Future-Proof Commerce Capability

• HD path → Solana PDA mapping is preserved in the architecture as a future capability
• Direct payments to objects, NFT-based ownership transfer, and on-chain marketplace operations are part of the long-term vision
• Status: design context only — not built in the foreseeable future. New work should not assume Solana commerce is being built now.

Multi-Layer System Architecture

Multi-Service Ecosystem Architecture

The Plings ecosystem operates as an intelligent routing network with specialized services:

Service Specializations:

Core Architecture Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Physical      │    │    Plings        │    │    Solana       │
│   Objects       │◄──►│   Platform       │◄──►│   Blockchain    │
│                 │    │                  │    │                 │
│ • QR/NFC Tags   │    │ • HD Wallet      │    │ • Object PDAs   │
│ • Identifiers   │    │ • Graph Database │    │ • NFT Minting   │
│ • Commerce URLs │    │ • Auth System    │    │ • Payments      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Data Layer - Dual Database Architecture

PostgreSQL (Supabase)

• User authentication and organization management
• HD wallet path registry (collision prevention)
• Object metadata and image storage
• Row Level Security for multi-tenancy

Neo4j (Graph Database)

• Object relationships (spatial, functional, ownership)
• Complex hierarchy navigation (PART_OF, CURRENT_IN chains)
• Graph traversal for advanced queries

Solana Blockchain

• Object ownership via dynamic NFTs
• Payment routing through Program Derived Addresses
• Smart contracts for commerce, rental, insurance
• Global state independent of Plings infrastructure

API Layer - GraphQL with HD Wallet Extensions

Core Object Operations

• createObject → Generates HD wallet path and Solana PDA
• transferOwnership → Updates both Neo4j and Solana NFT
• processPayment → Routes through PDA to appropriate parties

Commerce Integration

• getObjectPricing → Service marketplace discovery
• executeTransaction → Atomic payment + ownership transfer
• validateAuthenticity → Cryptographic manufacturer verification

System Layer Responsibilities

Client Layer - User Interfaces

All clients consume the same api.plings.io GraphQL endpoint — that is the canonical “one way in”. Two distinct entry-point patterns lead there:

• Browser path: external scan → s.plings.io Gateway → identifier resolved via GraphQL → 302 redirect to the right destination (Plings-Web or a future specialized service).
• Native path: scan happens inside the native app (Core NFC, android.nfc, in-app camera). The app parses the identifier locally and calls the GraphQL API directly. The Gateway is bypassed entirely on this path because the speed of NFC interactions is the whole point.

Plings-Web (current)

• Repository concept: Plings-Web · Disk path: Plings-Web/
• URL: https://plings.io
• Technology: React + TypeScript PWA, deployed on Vercel CDN
• Responsibilities:
  • Scan handling (QR / NFC / RFID) when no native app is involved
  • Object lifecycle UI: create, view, edit, transfer
  • Lost & Found flow
  • Organization and ownership management
  • Scan event timeline and history

Plings-iOS (planned)

• Native iOS app, reads NFC via Core NFC and QR via in-app camera
• Calls the GraphQL API directly — does not route through the Gateway
• Stack TBD

Plings-Android (planned)

• Native Android app, reads NFC via android.nfc and QR via in-app camera
• Calls the GraphQL API directly — does not route through the Gateway
• Stack TBD

Note on “one way in”: the unified contract is the GraphQL schema, not a specific HTTP front door. Identifier resolution, scan-event logging, validation, and authorization all happen behind the GraphQL layer regardless of how the client got there. The Gateway is essentially a thin regateway for the browser path.

Gateway Layer - Intelligent Routing & Security

URL: https://s.plings.io
Technology: Edge-deployed routing service with four core functions

The Gateway’s Four Functions:

1. Routing Function - Intelligent Context-Aware Routing
   • Route based on object status (for sale → market.plings.io, for rent → rent.plings.io)
   • User authentication-aware routing (owner scans vs. public scans)
   • A/B testing and experimentation without changing QR codes
   • Service discovery and geographic routing
2. Logger Function - Centralized Analytics & Tracking
   • Universal scan event logging before any redirect
   • GPS location tracking (with consent) for Lost & Found
   • Cross-service analytics independence
   • Privacy-compliant scan pattern analysis
3. Firewall Function - Security & Protection Layer
   • Rate limiting per IP/identifier (100 scans/minute)
   • DDoS protection at edge level
   • Input validation and injection prevention
   • Malicious URL parameter filtering
4. Freedom to Evolve - Future-Proof Architecture
   • Add new services without reprinting physical QR codes
   • Update routing logic globally and instantly
   • Handle service outages with graceful fallbacks
   • Enable new features through routing changes only

Why Not Direct Routing: Physical QR codes are permanent infrastructure. The Gateway layer provides infinite flexibility to evolve services, add features, and adapt user experiences without the cost and complexity of replacing millions of physical identifiers.

Gateway Verification Strategy

The Gateway implements a hybrid verification approach using cached manufacturer public keys for class verification at the edge, reducing backend load by ~70% while maintaining security through API-based instance verification. For detailed implementation, see s.plings.io Implementation Guide.

Backend Layer - Plings-API (Vercel Serverless)

• Repository concept: Plings-API · Disk path: Plings-API/
• URL: https://api.plings.io
• Technology: FastAPI + Python 3.10+ + Ariadne GraphQL, Poetry-managed

Responsibilities:

• GraphQL API: single endpoint for all client data needs (web, native, future services)
• HD Wallet operations: cryptographic verification and key management
• Dual database management: PostgreSQL (Supabase) + Neo4j (Aura) coordination
• Authentication: user management and API security via Supabase
• Business logic: object lifecycle, relationships, ownership

Solana integration (NFT minting, on-chain payment routing) lives in this layer architecturally but is not actively built — see Future-Proof Commerce Capability above.

Data Flow Summary

Object Creation Flow

1. Manufacturer requests HD path allocation
2. Path Registry allocates collision-free path
3. HD Wallet Service generates Solana keypair from path
4. Object metadata stored in PostgreSQL
5. Relationships stored in Neo4j
6. QR code contains path → Solana PDA for payments

Commerce Transaction Flow (future vision — not currently built)

1. Consumer scans object identifier (QR/NFC/RFID)
2. Client resolves path to object data + Solana PDA
3. Payment sent to PDA (manufacturer cannot intercept)
4. Smart contract validates and routes payment
5. NFT ownership transferred atomically
6. Neo4j relationships updated for new owner

Authentication Flow

1. Scan reveals HD path and manufacturer signature
2. Cryptographic verification proves manufacturer origin
3. Path validation confirms authentic Plings identifier
4. Offline verification possible without network
5. Online enhances with full object history

Economic Architecture (Future Vision)

The sections below describe the long-term economic model. They are not currently built and should not drive near-term implementation decisions. They are kept here as design context so that today’s architectural choices (HD wallet identification, PDA reservation) remain compatible with the future direction.

Revenue Model Transformation

Traditional: Platform fees on transactions Plings: Payment infrastructure replacement - becomes the global commerce backbone

Transaction Fee Structure

• Solana network fee: $0.00025 per transaction
• Plings service fee: Competitive with credit card processing (2-3%)
• Manufacturer royalties: Automatic distribution on resales
• Service commissions: Rent, repair, insurance marketplace fees

Global Scale Potential

• Current credit card volume: ~$4 trillion annually
• Plings addressable market: All physical object commerce
• Firedancer upgrade: 600K TPS (10x Visa capacity)

API Architecture & Developer Integration

GraphQL API Endpoint

Production URL: https://api.plings.io/graphql
Technology: Ariadne GraphQL over FastAPI
Documentation: Interactive GraphiQL explorer available at endpoint

Key API Capabilities

• Object Operations: Create, query, update object instances and classes
• Relationship Management: Spatial, functional, and ownership relationships
• Authentication: JWT-based user sessions with Supabase integration
• HD Wallet Integration: Cryptographic verification and key operations
• Blockchain Operations: Solana transaction management and NFT operations

Example GraphQL Queries

# Query object by identifier
query GetObject($identifier: String!) {
  objectByIdentifier(identifier: $identifier) {
    id
    name
    objectClass {
      name
      description
    }
    spatialLocation {
      name
      path
    }
    owner {
      username
    }
  }
}

# Create new object instance
mutation CreateObject($input: CreateObjectInput!) {
  createObject(input: $input) {
    id
    plingsPath
    solanaAddress
    verificationKey
  }
}

For New Developers

Multi-Service Architecture Understanding:

1. Gateway-First Routing: All QR scans enter through s.plings.io Gateway layer
2. Service-Specific Frontends: Objects route to specialized services based on status/context
3. Unified Backend API: All services consume the same api.plings.io/graphql endpoint
4. Shared Authentication: .plings.io domain cookies enable seamless service transitions

Backend Strategy Understanding:

1. Single GraphQL Endpoint: All frontend data needs served through api.plings.io/graphql
2. Dual Database Coordination: Business logic in Python coordinates PostgreSQL + Neo4j
3. HD Wallet Security: Cryptographic operations handled server-side with multi-tier key management
4. Blockchain Integration: Solana operations abstracted through GraphQL mutations
5. Multi-Tenant Security: Supabase RLS ensures data isolation between organizations

Development Flow with Gateway:

1. QR Scan Flow: QR codes → Gateway verification → Service routing → GraphQL API
2. Frontend Development: Each service queries GraphQL API for specialized data needs
3. Backend Development: Implement business logic in FastAPI resolvers (shared across services)
4. Database Operations: Use PostgreSQL for security/metadata, Neo4j for relationships
5. Gateway Integration: Services receive enriched parameters from Gateway routing

Deployment Topology

Multi-Service Deployment Strategy

Service Distribution (current and planned):

• Plings-Web (disk: Plings-Web/) → Vercel CDN at plings.io — current
• Plings-Gateway (disk: Plings-Gateway/) → Vercel Edge at s.plings.io — current
• Plings-API (disk: Plings-API/) → Vercel Serverless at api.plings.io — current
• Plings-iOS → App Store distribution — planned
• Plings-Android → Play Store distribution — planned
• Marketplace / Rentals / Lending / Business specialized frontends → future, to be built when those use-cases are activated

Gateway Parameter Enrichment:

// Gateway transforms scanned URLs into enriched service URLs
// Input:  https://s.plings.io?t=q&i=ABC123&p=4.2.3.3.6
// Output: https://market.plings.io/item?oid=obj-123&ikey=ABC123&path=4.2.3.3.6&src=scan

Database Infrastructure

• Supabase PostgreSQL (managed, global) - User auth, object metadata
• Neo4j Aura (managed graph database) - Relationship traversal
• Solana validators (decentralized blockchain) - Object ownership & payments

Authentication & Session Management

• Shared Domain Cookies: .plings.io enables seamless service transitions
• Single Sign-On: Login once, access all specialized services
• Session Persistence: Gateway preserves user context during routing

Development Coordination

• Cross-Repository Features: Claude Code coordinates full-stack features across services
• Unified Backend: All services share the same GraphQL API at api.plings.io
• Consistent Authentication: Shared auth system across all domains
• Centralized Documentation: Unified docs at https://docs.plings.io

Security & Compliance Posture

Cryptographic Security

• HD wallet master key in Hardware Security Modules (HSM)
• BIP32 standard compliance for interoperability
• Ed25519 signatures for Solana blockchain compatibility
• Program Derived Addresses prevent payment interception

Financial Compliance

• Payment routing through regulated Solana programs
• Audit trails on immutable blockchain ledger
• Anti-money laundering integration with service providers
• Tax reporting APIs for transaction transparency

Data Protection

• Row Level Security in PostgreSQL for multi-tenancy
• GraphQL authentication for API access control
• Minimal data storage (only objects using Plings services)
• GDPR compliance with right to be forgotten

Competitive Moat (Future Vision)

Strategic positioning for the long-term commerce vision. Not actively pursued in current development.

Technical Moat

1. HD Wallet Innovation: First system to use HD paths as Solana addresses
2. PDA Security Model: Solves payment interception while preserving manufacturer control
3. Dual Database Architecture: Leverages strengths of relational + graph databases
4. Offline + Online Hybrid: Works without network, enhanced with connectivity

Economic Moat

1. Network Effects: Every object strengthens ecosystem
2. Infrastructure Lock-in: Replaces traditional payment systems
3. Global Scale: Same system works for any price point
4. First Mover Advantage: Establishing object commerce standards

Strategic Positioning

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

This system overview emphasizes the revolutionary nature of enabling direct financial transactions to objects through HD wallet architecture. For detailed technical specifications, see Plings Identifier Specification.