jackfield-labeler

Architecture Documentation

Overview

The Jackfield Labeler application is built using a clean Model-View-Controller (MVC) architecture with PyQt6 for the user interface and ReportLab for PDF generation. The application is designed to be maintainable, extensible, and user-friendly, with approximately 3,300 lines of application code and comprehensive test coverage.

Architecture Principles

1. Separation of Concerns

2. Data Flow

User Input → View → Model Update → Signal Emission → View Update → Preview/Export

3. Signal-Driven Architecture

The application uses PyQt6’s signal-slot mechanism for loose coupling between components:

Core Components

Models (jackfield_labeler/models/)

LabelStrip (label_strip.py)

The central data model representing a complete label strip design.

Key Features:

Key Methods:

Validation Rules:

Segments (segment_types.py, segment.py)

Individual label segments with different types and properties.

Segment Types:

Properties:

Factory Pattern:

def create_segment_from_dict(data: Dict[str, Any]) -> Segment:
    """Creates appropriate segment type from dictionary data"""

StripSettings (strip_settings.py)

Configuration model for paper size, margins, rotation, and defaults.

Settings Categories:

Default Values:

Supporting Models

Views (jackfield_labeler/views/)

MainWindow (main_window.py)

The primary application window that coordinates all tabs and provides global functionality.

Responsibilities:

Key Features:

Signal Routing:

# Example signal connections
self.designer_tab.strip_changed.connect(self.preview_tab.update_preview)
self.settings_tab.settings_changed.connect(self.designer_tab.apply_settings)

DesignerTab (designer_tab.py)

The main workspace for creating and editing label strips.

Components:

Key Features:

Table Management:

PreviewTab (preview_tab.py)

Real-time visual preview and PNG export functionality.

Components:

Key Features:

Rendering Pipeline:

# Preview update flow
strip_changed → calculate_scale_factor → render_to_pixmap → update_display

SettingsTab (settings_tab.py)

Global configuration interface for paper, rotation, and default settings.

Setting Groups:

Key Features:

Utils (jackfield_labeler/utils/)

PDFGenerator (pdf_generator.py)

High-quality PDF generation with rotation and positioning.

Key Features:

Technical Implementation:

Positioning Algorithm:

# Center-to-center positioning
center_x = (paper_width - total_width) / 2
center_y = (paper_height - strip_height) / 2

# Apply rotation around center point
canvas.translate(center_x, center_y)
canvas.rotate(rotation_angle)

StripRenderer (strip_renderer.py)

PNG rendering and preview generation engine.

Key Features:

Use Cases:

Rendering Process:

# High-level rendering flow
calculate_dimensions → create_pixmap → setup_painter → render_segments → return_pixmap

ProjectManager (project_manager.py)

Project file management with .jlp format support.

Key Features:

File Format Structure:

{
  "version": "1.0",
  "application": "Jackfield Labeler",
  "label_strip": {
    "height": 6.0,
    "content_cell_width": 12.0,
    "segments": [...],
    "settings": {...}
  },
  "metadata": {
    "created_by": "Jackfield Labeler",
    "file_format_version": "1.0"
  }
}

Validation Features:

Data Flow Architecture

1. User Interaction Flow

User Input (Designer Tab)
    ↓
Control Panel / Segment Table
    ↓
Model Update (LabelStrip)
    ↓
Signal Emission (strip_changed)
    ↓
Preview Update (Preview Tab)
    ↓
Visual Feedback

2. Settings Flow

Settings Tab Input
    ↓
StripSettings Model Update
    ↓
Signal Emission (settings_changed)
    ↓
Designer Tab Update
    ↓
Model Application
    ↓
Preview Refresh

3. Export Flow

Export Request (Menu/Button)
    ↓
Current Model State
    ↓
Generator (PDF/PNG)
    ↓
File Output
    ↓
User Feedback

4. Project Management Flow

Save: Model → Serialization → JSON → File
Load: File → JSON → Validation → Model → UI Update

Design Patterns

1. Model-View-Controller (MVC)

2. Observer Pattern

3. Strategy Pattern

4. Builder Pattern

5. Factory Pattern

6. Command Pattern

Error Handling Strategy

1. Validation Layers

2. Error Recovery

3. Exception Handling

4. Validation Examples

# Model validation
def validate(self) -> list[str]:
    """Returns list of validation errors"""
    errors = []
    if self.height < self.MIN_HEIGHT:
        errors.append(f"Height {self.height}mm is below minimum {self.MIN_HEIGHT}mm")
    return errors

# UI validation
def _validate_input(self, value: str) -> bool:
    """Validates user input with immediate feedback"""
    try:
        float_value = float(value)
        return float_value > 0
    except ValueError:
        return False

Performance Considerations

1. Lazy Loading

2. Caching

3. Signal Optimization

4. Memory Management

Extensibility Points

1. New Segment Types

2. Export Formats

3. Paper Sizes

4. Color Palettes

Testing Strategy

1. Unit Tests

2. Integration Tests

3. UI Tests

4. Test Organization

tests/
├── test_models/           # Model unit tests
├── test_utils/            # Utility unit tests
├── test_integration/      # Integration tests
└── conftest.py           # Shared fixtures

Security Considerations

1. File Handling

2. PDF Generation

3. User Input

Future Architecture Considerations

1. Plugin System

2. Multi-Document Support

3. Cloud Integration

4. Advanced Rendering

5. Performance Enhancements

This architecture provides a solid foundation for the current application while maintaining flexibility for future enhancements. The clean separation of concerns, comprehensive error handling, and extensible design patterns ensure the application can evolve to meet changing requirements while maintaining code quality and user experience.

This site is open source. Improve this page.