Data Flow
Relevant source files
The following files were used as context for generating this wiki page:
The QR-Tool is a client-side application built with React. Its data flow is unidirectional and reactive, centered around the main App component. User inputs trigger state updates, which are then validated, processed into a QR-compatible string, and finally rendered as a visual QR code (Canvas or SVG). All processing occurs within the user's browser, with no backend server involvement.
The core of the data flow involves managing user-provided data for various QR code types, handling UI customization options, generating the final QR content string, and passing the necessary properties to the rendering library. This flow ensures that the QR code preview updates in real-time as the user modifies any input or setting.
Overall Data Flow Architecture
The application's data flow can be visualized as a pipeline starting from user interaction and ending with a downloadable QR code image. State is managed within the App.jsx component, with helper functions from qr-helpers.js providing logic for validation, content generation, and exporting.
This diagram shows the high-level data flow from user input to the final rendered QR code.
Sources: src/App.jsx, src/utils/qr-helpers.js
User Input and State Management
All application state, including user data and UI settings, is managed within the App.jsx component using React hooks. The useLocalStorage custom hook is employed to persist user preferences across sessions.
Sources: src/App.jsx:250-257
Primary State Objects
| State Variable | Hook | Purpose | Source File |
|---|---|---|---|
qrType | useLocalStorage | Stores the currently selected QR code type (e.g., 'url', 'wifi'). | src/App.jsx:291 |
qrData | React.useState | An object holding all data fields for all QR types. | src/App.jsx:292-313 |
size, eccMode, fgColor, bgColor, etc. | useLocalStorage | Store UI customization options like size, ECC level, and colors. | src/App.jsx:361-372 |
validationErrors | React.useState | Stores real-time validation error messages for the UI. | src/App.jsx:317 |
The updateQrData function is a simple utility to update a specific key within the qrData state object.
// src/App.jsx:315
const updateQrData = (k, v) => setQrData((prev) => ({ ...prev, [k]: v }));
This diagram illustrates how user actions update the application state.
Sources: src/App.jsx:315, src/App.jsx:250-264
Input Validation
Input validation occurs automatically whenever the qrType or qrData state changes. A useEffect hook in App.jsx runs a series of checks based on the current qrType and updates the validationErrors state. This provides immediate feedback to the user.
Sources: src/App.jsx:319-340, SECURITY_AUDIT_REPORT.md
The validation logic relies on helper functions from src/utils/qr-helpers.js.
| Function | Description | Source File |
|---|---|---|
isValidURL() | Checks if a string is a valid URL format. | src/utils/qr-helpers.js:33-41 |
isSafeHttpUrl() | Checks if a URL uses http: or https: protocols. | src/utils/qr-helpers.js:91-99 |
isValidEmail() | Validates email format using a regex. | src/utils/qr-helpers.js:47-51 |
isValidPhone() | Validates phone number format. | src/utils/qr-helpers.js:57-61 |
isValidLatLng() | Validates latitude and longitude values. | src/utils/qr-helpers.js:67-75 |
isValidHex() | Validates hex color code format. | src/utils/qr-helpers.js:116-117 |
The behavior of these functions is confirmed by unit tests.
Sources: tests/qr-helpers.test.js:45-86
This diagram shows the validation flow.
Sources: src/App.jsx:319-340
QR Content Generation
Once the input data is collected, it is formatted into a single string that the QR code library can encode. This process is handled by the generateQRContent function, which is memoized with React.useMemo for performance.
Sources: src/App.jsx:62-140, src/App.jsx:342
The function uses a switch statement to handle the specific formatting requirements for each QR code type. This includes escaping special characters for Wi-Fi and vCard data and encoding components for URLs in email and SMS types.
This logic is tested in src/App.test.js.
Sources: src/App.test.js:18-91
This diagram outlines the logic within generateQRContent.
Sources: src/App.jsx:62-140
QR Code Rendering
The generated QR content string, along with numerous customization properties, is passed to the qrcode.react library for rendering. The App component assembles these properties into a qrProps object.
Key Rendering Properties
value: The debounced QR content string fromgenerateQRContent.size: The pixel dimension of the QR code.level: The Error Correction Capability (ECC) level. This is determined by thepickECChelper function, which automatically selects a level based on logo size and color contrast to ensure scannability.fgColor/bgColor: Foreground and background colors.imageSettings: An object defining the logo to be embedded, including its URL, size, and anexcavateflag to clear space for it.
Sources: src/App.jsx:457-473, src/utils/qr-helpers.js:268-275
The QrPreview component is a presentational component that receives the qrProps and conditionally renders either a <QRCodeCanvas> or <QRCodeSVG> component based on the selected format.
Sources: src/components/QrPreview.jsx:12-13, src/components/QrPreview.jsx:40-53
This sequence diagram shows the rendering process.
QR Code Export
The export functionality is encapsulated in the ExportPanel.jsx component. When a user clicks a download button, the handleDownload function is triggered.
The flow is as follows:
- Identify the source element (
<canvas>or<svg>) from theQrPreviewcomponent via refs. - Check if a "Quiet Zone" (margin) is missing. If so, a padding is calculated and the user is warned before proceeding.
- For Canvas (PNG/JPG) export:
- The
buildDataURLhelper is called. - This function creates a temporary canvas, fills the background, draws the QR code image onto it (with padding if needed), and returns a data URL.
- The
- For SVG export:
- The
buildSVGBlobhelper is called. - It clones the SVG element, adds a background
<rect>, and wraps the original content in a<g>element with atranslatetransform to apply padding. - It returns a
Blobof the modified SVG data.
- The
- The
downloadFilehelper creates a temporary<a>tag with the data URL or blob URL and simulates a click to trigger the download.
Sources: src/components/ExportPanel.jsx:15-77, src/utils/qr-helpers.js:154-186, src/utils/qr-helpers.js:193-228
This diagram illustrates the export process for a PNG file.