QRApp - Secure QR Code Information Sharing Platform

A FastAPI-based application that enables users to create secure QR codes for sharing personal information with controlled access and authorization workflows.

🚀 Features

Core Functionality

• QR Code Generation: Create QR codes containing access tokens to personal information
• Two-Tier Access Control:
  • Basic Access: Shares all user information fields
  • Secure Access: Allows selective sharing of specific information fields
• Password Protection: All access codes are password-protected
• Authorization Workflow: Request-based access system with email notifications
• Credit System: Users consume credits to generate access codes

Security Features

• Authentication: Secure user sessions with expiration
• Two-Factor Authentication: OTP verification via email for login
• Password Reset: Secure password reset with email verification
• Role-Based Permissions: Granular access control system
• Account Verification: Email-based account verification for new users

Communication

• Real-time Notifications: WebSocket-based notification system
• Email Integration: Templated email notifications for various actions
• File Storage: Secure file upload and storage system

🏗️ Architecture

Technology Stack

• Backend Framework: FastAPI with Python 3.13+
• Database: PostgreSQL with SQLModel ORM
• Database Migrations: Alembic
• Authentication: cookie-based sessions
• Email: SMTP with templated emails
• File Storage: Local filesystem storage
• QR Code Generation: Python qrcode library with PIL

Project Structure

qrapp/
├── app/
│   ├── config/          # Environment configuration
│   ├── db/              # Database models and setup
│   │   ├── builders/    # Builder patterns for model creation
│   │   └── models.py    # SQLModel database models
│   ├── route/v1/        # API routes and controllers
│   │   ├── controllers/ # FastAPI route handlers
│   │   ├── providers/   # Business logic layer
│   │   └── dto/         # Data transfer objects
│   ├── security/        # Permission and authorization system
│   ├── services/        # Core services (email, crypto, QR, etc.)
│   └── utils/           # Utility functions and error handling
├── assets/templates/    # Email templates
├── fs/storage/          # File storage directory
├── migrations/          # Alembic database migrations
└── tests/              # Test files

🚀 Getting Started

Prerequisites

• Python 3.13+
• PostgreSQL database
• SMTP email server access

Installation

1. Clone the repository

   git clone <repository-url>
   cd qrapp

2. Install dependencies using Poetry

   poetry install

3. Set up environment variables Create a .env file in the root directory:

   DEBUG=true
   DB_URL=postgresql://username:password@localhost/qrapp
   GOOGLE_APP_PASSWORD=your_email_app_password
   APP_EMAIL_ADDRESS=[email protected]
   FRONTEND_URL=http://localhost:3000
   API_URL=http://localhost:8000
   CURRENT_API_VERSION=v1
   SECURE_ACCESS_GENERATION_CREDIT_COST=10
   BASIC_ACCESS_GENERATION_CREDIT_COST=5

4. Run database migrations

   alembic upgrade head

5. Start the application

   python main.py

The API will be available at http://localhost:8000

📊 Database Schema

Key Models

• User: User accounts with authentication and profile information
• AccessCode: QR code access tokens with password protection
• InfoField: User information fields that can be shared
• Notification: Real-time notifications for users
• FileResource: File storage and management
• LoginSession: User authentication sessions
• Role & Permission: Authorization and access control

🔌 API Endpoints

Authentication

• POST /v1/auth/register - User registration
• POST /v1/auth/login - User login with OTP
• POST /v1/auth/login/verify-otp - OTP verification
• POST /v1/auth/logout - User logout
• GET /v1/auth/verify-account/{token} - Account verification
• POST /v1/auth/password-reset - Password reset request
• POST /v1/auth/password-reset/{ticket_id} - Execute password reset

Access Codes

• GET /v1/access-code/costs - Get generation costs
• POST /v1/access-code - Generate new access code
• GET /v1/access-codes - List user's access codes
• GET /v1/access-codes/accessed - List accessed access codes
• POST /v1/access-code/pwd-set/{token} - Set access code password
• POST /v1/access-code/access - Request access to code
• POST /v1/access-code/grant/{request_id} - Grant access request
• DELETE /v1/access-code/{id} - Delete access code

Information Fields

• POST /v1/infofield - Create information field
• GET /v1/infofields - List user's information fields
• GET /v1/infofields/{id} - Get specific information field
• DELETE /v1/infofield/{id} - Delete information field

User Management

• GET /v1/me - Get current user profile
• PUT /v1/me - Update user profile
• PUT /v1/me/profile-picture - Update profile picture

🔄 Workflow Examples

Creating an Access Code

1. User creates information fields (name, phone, email, etc.)
2. User generates an access code (basic or secure)
3. System creates QR code and sends password setup email
4. User sets password to activate the access code
5. QR code can now be shared with others

Accessing Shared Information

1. Person scans QR code to get access code ID
2. Person enters the access code password
3. System sends authorization request to code owner
4. Code owner approves/denies the request via email link
5. If approved, requester gains access to shared information

🛡️ Security Considerations

• All passwords are hashed using bcrypt
• Session tokens have configurable expiration times
• Email verification required for account activation
• Two-factor authentication for login
• Permission-based access control for all resources
• Secure file storage with access controls

📧 Email Templates

The application includes responsive email templates for:

• Account verification
• OTP codes for login
• Password reset requests
• Access code password setup
• Access request notifications
• Access granted confirmations

🧪 Testing

Run tests using:

# Add your test command here when tests are implemented
pytest

📚 Dependencies

Core Dependencies

• fastapi[standard] - Web framework
• sqlmodel - Database ORM
• alembic - Database migrations
• psycopg2-binary - PostgreSQL adapter
• passlib[bcrypt] - Password hashing
• qrcode[pil] - QR code generation
• websockets - WebSocket support
• slowapi - Rate limiting
• pytz - Timezone handling

🚀 Deployment

For production deployment:

1. Set DEBUG=false in environment variables
2. Configure production database URL
3. Set up proper SMTP server for emails
4. Configure frontend URL correctly
5. Ensure secure session settings
6. Set up proper file storage permissions

📄 License

MIT

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

For support or questions, contact: [email protected]