Technical Documentation

Demo ID: demo-2025-004 Version: [1.0.0] Last Updated: 2025-09-05

Architecture Overview

System Architecture

The platform integrates retailer POS systems and a consumer mobile app via the BSV blockchain.

• POS system generates receipt, encodes data into a blockchain transaction, produces a QR code for consumer verification.

• Mobile app scans QR receipt, verifies authenticity against BSV blockchain, stores locally[12].

Technology Stack

• Frontend: Next.js 15, React 19, Tailwind CSS v4 (POS); React Native with Expo (mobile app)

• Backend: Node.js Express server (POS QR generation and blockchain interaction)

• Database: Local storage via AsyncStorage (mobile), NoSQL cache (POS server)

• Infrastructure: Cloud-hosted demo environment with BSV node access

Key Components

1. QR Receipt Generator (POS): Encodes purchase data and transaction hash

2. Mobile QR Receipt Scanner: Decodes, verifies, and caches receipt locally

3. Blockchain Integration Service: Manages receipt minting, stores immutable record

Integration & APIs

External Dependencies

Service	Purpose	Version	Documentation
@bsv/sdk	BSV blockchain handling	Latest	@bsv/sdk
expo-barcode-scanner	QR code scanning	Latest	Expo Barcode Scanner
AsyncStorage	Local storage	Latest	AsyncStorage Docs

API Endpoints

GET  /api/v1/receipts/:id
POST /api/v1/receipts

Implementation Guide

Prerequisites

• Node.js (v18 or later), npm/yarn, Expo CLI (mobile)

• POS server: Express/Node.js setup

• BSV node RPC access or hosted crypto service

Setup Instructions

Clone repository (POS)

git clone https://github.com/bsv-blockchain-demos/digital-receipts-pos
cd digital-receipts-pos
npm install
cd server
node server.js
npm run dev

Clone repository (Mobile)

git clone https://github.com/bsv-blockchain-demos/digital-receipts-mobile
cd digital-receipts-mobile
npm install
npx expo start

Configuration

Key configuration parameters:

• bsv_node_url: [BSV RPC endpoint]

• local_storage_path: [App config]

Testing & Validation

Test Coverage

• Unit Tests: 80% coverage POS, 85% coverage mobile

• Integration Tests: Passed for receipt creation, scanning, and verification

• Performance Tests: QR scan time < 2 sec; blockchain verification < 1 sec

Validation Criteria

• Receipt generates valid QR code

• Receipt is immutable on blockchain

• App caches and displays receipt

Performance & Scalability

Current Metrics

• Response Time: 300ms POS, 200ms mobile

• Throughput: 100 tx/sec POS demo

• Resource Usage: 30% CPU (server), <50MB RAM (mobile)

Scalability Considerations

• Horizontal scaling via containerized server instances

• QR scan UI performance optimization

• BSV transaction batching for peak demand

Maintenance & Support

Monitoring

• Logs: Managed via cloud log aggregation (server)

• Metrics: POS dashboard; Expo performance tracker (mobile)

• Alerts: Webhook alerts for failed QR verifications

Troubleshooting

Issue	Cause	Solution
Invalid QR	Data corruption	User scan retry, regenerate
Blockchain err	Connectivity loss	Fallback to local cache

Resources

• Repository: POS; Mobile

• Business Documentation: Digital Receipts - Business Overview

• Demo Environment: Live demo

• Support Contact: [Lead Blockchain Engineer]

---

For business context and ROI details, see: Digital Receipts - Business Overview