← Back to Main Documentation Architecture Index

System Overview

Created: Thu Jul 10 21:47:22 CEST 2025
Last Updated: Mon 28 Jul 2025 11:36:24 CEST - Added frontend/backend separation documentation
Architecture Version: 3.0 - Payment-to-Object Design
Document Version: 1.3 - Added multi-layer architecture explanation
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 transforms physical objects from passive identifiers into autonomous economic endpoints. The platform’s revolutionary breakthrough is enabling direct financial transactions to objects through HD wallet infrastructure and Solana blockchain integration.

Core Problem Solved

Traditional commerce: Objects require separate payment infrastructure (POS systems, card readers, cashiers) Plings innovation: Objects become self-selling commerce endpoints that can receive payments directly

Design Principles

1. Objects as Economic Agents

2. HD Wallet Infrastructure Foundation

3. Infrastructure Elimination

4. Cryptographic Verification + Commerce

Multi-Layer System Architecture

Multi-Service Ecosystem Architecture

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

flowchart TD QR[QR Code Scan] --> DIR[s.plings.io
Director Layer] DIR --> |Object for sale| MARKET[market.plings.io
Marketplace] DIR --> |Object for rent| RENT[rent.plings.io
Rental Platform] DIR --> |Object lendable| LEND[lend.plings.io
Lending Platform] DIR --> |Lost object| MAIN[plings.io
Main App - Lost & Found] DIR --> |Standard scan| MAIN DIR --> |Business tools| BIZ[business.plings.io
Enterprise Tools] DIR --> |Auth required| AUTH[plings.io/login
Authentication] subgraph "Unified Backend" API[api.plings.io
GraphQL API] DB1[(PostgreSQL
Supabase)] DB2[(Neo4j
Graph DB)] BLOCKCHAIN[Solana
Blockchain] end MARKET --> API RENT --> API LEND --> API MAIN --> API BIZ --> API API --> DB1 API --> DB2 API --> BLOCKCHAIN subgraph "Shared Authentication" COOKIES[.plings.io Domain Cookies] end MARKET -.-> COOKIES RENT -.-> COOKIES LEND -.-> COOKIES MAIN -.-> COOKIES BIZ -.-> COOKIES DIR --> ANALYTICS[analytics.plings.io
Usage Analytics]

Service Specializations:

Service Domain Purpose Context Routing
Main App plings.io Core inventory, object creation, Lost & Found Default route, auth required
Director s.plings.io Universal QR entry point, intelligent routing All scans enter here
Marketplace market.plings.io Buy/sell commerce platform Objects with FOR_SALE status
Rentals rent.plings.io Rental marketplace and management Objects with FOR_RENT status
Lending lend.plings.io Peer-to-peer lending platform Objects with LENDABLE status
Business business.plings.io B2B features and enterprise tools Business context routing
Analytics analytics.plings.io Usage insights and scan analytics Data visualization

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)

Neo4j (Graph Database)

Solana Blockchain

API Layer - GraphQL with HD Wallet Extensions

Core Object Operations

Commerce Integration

System Layer Responsibilities

Frontend Layer - User Interface (Vercel)

Repository: Plings-Lovable-Frontend
URL: https://plings.io
Technology: React + TypeScript PWA

Responsibilities:

Director Layer - Intelligent Routing & Security

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

The Director’s Four Functions:

  1. Director 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 Director layer provides infinite flexibility to evolve services, add features, and adapt user experiences without the cost and complexity of replacing millions of physical identifiers.

Director Verification Strategy

The Director 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 - Core Services (Vercel)

Repository: Plings-Backend
URL: https://api.plings.io
Technology: FastAPI + Python + Ariadne GraphQL

Responsibilities:

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

1. Consumer scans object QR code
2. Frontend 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

Revenue Model Transformation

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

Transaction Fee Structure

Global Scale Potential

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

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. Director-First Routing: All QR scans enter through s.plings.io Director 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 Director:

  1. QR Scan Flow: QR codes → Director 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. Director Integration: Services receive enriched parameters from Director routing

Deployment Topology

Multi-Service Deployment Strategy

Service Distribution:

Director Parameter Enrichment:

// Director 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

Authentication & Session Management

Development Coordination

Security & Compliance Posture

Cryptographic Security

Financial Compliance

Data Protection

Competitive Moat

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.