Core Objective
Build an end-to-end identity resolution system that creates deterministic phone number ↔ ADID (mobile device ID) mappings using the IAB UID2 protocol and ad campaign-based matching.
Project Overview
This is a sophisticated identity resolution platform with the following workflow:
Phone Numbers → UID2 Tokens → Ad Campaigns → Impression Tracking → ADID Capture → Bidirectional Mappings
Key System Components:
1. Phone Upload Service
Accepts CSV/JSON/Excel files with phone numbers
Normalizes to E.164 format
Encrypts and hashes for security
Tracks upload batches with validation stats
2. UID2 Conversion Service
Converts phone numbers to UID2 advertising tokens via IAB UID2 protocol
Manages token refresh cycles (90-day expiration)
Stores mappings in PostgreSQL
Async processing via Kafka queue
3. Ad Campaign Manager (Prebid Integration)
Creates low-cost tracking campaigns targeting UID2 tokens
Strategy: 1x1 pixel impressions for cost efficiency
Configurable budget, geography, and frequency caps
Tracks impressions and campaign performance
4. Impression Tracking System
Captures ADIDs from impression events
Extracts device data from OpenRTB bid requests
Supports both GET (pixel) and POST (S2S postback) tracking
Logs user agent and geo data
5. Mapping Service
Creates and updates phone ↔ ADID relationships
Confidence scoring based on impression frequency
Handles multiple ADIDs per phone (multi-device users)
Updates phone processing status
6. Lookup APIs (Bidirectional)
Phone → ADID: Find all ADID(s) associated with a phone number
ADID → Phone: Find phone number associated with ADID
Redis caching for <10ms lookups
Confidence scores and impression counts
7. Web Dashboard (Streamlit)
Real-time system statistics and metrics
Phone upload interface
Campaign creation and monitoring
Interactive lookup tool
Analytics and performance charts
API Endpoints Summary
/api/upload -Upload phone number file
/api/create-campaign/{batch_id} - Create ad campaign from batch
/lookup/phone-to-adid - Find ADID(s) by phone
/lookup/adid-to-phone - Find phone by ADID
/stats/overview - System statistics
/campaigns - List campaigns
/track - Impression tracking pixel
Deliverables
This is a complete, production-ready implementation with:
✅ Full database schema with indexes and partitioning
✅ All microservices implemented (upload, UID2, campaigns, tracking)
✅ Bidirectional lookup APIs with caching
✅ Docker containerization and docker-compose orchestration
✅ Web dashboard with real-time analytics
✅ Comprehensive error handling and logging
✅ Test endpoints and integration test framework
The system is ready for deployment with proper UID2 API credentials and campaign budget allocation.