Director Service Setup

Created: Tue 29 Jul 2025 09:17:00 CEST
Document Version: 1.0 - Initial setup documentation
Security Classification: Internal Technical Documentation
Target Audience: Backend Developers, DevOps Engineers
Author: Paul Wisén

Overview

This document describes the setup and deployment of the Plings Director service at s.plings.io. The Director is a Vercel Edge Function that serves as the universal entry point for all QR code and NFC tag scans in the Plings ecosystem.

Repository Structure

The Director service is located in the Plings-Director repository:

Plings-Director/
├── api/
│   ├── index.ts        # Main edge function handler
│   └── health.ts       # Health check endpoint
├── lib/
│   ├── router.ts       # Routing logic
│   ├── validators.ts   # Parameter validation
│   ├── manufacturers.ts # Manufacturer registry
│   ├── security.ts     # Security utilities
│   └── rate-limiter.ts # Rate limiting
├── types/
│   └── index.ts        # TypeScript type definitions
├── public/
│   └── index.html      # Static fallback page
├── package.json
├── tsconfig.json
└── vercel.json         # Vercel configuration

Current Implementation Status

✅ Completed Features

Core Functionality
- Parameter extraction (t, i, p, cp)
- Basic routing logic (known vs unknown manufacturers)
- Manufacturer registry with Plings (id=1)
- Health check endpoint at /health
Security Features
- Domain whitelist (only *.plings.io redirects allowed)
- Rate limiting (100 requests/minute per IP)
- Input sanitization (200 char limit, control char removal)
- Error message sanitization (production-safe messages)
Deployment
- Deployed to Vercel at s.plings.io
- Automatic deployments on push to main branch
- Edge runtime for global performance

⏳ Pending Features

Backend Integration
- resolveIdentifier GraphQL mutation
- Cryptographic verification
- Object context retrieval
Operational Features
- Scan event logging
- Upstash Redis for distributed rate limiting
- Comprehensive test suite
- Environment variable configuration

Local Development

Prerequisites

Node.js 18+
npm or yarn
Vercel CLI

Setup

# Clone repository
git clone https://github.com/paulwisen/Plings-Director.git
cd Plings-Director

# Install dependencies
npm install

# Run locally
npm run dev

Testing

# Run tests (when implemented)
npm test

# Type checking
npm run type-check

# Linting
npm run lint

Deployment

Automatic Deployment

The Director automatically deploys to Vercel when changes are pushed to the main branch.

Manual Deployment

# Deploy to production
vercel --prod

# Deploy to preview
vercel

Environment Variables

Required environment variables for production:

PLINGS_API_URL - Backend GraphQL endpoint (default: https://api.plings.io)
DIRECTOR_API_KEY - Authentication key for backend
USE_BACKEND_API - Enable backend integration (set to “true”)
NODE_ENV - Environment (development/production)

Security Configuration

Domain Whitelist

The Director only allows redirects to these domains:

plings.io
*.plings.io (any subdomain)
Specifically: s.plings.io, app.plings.io, market.plings.io, rent.plings.io, api.plings.io

Rate Limiting

Limit: 100 requests per minute per IP address
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Response: 429 Too Many Requests when exceeded

Input Validation

Maximum parameter length: 200 characters
Control characters stripped
SQL/XSS injection prevention through sanitization

API Endpoints

Main Endpoint: `https://s.plings.io/`

Handles QR code redirects with parameters:

t - Type (e.g., “plgs”, “mfr”)
i - Identifier
p or cp - Class pointer (optional)

Example:

https://s.plings.io/?t=plgs&i=plgs_1_12345&cp=abc123

Health Check: `https://s.plings.io/health`

Returns service status:

{
  "status": "healthy",
  "service": "plings-director",
  "timestamp": "2025-07-29T12:00:00Z",
  "version": "0.1.0"
}

Monitoring and Debugging

Vercel Dashboard

View logs: https://vercel.com/paulwisens-projects/plings-director
Monitor performance metrics
Check deployment status

Testing Redirects

# Test known manufacturer
curl -I "https://s.plings.io/?t=plgs&i=plgs_1_12345"
# Should redirect to https://plings.io/?t=plgs&i=plgs_1_12345

# Test unknown manufacturer  
curl -I "https://s.plings.io/?t=plgs&i=plgs_999_12345"
# Should redirect to https://plings.io/info?unknown=true&t=plgs&i=plgs_999_12345

# Test rate limiting
for i in {1..101}; do curl -I "https://s.plings.io/health"; done
# Should return 429 after 100 requests

Future Enhancements

Phase 1: Backend Integration

Implement resolveIdentifier GraphQL mutation in backend
Add Director API key authentication
Enable cryptographic verification

Phase 2: Advanced Features

Distributed rate limiting with Upstash Redis
Scan event logging to database
A/B testing capabilities
Geographic routing

Phase 3: Performance Optimization

Edge caching strategies
CDN integration
Response time optimization

Troubleshooting

Common Issues

Deployment Fails
- Check Vercel logs for build errors
- Ensure all dependencies are in package.json
- Verify TypeScript compilation succeeds
Redirects Not Working
- Verify domain is in whitelist
- Check parameter validation
- Review rate limit status
Rate Limiting Issues
- In-memory store resets on cold starts
- Consider implementing Redis for persistence

Search Results: