While that program no doubt sped up the end-of-life for my prized Dell Precision M6500 Covet (google it – I’m still in love), it did push me to finally move to Linux. Being the masochist that I am, I chose Arch. If you’re going to do something, you might as well do it with style – my style being to flail wildly towards the ground while debugging the latest update, without a parachute cord in sight.

Nevertheless, I’d found my forever-OS, and over the years my machines’ setups evolved. After eight years, I finally present to you Na Fir-Chlis: an i3 setup on Arch (or your distro of choice), themed end-to-end in Nord and managed with GNU Stow.

The repo read-me is thorough – install, keybindings, every status block, the lot – so I won’t rehash it here. What follows are a few notes.

Mind Your Own Buffers

You’ll notice almost nothing here themes your editor – nano aside. That’s deliberate. If you spend your day in Vim or an IDE, you already have strong opinions and a config tuned to within an inch of its life, and I’m not about to barge in with a symlink.

However, if you’ve got the one true Vim Nord theme to rule them all, open a PR and we can wire it in as an optional package. Same goes for anything else – fork it, take a piece, send a fix. The door’s open.

Pomodori at Large

The bar ships with a pomodoro timer (supported by an included shell script) – it was something I lived by for many years. When the struggle gets real on a technical problem, I still use it: I’m like a dog with a bone, and without the timer I’d run the risk of ossification. No engineer wants that.

Jesting aside, it’s the cheapest productivity trick I know. Head down for twenty-five minutes followed by a short breather. Having this habit a keybind away makes it easier to maintain flow.

1
2
pomodoro.sh start        # default: 25 minutes
pomodoro.sh start 50     # or set your own

Blank Desktop Space – The Final Frontier

My own desktop usually sits bare – no wallpaper, no icons. Beginning with a metaphorical blank canvas – familiar and exciting – before a coding session suits my inner-artist.

On the other hand, my inner-designer refused to ship “formalised dotfiles” without the final touch.

The included wallpaper is one of my paintings, Escape. Originally a greyscale notan piece, it was redesigned and recoloured into a Nord wallpaper and shipped in a few Polar Night shades. This way a fresh clone opens on something finished rather than my preferred “blank canvas”.

Of course, if none of this is your cup of tea, you can easily change it – there’s a whole collection of Nord wallpapers out there to swap in.

---

That’s the workshop: small, a little stubborn, and held together with symlinks.

If you’d rather see what comes out of a setup like this than how it’s wired, InPromptOut is what I’ve been building lately – a better measure of the work than my choice of window manager.

I enjoy refactoring code after a period of deep learning – it is often when my biggest architectural realisations land. Coming back to MetaMaker, a Python desktop application originally built around file metadata and Darkblock¹ upload workflows for an experimental steganographic art collection of my own paintings, I saw room to refine how its components communicated internally.

MetaMaker used an event-driven MVC architecture. To decouple components and standardise event handling, I introduced Blinker², a lightweight Python library for dispatching signals. This post focuses on how I hardened that signal layer: introducing explicit payload classes, enforcing runtime payload contracts, and adopting a hybrid object + ID pattern to balance responsiveness against reliability.

The main MetaMaker case study covers the wider architecture; this post focuses specifically on how the event layer evolved. Coming from a Java background, the process also helped me settle into a more Pythonic and maintainable approach to event-driven design.

Introducing Event Payloads

Early in the Blinker rollout, signal emissions were simple:

1
set_manager_on_updated.send(self, payload=nft_set)

The trouble was structure. Objects were passed informally, with no defined schema and no type safety. As the system grew, that ambiguity made payloads harder to validate, handlers harder to test, and signal flow harder to trace across components.

To address this, I introduced explicit payload classes using @dataclass³:

1
2
3
4
5
6
7
8
@dataclass
class SetUpdatedEvent:
    nft_set: 'NftMetadataSet'
    set_id: int

def emit_set_updated(sender, nft_set):
    payload = SetUpdatedEvent(nft_set=nft_set, set_id=nft_set.id)
    set_manager_on_updated.send(sender, payload=payload)

