EFQRCode Architecture: A Deep Dive into the Modular Swift QR Code Library

EFQRCode implements a four-layer modular architecture that separates QR code data encoding, visual styling, SVG generation, and media rasterization into distinct, interchangeable components.

The EFQRCode architecture is designed around clean separation of concerns, enabling developers to generate everything from simple static codes to complex animated QR codes with custom visual styles. This Swift library, maintained by the efprefix organization, structures its codebase into distinct layers for the public API, generation logic, styling engine, and recognition capabilities.

Core Architectural Layers of EFQRCode

The library organizes functionality into four primary layers, each responsible for a specific phase of the QR code lifecycle.

Public API Layer (EFQRCode Namespace)

The entry point resides in Source/EFQRCode.swift, which exposes the EFQRCode namespace. This file defines the static interface that aggregates the generator and recognizer, providing a unified access point for library consumers while hiding implementation complexity.

Generation Layer (EFQRCode.Generator)

Located in Source/EFQRCode+Generator.swift, the EFQRCode.Generator struct orchestrates the complete generation pipeline. It accepts raw data or QRCode objects from the underlying QRCodeSwift dependency, applies styling configurations, and coordinates rasterization through SwiftDraw. The generator supports multiple output formats including PNG, JPEG, SVG, PDF, and animated media formats (GIF, APNG, MOV, MP4).

Styling Layer (EFQRCodeStyle)

The visual customization system centers on Source/Styles/EFQRCodeStyle.swift, which defines the EFQRCodeStyle enum and the abstract EFQRCodeStyleBase class. This layer implements the Strategy pattern, allowing pluggable rendering algorithms. Concrete implementations such as EFQRCodeStyleBasic, EFQRCodeStyleBubble, and EFQRCodeStyle25D reside in separate files within Source/Styles/, each inheriting from EFQRCodeStyleBase and implementing generateSVG(qrcode:) to produce custom SVG markup.

Recognition Layer (EFQRCode.Recognizer)

The recognition functionality in Source/EFQRCode+Recognizer.swift provides the EFQRCode.Recognizer struct. This component utilizes CoreImage's CIDetector or Vision's VNDetectBarcodesRequest to locate and decode QR codes from input images, returning the extracted string payloads.

Data Flow: From String to Rendered QR Code

The EFQRCode architecture processes generation requests through a five-stage pipeline:

1. Initialization – The user creates an EFQRCode.Generator with a String, Data, or existing QRCode object, optionally specifying an EFQRCodeStyle (defaulting to .basic).

2. QR Code Creation – The generator delegates to QRCodeSwift to create a QRCode instance with the specified error correction level and encoding.

3. SVG Generation – The selected style's implementation (subclass of EFQRCodeStyleBase) receives the QRCode object and calls generateSVG(qrcode:). This method calculates the viewBox, invokes writeQRCode(qrcode:) for module patterns, writeIcon(qrcode:) for center icons, and returns a complete SVG string.

4. Rasterization – For image outputs, the SVG string is parsed by SwiftDraw (SVG(data:)), optionally transformed for edge insets, and rasterized to UIImage or NSImage. The generator also provides direct encoding to PNG or JPEG data.

5. Animation and Video – When animated formats are requested, the generator inspects the SVG for <animate> elements (isAnimated). It creates synchronized frame sequences, assembles them with proper timing delays, and exports to GIF, APNG, or video formats (MOV/MP4) via createAnimatedImageDataWith or createVideoDataWith.

The Styling System: Pluggable Visual Effects

EFQRCode's architecture implements a flexible styling system that separates visual design from data encoding. The system centers on the EFQRCodeStyle enum defined in Source/Styles/EFQRCodeStyle.swift, which enumerates all supported styles including .basic, .bubble, .style25D, .image, .line, and .randomRectangle.

Each enum case encapsulates a parameter struct (e.g., EFStyleBasicParams, EFStyleBubbleParams) that configures appearance specifics such as icon images, colors, and border widths. The enum provides a computed property implementation that returns an instance of the corresponding concrete style class.

Concrete style classes inherit from EFQRCodeStyleBase (defined in the same file, lines 448-525) and implement the rendering contract:

• generateSVG(qrcode:) – Produces the complete SVG document
• writeQRCode(qrcode:) – Renders data modules and position patterns
• writeIcon(qrcode:) – Handles center icon placement and masking
• viewBox(qrcode:) – Calculates coordinate systems respecting quiet zones

This architecture allows developers to add custom visual styles by subclassing EFQRCodeStyleBase and registering the new style in the enum, without modifying the core generation logic in Source/EFQRCode+Generator.swift.

Output Formats and Rasterization

The EFQRCode architecture abstracts output format complexity through a unified rasterization layer powered by SwiftDraw. This design enables the library to support multiple media types from a single SVG-based intermediate representation.

Static Image Generation – The generator can produce platform-native UIImage (iOS) or NSImage (macOS) objects through toImage(), or encoded data via toPNGData() and toJPEGData(). These methods pass the style-generated SVG to SwiftDraw's SVG(data:) parser, which handles path rasterization and color rendering.

Vector and Document Outputs – For scalable graphics, the generator exposes toSVGString() to retrieve the raw SVG markup directly. PDF generation is also supported for document workflows.

