| ← Back to Core Systems | Main Documentation |
s.plings.io Director Service
Created: Tue 29 Jul 2025 06:49:39 CEST
Document Version: 1.0 - Initial documentation
Security Classification: Public Technical Documentation
Target Audience: Frontend Developers, Backend Developers, System Architects
Author: Paul Wisén
Overview
The s.plings.io service acts as the Director Layer in the Plings ecosystem - an intelligent routing service that serves as the universal entry point for all QR code and NFC tag scans. It provides four critical functions: intelligent routing, centralized logging, security firewall, and future-proof evolution capabilities.
Why s.plings.io?
Physical QR codes are permanent infrastructure - once printed on millions of stickers, they cannot be changed. The Director layer provides:
- Intelligent Routing: Route scans to different services based on object status
- Evolution Freedom: Add new services without reprinting QR codes
- Security Layer: Protect main applications from malicious scans
- Analytics Hub: Centralized scan tracking across all services
The Four Core Functions
1. Director 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 QR Code Format
https://s.plings.io?t=<type>&i=<instance>&p=<path>&cp=<class_pointer>
Parameters
| Parameter | Name | Description | Example |
|---|---|---|---|
t |
Type | Tag type identifier | q (QR), n (NFC), r (RFID) |
i |
Instance | Unique instance key | 4kyQCd5tMDjJVWJH... |
p |
Path | HD wallet path | 4.2.3.3.6 |
cp |
Class Pointer | Optional class identifier | 4K7mX9abDcE |
Verification Strategy
The Director implements a hybrid verification approach using cached manufacturer public keys:
- Edge Verification: Class pointers verified using cached public keys
- API Verification: Instance keys verified via backend API
- Performance: ~70% reduction in backend load
- 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 Director:
oid: Object ID (when known)ikey: Original instance keypath: HD wallet pathsrc: 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