Benefit: handlers can access fields predictably (payload.set_id, payload.nft_set.name), and the code becomes easier to read and refactor.

Formalising events this way led me to a broader architectural question: should I really be passing full objects around, and was I violating the “single source of truth” principle by doing so?

The “Single Source of Truth” Principle

Conventionally, data should be re-fetched from the database (the repository) to ensure it is current, especially in multi-threaded⁴ or distributed systems.

In MetaMaker’s case, that convention did not always make sense. When emitting a signal immediately after writing to the database, I already had the “truth” in memory. Forcing handlers to re-query that data introduced latency and redundant work – defeating the responsiveness goals of the UI layer.

The hybrid approach struck a balance:

• IDs preserve the ability to re-fetch the authoritative state when needed.
• Object references allow fast, contextual responses in the UI – without assuming they are immutable or canonical.
• Event classes (like SetUpdatedEvent) formalise this structure, making the trade-off clear and auditable.

The Hybrid Payload Model: Object + ID

By wrapping both the object and its ID in a structured dataclass (e.g. DblockUpdatedEvent), I gained:

• Immediate UI access to object data (payload.nft_set.name)
• Optional DB refresh when needed (darkblockmanager.get_dblock(dblockid=42)⁵)
• Runtime payload contracts for debugging and handler validation
• Cleaner testing, using mock event payloads and signal assertions

This resolved several pain points at once. It preserved the responsiveness of object-based signalling while introducing the structure and reliability needed to scale. With hybrid payloads, handlers can now:

1. Update UI elements immediately from object attributes (payload.nft_set.name)
2. Fetch fresh state only when needed (darkblockmanager.get_dblock(dblockid=42))

Enforcing Runtime Payload Contracts

To guard against accidental signal misuse, I added a decorator that validates payload types when an environment flag is set:

1
2
3
4
5
6
7
8
9
10
11
def enforce_contract(signal_name, expected_type):
    def decorator(func):
        @wraps(func)
        def wrapper(sender, **kwargs):
            if os.getenv("DEBUG_SIGNALS") == "1":
                payload = kwargs.get('payload')
                if not isinstance(payload, expected_type):
                    raise TypeError(f"Signal '{signal_name}' expected {expected_type.__name__}")
            return func(sender, **kwargs)
        return wrapper
    return decorator

This let me catch mistakes safely during development, with no production overhead. To reinforce it, I also temporarily patched Signal.send to flag any legacy manual emissions:

1
2
3
4
5
6
7
8
9
10
11
12
13
def patched_send(self, *args, **kwargs):
    stack = inspect.stack()
    if not any("emit_" in frame.function for frame in stack):
        caller = next((f for f in stack if "emit_" not in f.function), None)
        if caller:
            logger.warning(
                f"[LEGACY SIGNAL USE] Signal '{self.name}' sent manually from: \n"
                f"{caller.filename}:{caller.lineno}; \n Refactor using emitter and dataclass payloads."
            )
    return _original_send(self, *args, **kwargs)

if os.getenv("DEBUG_SIGNALS", "1") == "1":
    Signal.send = patched_send

Testing Strategy

To keep the system reliable, I settled on a consistent testing approach for signals.

Use fake payloads

1
2
3
4
class FakeNftMetadataSet:
    def __init__(self, id):
        self.id = id
        self.name = "Test"

Patch the environment

1
2
3
4
5
6
invalid_payloads = [("string", "invalid"), ("none", None)]
with patch.dict('os.environ', {'DEBUG_SIGNALS': '1'}):
    for case_name, payload in invalid_payloads:
        with self.subTest(case=case_name):
            with self.assertRaises(TypeError):
                handler(None, payload=payload)

This enforces signal contracts during testing, with minimal noise and clear subtest isolation.

Clean up handlers

Handlers persist across tests unless removed:

1
2
3
4
5
def tearDown(self):
    for signal in self.ALL_SIGNALS:
        for receiver in signal.receivers.values():
            signal.disconnect(receiver)
    self.handlers.clear()

Together, these steps made the signal system reliable and testable, even during concurrency-heavy operations.

Looking Back

