🏗️ System Architecture
Four main layers — click any card for more details
Admin Layer
Super Admin & Support Agent panel for managing tags, users, analytics, and system configuration.
Super Admin / Support Agent
Public Layer
QR scan landing, tag activation, and visitor action pages — no login required.
No Authentication Required
User Layer
Activated users manage their profile, view scan logs, configure tag settings, and download PDF eTag.
Activated Users Only
Service Layer
Backend APIs: OTP, PDF generation, SMS, WhatsApp, Callback, and action logging.
API / Backend Services
📊 Tag Status Flow
Every QR tag passes through these statuses
⬜ Available
→
🟡 Assigned
→
🔵 Activated
→
🔴 Blocked
or
⚫ Expired
🔗 QR Tag URL Format
All tags share the same URL pattern — unique code per QR
🌐
https://yourdomain.com/tag/CAR1001
Same pattern for all tag types
👥 User Roles
Super Admin
Full system access — QR generation, user management, settings, billing, and all reports.
Support Agent
Handles support tickets, callback requests, and assists users with tag issues.
Activated User
Person who has activated a QR tag. Can manage profile, settings, and download eTag PDF.
Public Visitor
Person who scans a QR code — can view tag info, send WhatsApp, request callback, or call (masked).
⚡ Tag Activation Flow — 10 Steps
Complete journey from QR scan to successful activation
01QR Scan
→
02Tag Validate
→
03Intro Page
→
04Enter Mobile
→
05OTP Verify
→
06Full Form
→
07Tag Mapping
→
08PDF Generate
→
09Welcome SMS/WA
→
10✅ Success
💡
Each activation is logged with IP address, device type, source, and OTP verification status. A PDF eTag is auto-generated and sent via WhatsApp/SMS at the end.
🎯 Smart Action Buttons
Shown on the public page after a tag is activated — visitor can choose any action
Masked Call
Call owner without revealing real number
WhatsApp Message
Send message to owner on WhatsApp
Callback Request
Owner will call back the visitor
PDF eTag
Download tag info as PDF
Location Share
Share current GPS location with owner
SMS Fallback
Send SMS if WhatsApp not available
Live Support
Connect to support agent for help
🌐 Public Frontend Pages
All pages accessible without login — main visitor-facing interface
ℹ️
All public URLs are under
/public/ or root level. No authentication required. These are the pages a visitor sees after scanning a QR code.Tag Landing Page
First page after QR scan. Checks tag status — shows action buttons if activated, else starts activation.
/tag/{tag_code}
Activation Wizard
Multi-step form: intro → mobile → OTP → full profile form → success.
/public/activate.php
Action Page
Shows smart action buttons for activated tag. Handles WhatsApp, callback, PDF, location, call.
/public/action.php
Callback Request Form
Visitor enters name & number. Request saved to DB and owner gets WhatsApp/SMS notification.
/public/callback.php
Location Share
Captures visitor GPS via browser API and sends coordinates to tag owner via WhatsApp/SMS.
/public/location.php
PDF eTag Download
Generates and serves the tag owner's PDF eTag for download. Logged in action_logs.
/api/generate-pdf.php
🛡️ Admin Panel Modules
All admin pages under /admin/ — requires admin authentication
📋 Tags Management
🏷️ Tags List
View all tags, filter by status/batch, search by code. Bulk actions: block, assign, delete.
/admin/tags/list.php
⚡ Bulk QR Generate
Generate 1–1000 QR codes at once with prefix, batch name. Downloads ZIP of QR images.
/admin/tags/bulk-generate.php
🔗 Assign Tags
Manually assign available tags to users or agents. Set tag type (vehicle, contact, emergency).
/admin/tags/assign.php
👥 User Management
📋 Users List
All activated users with mobile, name, tag code, status. Filter, search, export CSV.
/admin/users/list.php
👁️ User Detail
Full profile, scan logs, action logs, subscription info. Block/unblock user from here.
/admin/users/view.php
💳 Subscriptions
Manage user plans, validity, feature access. Extend or change subscription manually.
/admin/users/subscriptions.php
📊 Analytics & Communications
Analytics Dashboard
Total scans, activations, actions by type. Charts for daily/weekly/monthly trends.
/admin/analytics/
Scan Logs
Every QR scan with device type, IP, GPS coordinates, timestamp. Filterable by tag or date.
/admin/analytics/scan-logs.php
Callback Requests
All pending/contacted/closed callbacks. Assign to agents. Update status after contact.
/admin/communications/callbacks.php
Support Tickets
User-raised issues. Assign to agents, set priority, track resolution. Internal notes supported.
/admin/communications/tickets.php
Settings
SMTP, SMS API, WhatsApp API, Telephony API keys. Site config, OTP expiry, plan limits.
/admin/settings/
👤 User Dashboard Pages
Accessible only to activated users (OTP-based session login)
🔐
Users do not have a password. Login is done via mobile OTP. Session is maintained after OTP verification. All user pages are under
/user/.Dashboard Home
Welcome screen showing tag status, recent scans, quick links to profile and settings.
/user/dashboard.php
Edit Profile
Update name, WhatsApp, vehicle number, emergency contacts, address, and profile photo.
/user/profile.php
Tag Settings
Toggle: Masked Call, WhatsApp, SMS, Callback, Location Share, Live Support on/off.
/user/settings.php
Scan Logs
View all scans of own tag with timestamp, device type, location. See who scanned and when.
/user/scan-logs.php
Action Logs
WhatsApp clicks, PDF downloads, callback requests, calls — all visitor actions in one view.
/user/action-logs.php
PDF eTag
Download or regenerate personal PDF eTag with QR code embedded. Share or print for physical use.
/user/pdf-etag.php
Callback Requests
View incoming callback requests from visitors. Mark as contacted or close after resolution.
/user/callbacks.php
Support Tickets
Raise issues with support team. View ticket status and agent replies.
/user/support.php
🗄️ Database Schema
15 core tables — MySQL. PK = Primary Key, FK = Foreign Key, UK = Unique Key
tags
Core table — every QR code is a row here
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | Primary identifier |
| tag_code UK | VARCHAR(20) | Unique code e.g. CAR1001 |
| status | ENUM | available / assigned / activated / blocked / expired |
| assigned_user_id FK | INT NULL | → users.id |
| tag_type | VARCHAR(30) | vehicle / contact / emergency / visitor |
| batch_name | VARCHAR(50) | Bulk generation batch label |
| qr_image | VARCHAR(255) | Path to QR image file |
| created_at | TIMESTAMP | Auto-set on insert |
users
Activated users — mobile is the unique identifier
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| mobile UK | VARCHAR(15) | Used for OTP login |
| full_name | VARCHAR(100) | |
| whatsapp_number | VARCHAR(15) | Can differ from mobile |
| status | ENUM | active / blocked |
| created_at | TIMESTAMP |
user_profiles
Extended profile + feature toggles per tag
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| user_id FK | INT | → users.id |
| tag_id FK | INT | → tags.id |
| vehicle_number | VARCHAR(20) | For vehicle tags |
| masked_call_enabled | TINYINT(1) | Toggle ON/OFF |
| whatsapp_enabled | TINYINT(1) | Toggle ON/OFF |
| sms_enabled | TINYINT(1) | Toggle ON/OFF |
| callback_enabled | TINYINT(1) | Toggle ON/OFF |
| support_enabled | TINYINT(1) | Toggle ON/OFF |
| location_enabled | TINYINT(1) | Toggle ON/OFF |
activations
One row per activation event
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| tag_id FK | INT | → tags.id |
| user_id FK | INT | → users.id |
| otp_verified | TINYINT(1) | 1 = verified, 0 = skipped |
| ip_address | VARCHAR(45) | IPv4 or IPv6 |
| activation_source | VARCHAR(50) | web / android / ios |
| activated_at | TIMESTAMP |
scan_logs
Every QR scan is recorded here
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| tag_id FK | INT | → tags.id |
| device_type | VARCHAR(30) | mobile / desktop / tablet |
| latitude | DECIMAL(10,7) | GPS coordinate |
| longitude | DECIMAL(10,7) | GPS coordinate |
| ip_address | VARCHAR(45) | |
| scan_time | TIMESTAMP | Auto-set |
action_logs
All visitor actions on activated tags
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| tag_id FK | INT | → tags.id |
| action_type | VARCHAR(50) | whatsapp_click / pdf_download / callback / call / location |
| visitor_mobile | VARCHAR(15) | Optional — if provided by visitor |
| status | VARCHAR(20) | success / failed / pending |
| created_at | TIMESTAMP |
callback_requests
Visitor callback requests awaiting owner response
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| tag_id FK | INT | → tags.id |
| visitor_name | VARCHAR(100) | |
| visitor_mobile | VARCHAR(15) | |
| status | ENUM | new / contacted / closed |
| created_at | TIMESTAMP |
admins
Admin and support agent accounts
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| email UK | VARCHAR(100) | Login email |
| password | VARCHAR(255) | bcrypt hashed |
| role | ENUM | super_admin / support_agent |
| is_active | TINYINT(1) | 1 = active |
plans + subscriptions
Plan definitions and per-user subscription tracking
| Column | Type | Notes |
|---|---|---|
| plans.id PK | INT | |
| plans.name | VARCHAR(50) | Basic / Standard / Premium |
| plans.max_tags | INT | Max tags per user |
| plans.validity_days | INT | 365 / 730 etc. |
| subscriptions.user_id FK | INT | → users.id |
| subscriptions.plan_id FK | INT | → plans.id |
| subscriptions.expires_at | DATE | Expiry date |
| subscriptions.payment_status | ENUM | paid / pending / free |
settings
Global system configuration (key-value store)
| Column | Type | Notes |
|---|---|---|
| id PK | INT AUTO_INCREMENT | |
| setting_key UK | VARCHAR(100) | e.g. smtp_host, sms_api_key |
| setting_value | TEXT | Stored as text, cast in PHP |
| updated_at | TIMESTAMP | Last modified |
🚀 Build Phases
Start with Phase 1 (MVP) — working product in shortest time
P1
Phase 1 — MVP Core
Start here — everything needed for a working system
DB Setup (all 15 tables)
Admin Auth (login/logout)
Bulk QR Generation
Public Tag Routing (/tag/{code})
OTP Send & Verify API
Tag Activation Flow (all 10 steps)
Tag ↔ User Mapping
Smart Action Page
WhatsApp Button
Callback Request Form
PDF eTag Generator
Scan Logger
P2
Phase 2 — User & Analytics
After MVP is working — add user experience & reporting
User Dashboard
Profile Edit
Tag Settings (toggles)
Scan Logs (user view)
Action Logs (user view)
Admin Analytics Dashboard
PDF Advanced Template
Support Tickets System
Admin Callback Manager
P3
Phase 3 — Advanced & Monetization
Premium features — add after core is stable
SMS API Integration
Masked Call API
Plans & Subscriptions
Payment Gateway
Location Share (GPS)
Live Chat / Video Call (optional)
Admin Mobile App (optional)
📁 Folder Structure
Complete project directory layout
📁 /project-root/
├── 📁 admin/
│ ├── 📁 tags/ # list.php, bulk-generate.php, assign.php
│ ├── 📁 users/ # list.php, view.php, subscriptions.php
│ ├── 📁 analytics/ # index.php, scan-logs.php
│ ├── 📁 communications/ # callbacks.php, tickets.php
│ └── 📁 settings/ # index.php (SMTP, SMS, WA API keys)
├── 📁 user/
│ ├── dashboard.php
│ ├── profile.php
│ ├── settings.php # feature toggles
│ ├── scan-logs.php
│ ├── action-logs.php
│ ├── pdf-etag.php
│ ├── callbacks.php
│ └── support.php
├── 📁 public/
│ ├── activate.php # multi-step activation wizard
│ ├── action.php # smart action buttons page
│ ├── callback.php # visitor callback form
│ └── location.php # GPS share page
├── 📁 api/
│ ├── send-otp.php
│ ├── verify-otp.php
│ ├── activate-tag.php
│ ├── save-callback.php
│ ├── save-location.php
│ ├── log-action.php
│ ├── generate-pdf.php
│ └── bulk-generate-tags.php
├── 📁 includes/
│ ├── db.php # DB connection (PDO)
│ ├── config.php # global constants
│ ├── auth.php # session / role checks
│ ├── functions.php # helper functions
│ ├── header.php
│ └── footer.php
├── 📁 assets/ # CSS, JS, images
├── 📁 uploads/
│ ├── 📁 qr/ # generated QR images
│ ├── 📁 pdf/ # generated PDFs
│ └── 📁 users/ # user profile photos
└── tag.php # root: /tag/{code} → routes to public/activate or public/action
├── 📁 admin/
│ ├── 📁 tags/ # list.php, bulk-generate.php, assign.php
│ ├── 📁 users/ # list.php, view.php, subscriptions.php
│ ├── 📁 analytics/ # index.php, scan-logs.php
│ ├── 📁 communications/ # callbacks.php, tickets.php
│ └── 📁 settings/ # index.php (SMTP, SMS, WA API keys)
├── 📁 user/
│ ├── dashboard.php
│ ├── profile.php
│ ├── settings.php # feature toggles
│ ├── scan-logs.php
│ ├── action-logs.php
│ ├── pdf-etag.php
│ ├── callbacks.php
│ └── support.php
├── 📁 public/
│ ├── activate.php # multi-step activation wizard
│ ├── action.php # smart action buttons page
│ ├── callback.php # visitor callback form
│ └── location.php # GPS share page
├── 📁 api/
│ ├── send-otp.php
│ ├── verify-otp.php
│ ├── activate-tag.php
│ ├── save-callback.php
│ ├── save-location.php
│ ├── log-action.php
│ ├── generate-pdf.php
│ └── bulk-generate-tags.php
├── 📁 includes/
│ ├── db.php # DB connection (PDO)
│ ├── config.php # global constants
│ ├── auth.php # session / role checks
│ ├── functions.php # helper functions
│ ├── header.php
│ └── footer.php
├── 📁 assets/ # CSS, JS, images
├── 📁 uploads/
│ ├── 📁 qr/ # generated QR images
│ ├── 📁 pdf/ # generated PDFs
│ └── 📁 users/ # user profile photos
└── tag.php # root: /tag/{code} → routes to public/activate or public/action