ScanFlow – Dynamic QR Management & Visitor Journey Analytics

“Turn static physical QR prints into programmable, intelligent entry points.”
Full-Stack SaaS Platform with Edge Redirects & Asynchronous Visitor Telemetry

🚀 Live Application: https://scanflow-pi.vercel.app/
📦 GitHub Repository: https://github.com/amirfaisalz/scanflow

ScanFlow solves the core flaw of physical QR codes: traditional QR codes are permanently linked to a static URL, rendering printed flyers, billboards, packaging, or table tents useless the moment a campaign URL changes, app store targets diverge between iOS and Android, or seasonal operating hours shift.

ScanFlow decouples physical prints from digital destinations through a sub-millisecond HTTP 307 redirect engine, deterministic context-aware routing rules, and asynchronous session-stitched visitor journey tracking.

ScanFlow Multi-Tenant Analytics Dashboard Figure 1: ScanFlow Overview Dashboard with real-time KPI metrics, time-series scan volume telemetry, and live dynamic QR code management.

⚡ System Architecture

ScanFlow is engineered for minimum latency at the edge while asynchronously streaming granular scan telemetry to a PostgreSQL analytical store.

flowchart TD
    subgraph Visitor Experience
        A[📱 Visitor Scans QR Code] -->|GET /r/:code| B[⚡ ScanFlow Redirect Engine]
    end

    subgraph Deterministic Routing Pipeline
        B --> C[Extract Visitor Context\n- Device: Mobile/Desktop/Tablet\n- OS: iOS/Android/macOS/Windows\n- Geo: Country Code\n- Time: Current Time Window]
        C --> D{Evaluate Prioritized Rules}
        D -->|Rule Matched| E1[Target Variant Destination]
        D -->|Fallback / No Match| E2[Default QR Destination]
    end

    subgraph Edge Response & Telemetry Worker
        E1 --> F[HTTP 307 Instant Redirect]
        E2 --> F
        F --> G[🚀 Visitor Arrives at Destination]
        
        B -.->|Non-Blocking Async| H[Telemetry & Session Worker]
        H --> I[Parse User-Agent & Headers]
        H --> J[Issue/Verify 'sf_sid' Cookie]
        I & J --> K[(PostgreSQL Database)]
    end

    subgraph Analytical Dashboard
        K --> L[Real-Time Analytics Engine]
        L --> M[📊 Overview KPI Metrics]
        L --> N[🗺️ Chronological Scan Journey Explorer]
        L --> O[📈 Campaign Attribution & Conversion Funnel]
    end

✨ Key Features & Capabilities

⚡ 1. Dynamic QR Code Engine & High-Res Export

Instant Destination Swapping: Modify destination URLs in real-time without reprinting physical materials.
Full Lifecycle Management: Seamlessly switch QR states between Active, Paused (custom branded maintenance splash), and Archived.
Crisp Multi-Format Export: Client-side and server-side QR rendering supporting SVG vectors and high-resolution raster PNGs (from 512px up to 4K).
Styling & Error Correction: Foreground/background color personalization and configurable Reed-Solomon error correction levels (L, M, Q, H).

Dynamic QR Code Studio Figure 2: Dynamic QR Studio with real-time vector generation, destination swapping, and status toggles.

🎯 2. Smart Conditional Routing Pipeline

Mobile OS Routing: Automatically route iOS visitors to Apple App Store and Android visitors to Google Play from a single universal QR code.
Device Targeting: Differentiate experiences across Mobile, Desktop, and Tablet form factors.
Geo-Location Rules: Forward users to region-specific storefronts or local language landing pages based on country headers.
Time-Based Windows: Route to lunch/dinner menus or daytime/nighttime landing pages based on live operating hours.
Deterministic Priority Engine: Weighted rule evaluation with automatic fallback to default destinations.

ScanFlow Edge Routing Engine & Interactive Simulator Figure 3: Interactive Edge Routing Playground simulating real-time OS, Geo, and Time header evaluation.

🗺️ 3. Visitor Scan Journey Tracker (Standout Feature)

Session Stitching: Groups individual touchpoints into a unified visitor journey using secure, privacy-first sf_sid cookies.
Chronological Timeline: Step-by-step visual audit trail displaying the user’s multi-scan trajectory from initial scan to eventual conversion.
Dwell & Conversion Metrics: Measures time-to-convert, scan frequency, repeat visits, and drop-off behaviors.

ScanFlow Visitor Scan Journey Explorer Figure 4: Visitor Journey Explorer tracing individual scan touchpoints, device telemetry, and conversion outcomes.

📊 4. Campaign Attribution & Marketing ROI

Cross-Asset Grouping: Aggregate multiple physical flyers, billboards, packaging inserts, and table tents under unified marketing campaigns.
Comparative Metrics: Track aggregate scans, unique visitors, total sessions, and conversion rates across active campaigns.
Funnel Analytics: Visualize physical-to-digital conversion funnels with interactive Recharts visualizations.

🛡️ 5. Multi-Tenant Security & 1-Click Recruiter Demo

Better Auth Integration: Multi-tenant session authentication, password hashing, and CSRF protection.
Tenant Boundary Isolation: Database queries strictly scoped to the authenticated tenant.
1-Click Demo Login: Recruiter-friendly demo sign-in on the login page for instant sandbox evaluation.

🛠️ Tech Stack & Engineering Decisions

Layer	Technologies	Purpose
Framework	Next.js 16 (App Router)	Server Components, Route Handlers, Proxy routing
UI & Styling	React 19, Tailwind CSS v4	High-performance dynamic interfaces and design tokens
Primitives	shadcn/ui, Base UI, Radix	Accessible dialogs, drawers, dropdowns, and sheets
Visualizations	Recharts, TanStack Table v9	Interactive area charts, telemetry trends, and data grids
Database	PostgreSQL 15+	Relational store for QRs, routing logic, sessions, and events
ORM	Drizzle ORM & Drizzle Kit	Type-safe schema definitions, relationships, and push migrations
Authentication	Better Auth	Multi-tenant auth, session validation, route guards
Testing	Vitest, Testing Library	Unit, integration, component, and coverage test runners

💻 Live Application & Source Code

🚀 Live Demo: https://scanflow-pi.vercel.app/ (Try the 1-Click Recruiter Demo Login)
🔗 GitHub Repository: https://github.com/amirfaisalz/scanflow