MetaMaker is now archived as a portfolio project, so I would not continue this migration for its own sake. If I were rebuilding the architecture today, I would either standardise the remaining listener-based paths around Blinker or deliberately keep them separate as a smaller async-result boundary.

The important lesson was not “use Blinker everywhere.” It was that event-driven code needs structure. Named payloads, explicit emit functions, runtime contracts, and predictable cleanup turned a loose signal layer into something easier to test, trace, and refactor.

MetaMaker – Next Steps

For the full picture on this project, read the MetaMaker case study, or browse the code on GitHub.

Or, since you have read this far – a choice:

Case study InPromptOut My latest and most rigorous case study: graph modelling, a performance crisis, a security audit and cost-safety work. See how deep the architecture goes. Explore

Case study PhonixLab A live classroom phonics platform, in daily use across an eleven-school education board. Step into a project running in the real world. Take a look

Let’s Connect

If you are interested in event-driven Python architecture, or want to talk about signal layers, typed payloads, or testing event-driven systems, I’d be glad to hear from you.

Introduction

MetaMaker grew from a simple command-line tool for the Darkblock¹ API into an open-source, cross-platform desktop app for managing file metadata and Darkblock upload workflows, running on Linux, Windows and Mac. Coming from a Java background, I had habits to unlearn – my early code was verbose, reflecting a Java mindset. Embracing Pythonic simplicity, MetaMaker became my proving ground for a modular, maintainable architecture.

This post covers the key decisions: MVC for separation of concerns, Blinker² for event-driven updates, and manual dependency injection³ for flexibility – with code examples and the lessons behind them. For the broader picture, see the MetaMaker case study, or explore concurrency in the Threading Deep Dive.

Quick Navigation

• Choosing MVC for Separation of Concerns
• Building an Event-Driven System with Blinker
• Manual Dependency Injection for Flexibility
• Supporting Persistence with SQLAlchemy
• Lessons Learned and Reflections
• MetaMaker – Next Steps

Choosing MVC for Separation of Concerns

To keep MetaMaker maintainable, I needed a clear architectural pattern. MVC⁴ fit Tkinter’s⁵ legacy style and made feature additions, like supporting alternative upload models, far easier:

• Models: manage data (SQLAlchemy ORM⁶).
• Views: render UI (CustomTkinter⁵).
• Controllers: handle user interactions.

View Layer: Rendering the Gallery

The SetViewMvc class dynamically renders the gallery. Here is a streamlined look at init_gallery_view:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@logger.catch
def init_gallery_view(self, nft_data: List[NftMetadata], lower_range: int, upper_range: int) -> None:
    """Initialize and display the gallery view with NFTs within the specified range."""
    # Validate range and image directory
    if lower_range < 1 or upper_range < lower_range:
        logger.error(f"Invalid range: {lower_range}-{upper_range}")
        raise ValueError(f"Invalid range: {lower_range}-{upper_range}")
    image_dir = self._collection.get_collection_local_path()
    error = global_validator.validate_collection_img_dir(...)
    if error:
        raise ValidationError(error)

    # Sort and select image files
    sorted_files = sorted([...], key=lambda x: int(os.path.splitext(x)[0]))
    selected_files = sorted_files[lower_range - 1:upper_range]
    if len(nft_data) < len(selected_files):
        raise ValueError("Insufficient NFT metadata")

    # Initialize view and populate gallery
    self._transition_view = GalleryView(self)
    self._transition_view.init_view()
    for i, file in enumerate(selected_files):
        self._transition_view.add_item(SetViewGalleryItem(...))
        if i % constants.UI_UPDATE_INTERVAL == 0:
            self.update()

Why this matters: early validation ensures rendering is fast and won’t easily fail. Transition views and pagination reduce UI flicker. See the full code in MetaMaker’s repo.

MetaMaker’s gallery loading, demonstrating dynamic rendering and pagination powered by the SetViewMvc class.

Controller Layer: Navigation

