📱 QR Code Generator & Tracker

A comprehensive, password-protected QR code generator with click tracking and analytics, built with Streamlit and AWS.

✨ Features

QR Code Generation

• Rounded edges for a modern, soft look (scan-compatible)
• Custom logo overlay in the center of QR codes
• Customizable colors for QR code and background
• Adjustable size and error correction levels
• High-resolution export (PNG format)

Click Tracking & Analytics

• Real-time click tracking via AWS Lambda
• Visitor information capture:
  • IP address (hashed for privacy)
  • Geographic location (country, region, city)
  • Device type (mobile, tablet, desktop)
  • Browser and OS information
  • Referrer URL
  • UTM parameters (source, medium, campaign, etc.)
• Analytics dashboard with charts and metrics
• Historical data with customizable date ranges

Security

• Password protection via Streamlit secrets
• IAM-based access control for AWS resources
• IP address hashing for visitor privacy

🏗️ Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User scans    │────▶│  API Gateway    │────▶│     Lambda      │
│    QR Code      │     │  (HTTP API)     │     │   (Redirect)    │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
                        ┌────────────────────────────────┼────────────────────────────────┐
                        │                                │                                │
                        ▼                                ▼                                ▼
               ┌─────────────────┐              ┌─────────────────┐              ┌─────────────────┐
               │   DynamoDB      │              │   DynamoDB      │              │   Target URL    │
               │  (QR Codes)     │              │   (Clicks)      │              │   (Redirect)    │
               └─────────────────┘              └─────────────────┘              └─────────────────┘
                        ▲                                ▲
                        │                                │
                        └────────────────┬───────────────┘
                                         │
                               ┌─────────────────┐
                               │   Streamlit     │
                               │      App        │
                               └─────────────────┘

📋 Prerequisites

• Python 3.9+
• AWS Account with CLI configured
• AWS CLI v2
• jq (for JSON parsing in shell scripts)

🚀 Quick Start

1. Clone or Download

# Navigate to the project directory
cd qr-tracker

2. Set Up AWS Infrastructure

# Make scripts executable
chmod +x aws/*.sh

# Run the setup script
cd aws
./setup_aws.sh

The script will:

• Create DynamoDB tables for QR codes and clicks
• Create a Lambda function for redirect handling
• Set up API Gateway with HTTP endpoint
• Create IAM roles and policies
• Generate access credentials for the Streamlit app

Save the output! It contains the configuration values you'll need.

3. Configure Streamlit Secrets

# Create secrets directory
mkdir -p .streamlit

# Copy and edit the example secrets file
cp .streamlit/secrets.toml.example .streamlit/secrets.toml

# Edit with your values from the setup script output
nano .streamlit/secrets.toml

4. Install Dependencies

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

5. Run the App

streamlit run app.py

The app will be available at http://localhost:8501

📁 Project Structure

qr-tracker/
├── app.py                      # Main Streamlit application
├── requirements.txt            # Python dependencies
├── README.md                   # This file
├── .streamlit/
│   ├── secrets.toml.example    # Example secrets file
│   └── secrets.toml            # Your secrets (git-ignored)
└── aws/
    ├── lambda_function.py      # Lambda function code
    ├── setup_aws.sh            # AWS infrastructure setup
    ├── teardown_aws.sh         # AWS infrastructure cleanup
    └── update_lambda.sh        # Update Lambda function code

⚙️ Configuration

Secrets File (.streamlit/secrets.toml)

Key	Description	Example
app_password	Password to access the app	"my-secure-password"
aws_region	AWS region	"us-east-1"
aws_access_key_id	AWS access key	"AKIA..."
aws_secret_access_key	AWS secret key	"..."
dynamodb_qr_table	QR codes table name	"qr-tracker-qr-codes"
dynamodb_clicks_table	Clicks table name	"qr-tracker-clicks"
redirect_base_url	API Gateway URL	"https://xxx.execute-api..."

Environment Variables

You can also configure the AWS setup scripts with environment variables:

export AWS_REGION="us-west-2"
export PROJECT_NAME="my-qr-tracker"
./setup_aws.sh

📊 Analytics Data

The following data is captured for each QR code scan:

Field	Description
timestamp	When the scan occurred
ip_hash	Hashed IP for unique visitor counting
country	Visitor's country
region	Visitor's region/state
city	Visitor's city
device_type	mobile, tablet, or desktop
browser	Chrome, Safari, Firefox, etc.
os	Operating system
referrer	Where the visitor came from
utm_*	UTM campaign parameters

🔧 Maintenance

Update Lambda Function

After modifying aws/lambda_function.py:

cd aws
./update_lambda.sh

View Lambda Logs

aws logs tail /aws/lambda/qr-tracker-redirect --follow

Cleanup AWS Resources

cd aws
./teardown_aws.sh

🚀 Deployment Options

Streamlit Cloud

1. Push code to GitHub
2. Connect to Streamlit Cloud
3. Add secrets in the Streamlit Cloud dashboard
4. Deploy!

Docker

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY app.py .
COPY .streamlit .streamlit

EXPOSE 8501

CMD ["streamlit", "run", "app.py", "--server.port=8501"]

AWS EC2/ECS

See the Streamlit deployment documentation for detailed instructions.

🛡️ Security Considerations

1. Never commit secrets: The .streamlit/secrets.toml file should be in .gitignore
2. Use strong passwords: Generate secure passwords for app access
3. Rotate credentials: Periodically rotate AWS access keys
4. Limit IAM permissions: The setup script creates minimal required permissions
5. IP hashing: Visitor IPs are hashed before storage for privacy
6. HTTPS only: API Gateway uses HTTPS by default

🐛 Troubleshooting

"AWS not configured" error

• Ensure .streamlit/secrets.toml exists and has correct values
• Verify AWS credentials are valid: aws sts get-caller-identity

QR codes not tracking clicks

• Check API Gateway is deployed: Look for /prod/r endpoint
• Verify Lambda permissions in AWS Console
• Check CloudWatch logs for Lambda errors

DynamoDB errors

• Ensure tables exist: aws dynamodb list-tables
• Verify IAM permissions include DynamoDB access

Logo not displaying

• Use PNG format with transparent background
• Keep logo size under 25% of QR code
• Use "H" (High) error correction for best results

📄 License

MIT License - feel free to use for personal or commercial projects.

🤝 Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

---

Built with ❤️ using Streamlit and AWS