Architecture overview

Meikipop is built around a multi-threaded architecture that enables real-time OCR and dictionary lookups without blocking the user interface. This page explains the core architectural components and how they work together.

Threading model

Meikipop uses a multi-threaded design where each major component runs in its own daemon thread. All threads share a SharedState object that coordinates communication through thread-safe queues and events.

SharedState class

The SharedState class is the central coordination point for all threads:

class SharedState:
    def __init__(self):
        self.running = True

        # events and queues
        self.screenshot_trigger_event = threading.Event()
        self.ocr_queue = LatestValueQueue()
        self.hit_scan_queue = LatestValueQueue()
        self.lookup_queue = LatestValueQueue()

        # screen lock - used by screen manager and popup
        self.screen_lock = threading.RLock()

Key elements:

running: Global flag to signal all threads to terminate gracefully
screenshot_trigger_event: Signals when a new screenshot should be captured
Queues: Custom LatestValueQueue instances that only keep the most recent value
screen_lock: Prevents the popup from being included in screenshots

LatestValueQueue

A specialized queue that only stores the most recent value:

class LatestValueQueue():
    def __init__(self):
        self._value = None
        self._lock = threading.Lock()
        self._event = threading.Event()

    def put(self, item):
        with self._lock:
            self._value = item
            self._event.set()

    def get(self):
        self._event.wait()
        with self._lock:
            value = self._value
            self._event.clear()
            return value

This ensures that if processing is slow, only the latest data is processed, preventing queue buildup.

Core components

Meikipop consists of six main threaded components that communicate through the shared state:

TrayIcon (non-threaded)

The system tray icon provides user interaction: Features:

Settings dialog access
OCR provider selection
Scan mode toggle (manual/auto)
Scan area selection (region/screens)
Pause/resume functionality
Quit application

Implementation (from src/gui/tray.py:28):

class TrayIcon(QSystemTrayIcon):
    def __init__(self, screen_manager, ocr_processor, popup_window, input_loop, lookup):
        # Initialize with icon and create context menu
        # Provides access to all major components for configuration

Application lifecycle

The main application flow (from src/main.py:44):

Data flow diagram

Here’s how data flows through the system:

InputLoop → screenshot_trigger_event → ScreenManager
    ↓                                        ↓
    ↓                                    ocr_queue
    ↓                                        ↓
    ↓                                  OcrProcessor
    ↓                                        ↓
    ↓                                 hit_scan_queue
    ↓                                        ↓
    └──────→ hit_scan_queue ←──────── HitScanner
                   ↓
              lookup_queue
                   ↓
                Lookup
                   ↓
            (direct method call)
                   ↓
                 Popup

All threads are daemon threads, meaning they will automatically terminate when the main thread exits.

Thread safety

Meikipop uses several strategies to ensure thread safety:

LatestValueQueue: Thread-safe queue implementation with internal locking
screen_lock: RLock prevents popup from being captured in screenshots
_data_lock: Protects popup’s latest data from concurrent access
Daemon threads: All worker threads are marked as daemon to ensure clean shutdown
Atomic operations: Config changes are atomic and use file-based persistence

When modifying the architecture, be careful about race conditions between the popup visibility state and screenshot capture. The screen_lock mechanism is critical for preventing the popup from appearing in OCR results.

Custom OCR Providers

Contributing

Architecture overview

Threading model

SharedState class

LatestValueQueue

Core components

TrayIcon (non-threaded)

Application lifecycle

Data flow diagram

Thread safety

​Threading model

​SharedState class

​LatestValueQueue

​Core components

​TrayIcon (non-threaded)

​Application lifecycle

​Data flow diagram

​Thread safety

Threading model

SharedState class

LatestValueQueue

Core components

TrayIcon (non-threaded)

Application lifecycle

Data flow diagram

Thread safety