Controllers mediate navigation, such as directing users to the configuration view:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class SetViewControllerMvc(BaseControllerMvc, SetViewObsvProtocol):
    def on_json_preview_selected(self, nft_uid: int):
        self._nav_manager.nm_init_json_view(
            nft_uid,
            self._set_accessor.get_current_set_id(),
            as_top_level=True,
        )

    @override
    def on_item_selected(self, item_id: int, image_path: str):
        self._nav_manager.nm_init_config_nft_view_from_item(
            item_id,
            self._set_accessor.get_current_set_id(),
            image_path
        )

MetaMaker MVC and Blinker architecture: AppController injects dependencies into AppView and the view controllers. Views like SetViewMvc render UI via CustomTkinter, while Blinker signals decouple updates.

Building an Event-Driven System with Blinker

To decouple components, I needed an event-driven system for UI updates – like refreshing after Darkblock transactions⁷. Custom listeners (RepoEvent) caused complexity early on, so I switched to Blinker.

Triggering Signals

Signals are fired from functions, such as associating an NFT with a Darkblock:

1
2
3
4
5
6
7
def associate_nft(self, dblock_id: int, nft_id: int):
    """Associate an NFT with a Darkblock by updating nft_id in database."""
    try:
        db.update_item(orm_obj=Darkblock, item_id=dblock_id, update_data={"nft_id": nft_id})
        self._on_updated_signal.send(self, dblock_id=dblock_id)
    except Exception as error:
        self._handle_update_error(error, dblock_id=dblock_id)

Handling Signals

Views or controllers register handlers:

1
2
3
4
5
6
7
8
@override
def signal_handlers(self) -> Optional[dict]:
    """Register signal handlers for view/controller updates."""
    return {
        'dblock_manager_on_updated': self._on_dblock_updated_signal,
        'nft_manager_on_updated': self._on_nft_updated_signal,
        'on_nav_intention_created': self._on_nav_intention_signal_received,
    }

Abstracting Signal Management

The SignalHandlerMixin abstracts signal registration so views and controllers manage Blinker signals consistently:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class SignalHandlerMixin:
    def register_signal_handlers(self):
        """Register Blinker signal handlers defined in signal_handlers()."""
        if self.signal_handlers():
            for signal_name, handler in self.signal_handlers().items():
                new_signal = signal(signal_name)
                handler_partial = functools.partial(handler)
                self._registered_signals[new_signal] = handler_partial
                new_signal.connect(handler_partial)

    def signal_handlers(self) -> Optional[dict]:
        """Return a dict of signals and their handler functions, e.g. {'signal': self.on_signal}."""
        return None

    def unregister_signal_handlers(self):
        """Unregister all signal handlers."""
        for signal, handler in self._registered_signals.items():
            signal.disconnect(handler)
        self._registered_signals = {}

The payoff: adding a new signal handler is now a one-line entry in signal_handlers() – no manual .connect()/.disconnect() bookkeeping anywhere else in the class. See the full implementation in MetaMaker’s repo.

Manual Dependency Injection for Flexibility

To keep MetaMaker extensible, I used manual dependency injection rather than a DI library, keeping control over how components were wired.

Example: Initialising a View

The AppController injects dependencies for the create-set view:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@override
def nm_init_create_set_view(self):
    """Initialize and set up the create set view, pausing the active view."""
    self._pause_active_view()
    create_set_controller = CreateSetControllerMvc(
        set_manager=self._set_manager,
        nft_manager=self._nft_manager,
        nav_manager=self,
    )
    CreateSetControllerMvc.class_id += 1
    create_set_view = self._app_view.init_create_set_view(
        col_accessor=self._collection_manager,
        set_accessor=self._set_manager,
    )
    self._start_as_active_mvc(create_set_controller, create_set_view)

Why manual DI? It offers explicit control, which avoids premature abstraction and simplifies debugging, at the cost of some boilerplate.

Supporting Persistence with SQLAlchemy

SQLAlchemy’s ORM balanced abstraction against simplicity for database access. Here is an example from CollectionManager:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class CollectionManager:
    def __init__(self):
        self._collection_id = None
        self._collection = NftMetadataCollection()
        self._on_updated_signal = signal("collection_manager_on_updated")

    def get_collection_traits(self):
        query = (
            select(Trait)
            .select_from(NftMetadataCollection)
            .join(NftMetadataCollection.traits)
            .where(NftMetadataCollection.id == self._collection_id)
        )
        return db.read_database(query)