Animated Media – The architecture supports GIF, APNG, and video formats (MOV, MP4, M4V) through specialized export methods (toGIFData(), createVideoDataWith). When generating animated content, the system inspects the SVG for <animate> elements or animated icon parameters, creates synchronized frame sequences, and encodes them with proper timing metadata.

Platform Extensions – Convenience extensions in Source/Extension/ (such as UIImage+EFQRCode.swift and String+EFQRCode.swift) provide direct methods on platform types, internally instantiating the generator and delegating to the rasterization pipeline.

EFQRCode Architecture Code Examples

Basic Generation with Default Style

import EFQRCode

do {
    let generator = try EFQRCode.Generator("https://github.com/efprefix/efqrcode")
    let pngData = try generator.toPNGData(width: 300)
    try pngData.write(to: URL(fileURLWithPath: "/tmp/qrcode.png"))
} catch {
    print("Generation failed: \(error)")
}

This example demonstrates the minimal path through the EFQRCode architecture: EFQRCode.Generator → EFQRCodeStyle.basic → SVG generation → SwiftDraw rasterization → PNG encoding.

Custom Styled QR Code with Icon

import EFQRCode
import CoreGraphics

let icon = EFStyleParamIcon(
    image: .static(image: myIconCGImage),
    borderColor: CGColor.createWith(rgb: 0x000000)!,
    percentage: 0.25
)

let params = EFStyleBasicParams(icon: icon)
let style = EFQRCodeStyle.basic(params: params)

let generator = try EFQRCode.Generator("Styled QR", style: style)
let image = try generator.toImage(width: 400)

This implementation leverages EFStyleParamIcon and EFStyleBasicParams to configure the EFQRCodeStyleBasic class, which generates an SVG containing an <image> element for the center icon.

Animated QR Code Generation

import EFQRCode

let animatedIcon = EFStyleParamIcon(
    image: .animated(
        images: [frame1CG, frame2CG, frame3CG],
        imageDelays: [0.2, 0.2, 0.2]
    ),
    borderColor: CGColor.createWith(rgb: 0xffffff)!,
    percentage: 0.2
)

let params = EFStyleBasicParams(icon: animatedIcon)
let style = EFQRCodeStyle.basic(params: params)

let generator = try EFQRCode.Generator("Animated QR", style: style)
let gifData = try generator.toGIFData(width: 300)

The EFQRCode architecture detects animation via isAnimated, creates synchronized frames, and writes the GIF through createAnimatedImageDataWith.

Summary

• EFQRCode implements a four-layer modular architecture separating public API, generation logic, visual styling, and recognition capabilities.
• The Generator (Source/EFQRCode+Generator.swift) orchestrates data encoding through QRCodeSwift, styling through the EFQRCodeStyle system, and rasterization through SwiftDraw.
• The Styling Layer uses an abstract base class (EFQRCodeStyleBase) and concrete implementations to enable pluggable visual effects without modifying core generation code.
• Output flexibility spans static images (PNG, JPEG), vector graphics (SVG, PDF), animated formats (GIF, APNG), and video (MOV, MP4) through a unified rasterization pipeline.
• Recognition is handled by EFQRCode.Recognizer using CoreImage and Vision frameworks, providing symmetrical decode capabilities to the generation pipeline.

Frequently Asked Questions

How does EFQRCode architecture separate QR code generation from visual styling?

EFQRCode achieves separation through the EFQRCodeStyle enum and EFQRCodeStyleBase abstract class defined in Source/Styles/EFQRCodeStyle.swift. The EFQRCode.Generator (Source/EFQRCode+Generator.swift) handles data encoding and orchestration but delegates all visual rendering to style implementations. Concrete style classes inherit from EFQRCodeStyleBase and implement generateSVG(qrcode:), allowing developers to add new visual styles without modifying the core generation logic in the generator file.

What dependencies does EFQRCode use for core QR generation and rasterization?

EFQRCode relies on two primary external dependencies to implement its architecture. QRCodeSwift handles the low-level QR code data encoding, error correction, and masking pattern generation, converting input strings into QRCode objects. SwiftDraw performs SVG parsing and rasterization, converting the vector graphics produced by the styling layer into platform-native bitmaps (UIImage or NSImage) or encoded image data (PNG, JPEG). These dependencies are abstracted behind the generator interface in Source/EFQRCode+Generator.swift.

Can EFQRCode generate animated QR codes, and how does the architecture support this?

Yes, EFQRCode supports animated outputs including GIF, APNG, and video formats (MOV, MP4, M4V). The architecture detects animation potential by inspecting the SVG for <animate> elements or checking for animated icon parameters (isAnimated). When generating animated content, the EFQRCode.Generator creates synchronized frame sequences, assembles them with proper timing delays, and exports via createAnimatedImageDataWith for image formats or createVideoDataWith for video output. This capability is implemented within Source/EFQRCode+Generator.swift without requiring changes to the styling or recognition layers.

How does EFQRCode handle QR code recognition and decoding?

EFQRCode provides recognition capabilities through the EFQRCode.Recognizer struct defined in Source/EFQRCode+Recognizer.swift. The recognizer accepts platform image types (UIImage, NSImage, or CIImage) and utilizes CoreImage's CIDetector with CIDetectorTypeQRCode or Vision's VNDetectBarcodesRequest to locate QR code symbols within the image. It extracts the encoded data from detected symbols and returns the decoded strings, providing a symmetrical counterpart to the generation pipeline within the EFQRCode architecture.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}