s.plings.io Gateway Service

Created: Tue 29 Jul 2025 06:49:39 CEST
Updated: Wed 06 May 2026 17:14:18 CEST - Phase 1 naming migration: clarified transport-agnosticism (QR / NFC / RFID treated equally); resolved that the Gateway handles the browser path while native apps call the GraphQL API directly; “one way in” clarified as the GraphQL API, not the Gateway
Document Version: 1.2 - Browser path vs native path clarified
Security Classification: Public Technical Documentation
Target Audience: Frontend Developers, Backend Developers, System Architects
Author: Paul Wisén

Overview

The s.plings.io service is the Plings-Gateway — an intelligent routing service that acts as the entry point for the browser path: any scan where the user does not have (or is not using) a native Plings app. QR codes, NFC tags, and RFID tags all encode the same s.plings.io URL, so the same logic handles every transport on this path. The Gateway provides four critical functions: intelligent routing, centralized logging, security firewall, and future-proof evolution.

Where the Gateway sits

There are two paths from a physical scan to a result:

The unified “one way in” of the Plings system is the GraphQL API at api.plings.io, not the Gateway. The Gateway is one specific client of that API, optimized for the case where there is no native app to do its own resolution.

Transport-Agnosticism (QR · NFC · RFID)

On the browser path, the Gateway treats all scan transports identically. The URL parameter t (see URL Structure) signals which transport the scan came through, but routing decisions are made on object state and user context — not on transport. Switching from a printed QR sticker to an NFC tag requires no change to the Gateway’s routing logic.

The same URL format is also what native apps parse locally before calling the API, so transport abstraction holds across both paths.

Why s.plings.io?

Physical identifiers are permanent infrastructure — once printed on millions of stickers (or embedded in NFC tags), they cannot be changed. The Gateway layer provides:

• Intelligent Routing: route scans to different services based on object status
• Evolution Freedom: add new services without reprinting physical identifiers
• Security Layer: protect downstream services from malicious scans
• Analytics Hub: centralized scan tracking across all destinations

The Four Core Functions

1. Routing Function - Intelligent Context-Aware Routing

Routes scans based on:

• Object Status: FOR_SALE → market.plings.io, FOR_RENT → rent.plings.io
• User Context: Owner scans vs. public scans
• Service Availability: Handle outages with fallback routing
• Geographic Location: Route to nearest service endpoint

2. Logger Function - Centralized Analytics & Tracking

Every scan is logged before any redirect:

• Universal Tracking: All scans logged regardless of destination
• Lost & Found Support: GPS location tracking (with consent)
• Privacy Compliant: Anonymous scan logging options
• Cross-Service Analytics: Independent of destination service

3. Firewall Function - Security & Protection Layer

Protects all services with:

• Rate Limiting: 100 scans/minute per IP
• DDoS Protection: Edge-level protection
• Input Validation: Prevent injection attacks
• Malicious URL Filtering: Block harmful parameters

4. Freedom to Evolve - Future-Proof Architecture

Enables system evolution:

• New Service Addition: Add services without changing QR codes
• A/B Testing: Experiment with different user flows
• Global Updates: Instant routing logic changes
• Graceful Degradation: Handle service outages intelligently

URL Structure

Incoming Scan URL Format

The same URL format is used for all scan transports (QR / NFC / RFID):

https://s.plings.io?t=<type>&i=<instance>&p=<path>&cp=<class_pointer>

Parameters

Verification Strategy

The Gateway implements a hybrid verification approach using cached manufacturer public keys:

1. Edge Verification: Class pointers verified using cached public keys
2. API Verification: Instance keys verified via backend API
3. Performance: ~70% reduction in backend load
4. Security: Maintains cryptographic verification integrity

For detailed verification flow, see Verification Strategy.

Routing Examples

Object for Sale

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

Unknown Generic Tag

Input:  https://s.plings.io?t=q&i=XYZ789&p=1.1.1.1.1
Output: https://plings.io/create?ikey=XYZ789&path=1.1.1.1.1&src=scan

Lost Object

Input:  https://s.plings.io?t=q&i=DEF456&p=2.2.2.2.2
Output: https://plings.io/found?oid=obj-456&ikey=DEF456&path=2.2.2.2.2&src=scan

Integration with Services

All Plings services receive enriched parameters from the Gateway:

• oid: Object ID (when known)
• ikey: Original instance key
• path: HD wallet path
• src: Source tracking (always ‘scan’)
• Additional context parameters as needed

Security Considerations

• Rate Limiting: Per IP, per identifier, per user
• Input Validation: Strict parameter validation
• HTTPS Only: All redirects use secure protocols
• Privacy: GPS data only with explicit consent

Performance Requirements

• Response Time: <100ms at 95th percentile
• Global Availability: Edge deployment in all regions
• Uptime: 99.9% availability target
• Throughput: 10,000 scans/second capacity

Related Documentation

• URL Structure & Parameters
• Verification Strategy
• Routing Logic
• Implementation Guide
• Security Model