Challenge: an out-of-date course initially had me writing legacy SQLAlchemy queries. Making the switch to 2.0 streamlined persistence. The lesson: always check the official documentation and web site.

Lessons Learned and Reflections

MetaMaker refined my architectural planning, building on my Java-Android experience as I learned Python’s ecosystem. Modular design streamlined component development and refactoring. While debugging was a real challenge, tackling it systematically made all the difference. For all the self-doubt along the way, MetaMaker stands as a record of how my architectural thinking evolved – a project I am still glad to share.

MetaMaker – Next Steps

For the full picture on this project, read the MetaMaker case study, or browse the code on GitHub.

Or, since you have read this far – a choice:

Case study InPromptOut My latest and most rigorous case study: graph modelling, a performance crisis, a security audit and cost-safety work. See how deep the architecture goes. Explore

Case study PhonixLab A live classroom phonics platform, in daily use across an eleven-school education board. Step into a project running in the real world. Take a look

Let’s Connect

If you are interested in event-driven Python architecture, MVC desktop apps, or drawing clean boundaries in small codebases, I’d be glad to hear from you.

When building MetaMaker – a cross-platform desktop app for managing file metadata and Darkblock upload workflows – I prioritised a responsive UI, even during demanding tasks like image processing and batch API uploads.

Coming from a Java-Android background, this was also a chance to get hands-on with Python’s threading model¹. I learn best by building, and with Tkinter² powering the GUI, it offered both a real challenge and a way to tackle performance problems head-on.

Here is how I built a custom thread pool wrapper to keep MetaMaker’s interface fluid and responsive.

The Challenge

Tkinter, the backbone of MetaMaker’s CustomTkinter interface, runs on the main thread. Long-running tasks – image processing such as resizing, and API uploads – blocked the UI, causing delays of several seconds. Worse, Tkinter’s lack of thread safety meant worker thread updates could crash the app. This was a barrier to scaling MetaMaker for batch workflows and large asset uploads.

Sequence diagram: sequential execution (left) blocks the main thread during tasks like API uploads, while multi-threaded execution (right) offloads tasks to worker threads.

The Solution: A Custom Thread Pool

I reached for the familiar tools first. Python’s asyncio³ conflicted with Tkinter’s mainloop⁴ and could not help with CPU-bound tasks like image resizing. multiprocessing⁵ enabled true parallelism, but its overhead – separate memory spaces and inter-process communication – was unnecessary for MetaMaker’s needs. ThreadPoolExecutor⁶ offered basic threading but lacked fine-grained control over task scheduling and callbacks.

To get the behaviour I needed, I built a ThreadPoolManager⁷: a custom wrapper around ThreadPoolExecutor, paired with a thread-safe work queue⁸ and a listener system for result handling and UI updates. This gave me:

• Precise control over task scheduling and concurrency limits
• Safe UI updates through listener-based callbacks and event signals (using Blinker⁹)
• Room for future enhancements, such as task prioritisation or retries

Sequence diagram: how a typical background task – such as image processing – moves through this architecture, from the view layer to the worker thread and back to the UI.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
class ThreadPoolManager:
    def __init__(self, max_threads=3):
        self._is_running = True
        self.max_threads = max_threads
        self.work_queue = Queue()                # stdlib queue.Queue
        self.queue_lock = threading.Lock()       # guards queue access
        self._pool: ThreadPoolExecutor = None
        self._listeners = []
        # A dedicated manager thread owns the executor and drains the queue
        self.threaded_manager = threading.Thread(target=self.manager, args=(self.callback,))
        self.threaded_manager.start()

    def manager(self, callback):
        with ThreadPoolExecutor(max_workers=self.max_threads) as self._pool:
            while self._is_running:
                try:
                    with self.queue_lock:
                        task: WorkItem = self.work_queue.get_nowait()
                    future = self._pool.submit(task.work)
                    future.tag = task.tag                # tag rides along for routing
                    future.add_done_callback(callback)
                except queue.Empty:
                    time.sleep(0.2)                      # poll; a Condition would be leaner

    def add_task(self, work_item: WorkItem):
        with self.queue_lock:
            self.work_queue.put(work_item)

