Bulk QR Code Generation
Relevant source files
The following files were used as context for generating this wiki page:
- src/server/serverless/bulk-qrcode-generation/index.js
- src/server/serverless/bulk-qrcode-generation/qrCode.js
- src/server/modules/qr/services/QrCodeService.ts
- src/server/modules/bulk/BulkController.ts
- src/server/services/email.ts
- src/server/config.ts
- src/shared/constants.ts
- src/client/user/actions/index.ts
Bulk QR Code Generation is a serverless-driven feature that enables users to generate and download branded QR codes for multiple short links simultaneously. When a user performs a bulk link creation via a CSV upload, the system can trigger an asynchronous process to generate corresponding QR codes in both PNG and SVG formats.
The process involves a specialized Lambda function that renders QR codes with government-branded logos (e.g., GoGovSG, ForEduSG, or ForSG), bundles them into ZIP archives, and uploads them to an S3 bucket for retrieval. Users receive status updates via the web interface and a final notification containing download links via email once generation completes.
Sources: src/server/modules/bulk/BulkController.ts, src/server/serverless/bulk-qrcode-generation/index.js, src/server/services/email.ts
System Architecture and Data Flow
The bulk QR code generation workflow begins in the BulkController when a bulk link creation request is processed. If the ACTIVATE_BULK_QR_CODE_GENERATION environment variable is set to true, the controller passes the URL mappings to a Job Controller to initiate the serverless task.
The diagram shows the transition from user link creation to asynchronous serverless generation and final delivery via S3 and Email.
Sources: src/server/modules/bulk/BulkController.ts:63-75, src/server/serverless/bulk-qrcode-generation/index.js:10-25, src/server/config.ts:251-255
Serverless Generation Logic
The serverless handler processes SQS records containing link mappings and a jobItemId. It performs the following sequential operations:
- CSV Metadata Creation: Generates a
generated.csvfile containing the link mappings and uploads it to S3. - SVG Generation: Renders individual SVG QR codes for each link, zips them, and uploads the archive.
- PNG Generation: Renders individual PNG QR codes (using the
sharplibrary for conversion from SVG), zips them, and uploads the archive. - Cleanup: Removes temporary files from the
/tmpdirectory to manage Lambda disk space. - Reporting: Sends an HTTP message back to the main server to update the job status (success or failure).
Sources: src/server/serverless/bulk-qrcode-generation/index.js:15-62
QR Code Rendering Specifications
The system uses cheerio and qrcode libraries to build branded QR codes. Each QR code is generated as an SVG string and then modified to include branding elements.
| Dimension / Property | Value | Description |
|---|---|---|
IMAGE_WIDTH | 1000 | The base width of the generated image. |
QR_CODE_DIMENSIONS | 800 | The size of the QR square itself. |
MARGIN_VERTICAL | 85 | Top and bottom margins. |
FONT_SIZE | 32px | Size for the URL text printed at the bottom. |
Error Correction | 'H' | High error correction level to allow for the central logo. |
Sources: src/server/serverless/bulk-qrcode-generation/qrCode.js:10-15, src/server/modules/qr/services/QrCodeService.ts:16-20
Branding Logic
The rendering engine selects logos and colors based on the ASSET_VARIANT environment variable.
- gov: Uses
#384A51for the QR code and theqrlogo-gov.svglogo. - edu: Uses
#2B2E4A(or#000000in TypeScript implementation) and theqrlogo-edu.svglogo. - health: Uses
#472F40(or#000000in TypeScript implementation) and theqrlogo-health.svglogo.
Sources: src/server/serverless/bulk-qrcode-generation/qrCode.js:33-43, src/server/modules/qr/services/QrCodeService.ts:22-28
User Notification and Retrieval
The MailerNode service handles communication with the user upon job completion. It generates an email containing direct S3 download links for the PNG and SVG zip files.
Sequence of events leading to user notification after successful bulk generation.
Sources: src/server/services/email.ts:153-178, src/shared/constants.ts:14-23
Download Mapping
The system uses standard filenames for the generated artifacts stored in S3.
| Format | Filename |
|---|---|
| CSV | generated.csv |
| PNG ZIP | generated_png.zip |
| SVG ZIP | generated_svg.zip |
Sources: src/shared/constants.ts:20-23
Configuration Options
Bulk QR code generation behavior is controlled by several environment variables defined in the server configuration.
| Variable | Type | Default | Description |
|---|---|---|---|
ACTIVATE_BULK_QR_CODE_GENERATION | Boolean | false | Enables/disables the entire generation workflow. |
BULK_QR_CODE_BATCH_SIZE | Number | 1000 | Maximum number of codes processed in one batch. |
BULK_QR_CODE_BUCKET_URL | String | "" | The base URL where generated files are hosted. |
SQS_BULK_QRCODE_GENERATE_START_URL | String | "" | The SQS queue URL used to trigger the Lambda. |
JOB_POLL_INTERVAL | Number | 5000 | MS between polling attempts for job status. |
Sources: src/server/config.ts:248-255
Conclusion
The Bulk QR Code Generation system provides a robust, scalable way to generate branded assets for large volumes of links. By offloading the computationally intensive rendering and zipping tasks to AWS Lambda, the main application server remains responsive. The integration with S3 for storage and SES/Postman for notification ensures that users can reliably access their generated assets even for maximum-sized bulk uploads of 1000 links.