What Happens During a Scan

Overview

When someone scans a QrioTag QR code, here is what happens in under 500 milliseconds:

1. Phone camera reads QR code
2. Browser opens the scan URL
3. Web app calls the API
4. API decrypts the tag ID
5. API looks up the tag and profile
6. API records the scan
7. API triggers alerts (if LOST/STOLEN)
8. API returns profile data
9. Web app renders the scan page
10. Finder can contact owner

Step 1: Phone Camera Reads the QR Code

The user points their phone camera at a QrioTag QR code. Modern phones (iOS and Android) have built-in QR code readers in the camera app — no special app is needed.

The QR code encodes a URL in this format:

https://qriotag.to/scan/aGVsbG8gd29ybGQgdGhpcyBpcyBhIHRlc3Q...

The URL consists of:

• Base URL: https://qriotag.to — a short domain optimized for QR codes
• Path: /scan/ — identifies this as a scan request
• Encrypted ID: aGVsbG8gd29ybGQ... — the AES-256-GCM encrypted tag ID

Step 2: Browser Opens the Scan URL

The phone opens the URL in the default browser. This loads the QrioTag web app (apps/web), which is a Next.js application.

The web app's scan page (/scan/[encryptedId]) renders a loading state while it fetches data from the API.

Step 3: Web App Calls the API

Step 4: API Decrypts the Tag ID

The API receives the encrypted ID and decrypts it using AES-256-GCM.

Encrypted: aGVsbG8gd29ybGQgdGhpcyBpcyBhIHRlc3Q...
Decrypted: tag_uuid_123

The encryption uses:

• Algorithm: AES-256-GCM (authenticated encryption)
• Key: TAG_ENCRYPTION_KEY from environment variables
• HMAC verification: TAG_HMAC_SECRET for additional integrity checking

If decryption fails (wrong key, tampered data, or invalid format), the API returns:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Tag not found"
  }
}

Step 5: API Looks Up the Tag and Profile

Using the decrypted tag ID, the API queries the database:

1. Tag lookup: Find the tag record — status, type, owner, creation date
2. Profile lookup: Find the associated profile — name, description, photos, custom fields
3. Visibility check: Determine what information to return based on the profile's visibility setting

The four visibility levels control what scanners can see:

Step 6: API Records the Scan

Every scan creates a Scan record in the database:

{
  "id": "scan_uuid_1",
  "tagId": "tag_uuid_123",
  "ipAddress": "203.0.113.42",
  "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X)...",
  "scanMethod": "QR",
  "latitude": 45.5152,
  "longitude": -122.6784,
  "city": "Portland",
  "country": "US",
  "createdAt": "2026-04-08T14:30:00.000Z"
}

This data is used for:

• Scan history: The tag owner can see when and where their tag was scanned
• Analytics: Location heat maps, scan frequency, device types
• Clone detection: Detecting suspicious scan patterns
• Lost item recovery: Showing the owner where their item was last scanned

Step 7: API Triggers Alerts (if LOST or STOLEN)

If the tag's status is LOST or STOLEN, additional steps happen:

For LOST tags:

1. A ScanAlert record is created with priority HIGH
2. A push notification is sent to the owner: "Your tag [name] was just scanned!"
3. An email is sent to the owner with the scan location and time
4. If the tag has a reward, the reward information is included in the notification

For STOLEN tags:

1. A ScanAlert record is created with priority CRITICAL
2. A push notification is sent to the owner: "STOLEN ALERT: Your tag [name] was just scanned!"
3. An email is sent with scan location, time, and the police report number
4. The scan page shows a prominent stolen alert to the scanner

Step 8: API Returns Profile Data

Step 9: Web App Renders the Scan Page

The Next.js web app receives the API response and renders the scan page. The page design depends on the tag type and status:

Normal scan (ACTIVE tag)

• Tag type icon and name
• Profile information (photo, details, custom fields)
• "Contact Owner" button
• "Share Location" toggle

Lost tag scan

• Everything above, plus:
• Prominent "LOST" banner in red
• Owner's message
• Reward amount (if offered)
• Urgency indicators

Stolen tag scan

• Prominent "STOLEN VEHICLE" alert
• Vehicle details (make, model, year, color, license plate)
• Police report reference number
• Instructions to contact police
• "Report Sighting" button

Emergency scan (medical ID)

• Emergency-optimized layout (large text, high contrast)
• Blood type, allergies, conditions, medications
• Emergency contacts with click-to-call buttons
• No profile photo or personal details (EMERGENCY_ONLY visibility)

Step 10: Finder Contacts Owner

If the finder taps "Contact Owner," a new message thread is created:

Rate Limiting

The scan endpoint is rate-limited to prevent abuse:

Scan Methods

QrioTag supports three scan methods:

The scan method is recorded with each scan for analytics purposes.