The ThreadPoolManager wraps ThreadPoolExecutor, adding a thread-safe queue and a listener system.

This kept Tkinter’s main thread free for GUI updates while worker threads handled the heavy lifting, sidestepping Tkinter’s threading limitations with a lightweight, tailored solution.

Implementation Details

The ThreadPoolManager coordinates tasks through its custom wrapper around ThreadPoolExecutor. A thread-safe work queue (a queue.Queue guarded by a lock) stores incoming tasks, and a listener system manages result processing and UI updates.

Here is how it works for uploading Darkblocks¹⁰ (encrypted, unlockable content):

• The DblocksViewController¹¹ triggers a mint_darkblock¹² task.
• The task is added to the work queue and executed asynchronously by a worker thread.
• The worker notifies a listener (DblockServiceAsync¹³), which forwards a DblockServicePacket¹⁴ to the DarkblockManager¹⁵.
• The manager updates the database – e.g. storing a transaction ID – and emits a Blinker signal: dblock_manager_on_updated.
• The UI (DblocksView¹⁶) receives this signal through DblockListViewMixin¹⁷ and updates the Darkblock list on the main thread, preserving Tkinter thread safety.

View and controller components register as ThreadPoolListeners¹⁸ to drive live progress bars and status updates, giving real-time feedback during tasks like uploads.

To prevent race conditions under high load – such as uploading 100 Darkblocks at once – a threading.Lock¹⁹ guards the work queue. Without it, concurrent writes could drop tasks. A dedicated manager thread polls the work queue to dispatch tasks to the thread pool, though this polling could be optimised with a threading.Condition²⁰ to reduce CPU overhead.

Sequence diagram: a Darkblock task flows from the UI controller to the thread pool, then through worker threads, service listeners and the manager. Database updates trigger Blinker signals, which update the UI safely on the main thread – keeping MetaMaker responsive throughout the upload.

Why Not Just Use a Library?

I considered libraries like celery²¹ and extending concurrent.futures²², but I wanted full control over thread lifecycle, queue strategy and UI-safe callbacks. Building my own manager kept things lightweight and easier to debug.

The other reason was educational. My previous multithreading experience came from Java-Android, so building this from scratch in Python was a practical way to deepen my understanding while solving real performance problems.

Lessons Learned

Exploring asyncio, ThreadPoolExecutor and multiprocessing taught me how to navigate Tkinter’s threading limitations and the trade-offs of concurrency in GUI apps.

• Threading with Tkinter is tricky. You have to be meticulous about which thread touches the UI.
• More control means less confusion. Owning the thread pool meant fewer surprises and more predictable behaviour.
• Debugging multithreading is a different beast. Logging and visual debugging were invaluable when chasing rare issues.
• Custom isn’t always overkill. Sometimes building exactly what you need is the right call.

Real-World Impact

With the thread pool in place, uploading a batch of 100 Darkblocks no longer blocked the interface: the window stayed interactive while worker threads did the work, where the same upload on the main thread would freeze MetaMaker for seconds at a time. Progress bars and status text, driven by ThreadPoolListeners, updated live throughout, so users saw the upload advancing instead of a frozen window.

Conclusion

This custom thread pool keeps MetaMaker’s UI responsive – a cornerstone of the app despite Tkinter’s constraints.

MetaMaker – Next Steps

For the full picture on this project, read the MetaMaker case study, or browse the code on GitHub.

Or, since you have read this far – a choice:

Case study InPromptOut My latest and most rigorous case study: graph modelling, a performance crisis, a security audit and cost-safety work. See how deep the architecture goes. Explore

Case study PhonixLab A live classroom phonics platform, in daily use across an eleven-school education board. Step into a project running in the real world. Take a look

Let’s Connect

If you are interested in concurrency, responsive desktop UIs, or threading patterns in Python, I’d be glad to hear from you.