DEV Community: Digital Craft Workshop

Four Reason to Change your Software

Digital Craft Workshop — Thu, 18 Jun 2026 15:07:15 +0000

CLEAN CODE & REFACTORING

Four Reasons to Change your Software

Created by [Stories](https://www.freepik.com/stories)

Michael Feathers defines four main reasons to change your code in the book Working Effectively with Legacy Code. I found those few paragraphs interesting, and I would like to share them with you from my perspective.

Four main reasons to change are

Adding a feature
Fixing a bug
Improving design
Optimising

Adding Feature and Bug Fixing

original pictures by [Stories](https://www.freepik.com/stories)

The most typical reason to change software is an adding of the feature. Your software is acting one way, and the boss or client needs it to do something else.

At first, adding a feature may look like an easy task for both sides. Friction between the developer and the task assigner began when the assigner thinks it is a bug, but the developer sees it as a completely new feature.

At the moment when I am writing this article, I am also working on a form-based information system, and new task recently appeared in the mailbox. The client wants me to fix the focus behaviour of textboxes. He thinks that every time he clicks or tabs into a textbox which contains a text, the whole text should be already selected or as he said; “it should be blue”.

selection of text

As the developer, you know that this is not typical behaviour of textbox and you will have to make changes. Depends on the framework you are work with, the task can take a few minutes or a few hours, and you may come out without a solution.

It might seem that difference between adding a feature and bug fixing is just the dilemma about the contrast of the point of view. A task stays the same, and you still have to complete it one or another.

But some companies are tracking developers time, for example, for invoice calculations or quality initiatives. Such difference decides if the company will bill the customer for a new feature or not. Bug fixing can be part of the contract with the customer. In this situation, the determination of difference crucial.

Design Improvement and Optimisation

Created by [Stories](https://www.freepik.com/stories)

First of all, don’t get me wrong. By saying word design, I mean a code design, no design of user interface.

Design improvement is a different kind of software change. It is driven by the goodwill of the developer, no by the boss task.

When we want to alter the software’s design to make it more maintainable, we want software behaviour to keep untouched. By changing a design, we may introduce a bug. Fear of introducing a bug leads to intact code segments which stay the same since the beginning and will rot.

As developers, we grow and knowledge of our craft rise. Time goes, design of new code is better, and one day task will appear for adding a new feature into old code parts. We can clearly say that such situations will once in a while come out. Such a position always motivate me to improve the design, but I am too afraid of dropping behaviours, and I will not do any. Again.

Created by [Stories](https://www.freepik.com/stories)

Side note: if you like thinking about the craft itself — when to refactor, when to leave code alone — I share short, free lessons like that in The Claude Code Memory Starter, a tiny email series you can join in one click.

Refactoring

Developers fear of changing code drives the creation of whole the discipline named refactoring. Refactoring is also the main topic of the earlier mentioned book.

The idea behind refactoring is that we can make the software more maintainable without changing behaviour if we write tests. Tests will serve as watchdogs. If any test fails while you improve a design, it indicates that you unwillingly drop a behaviour.

Code should be cover by the collection of tests which will keep watch on application behaviours. We should refactor in small steps, and continuously run a set of tests that will keep us informed.

The critical thing about refactoring from a change point of view is that there aren’t supposed to be any functional changes when you refactor.

Optimisation

Created by [Stories](https://www.freepik.com/stories)

The optimisation is like refactoring, but with a different goal. We want the functionality to stay the same, but the goal is to increase performance. Optimising can lead to dropping a behaviour and introduction of bugs too. We must apply the very same rules as in the refactoring process.

Summary

Fight between “it’s a feature” and “it’s a bug” is endless. Correct identification of the problem could lead to the rise of the company’s income or vice versa.

Refactoring and Optimizing are essential disciplines of code improvement and reasons for changing code. It has to be done slowly, wisely, and with the collection of tests which are going to watch your back.

One way of improving code design is to take advantage of design patterns. I wrote a few pieces, and you might find an interested in reading them as well.

Decoupling with Chain of Responsibility Pattern in C#

The Chain of Responsibility Pattern allows us to easily separate dependent parts to make code more extensible and…medium.com

How to manage states with State Design Pattern in C#?

Everything you need to know about State Design Pattern in C# at one place.medium.com

Daniel Rusnok's Newsletter

Every month I will send you an email about with list of my newest articles. It will be ofcourse the friendly links…www.danielrusnok.com

If this resonated, you might also enjoy The Claude Code Memory Starter — a short free email series, one bite-sized lesson at a time.

Developers are introverts. Domain-driven design can help.

Digital Craft Workshop — Tue, 16 Jun 2026 15:07:44 +0000

Developers are introverts. Domain-driven design can help to change it.

As developers, we are writing code to build software, but we can’t make good software without talking to clients.

Developers aren’t chatty.

Most of the time software developers are struggling in communication with clients and also with the outer world. Many of us choose this career to avoid meeting with people, and that is why companies hire managers who are doing instead of us.

If you are one of these introverts, then I have bad news for you. You may end up stuck with buggy code forever.

Created by rawpixel.com — [www.freepik.com](http://www.freepik.com)

If you are going to build software for business, you need to understand every detail because you are translating business processes into code. And you don’t want to lose important information in translation.

Domain-driven design intervention

One of the critical pieces of Domain-driven design(DDD) is to encourage developers for better interaction with domain experts. The domain expert is one who knows the client’s business needs and processes.

Developers need to understand their clients more than their partners. If you are a man, you probably are more successful in understanding your client than your precious one.

Photo by yanalya — [www.freepik.com](http://www.freepik.com)

You may say you already talk to them, but maybe in a different language. Maybe you are using your terms like tables in the database rather than domain concepts.

DDD guides us to find a common language with Domain Experts and understand each other at a much higher level.

Ubiquitous language

Ubiquitous. Terrible word. If you don’t know how to pronounce it, this might help [yo͞oˈbikwətəs]. For me, it doesn’t. I had to use Google Translator for listening to the pronunciation. It doesn’t help either.

A simple definition of a ubiquitous language is to come up with terms that will be commonly used when discussing a particular subdomain. What subdomain is, will be introduced in the next paragraph. Hold tight.

There will most likely be terms that come from the business space, not the software world. But those terms have to be agreed by both sides, domain expert and developer. Make sure there is no confusion or misunderstanding created by the terminology used by various members of the team.

Photo by pressfoto — [www.freepik.co](http://www.freepik.com)m

Domain and subdomains

The core domain is a field of study that defines a set of common requirements, terminology, and functionality for any software program. DDD teaches us how to divide the core domain into smaller subdomains.

Imagine a company. It can be divided into smaller pieces, departments, for example. With subdomains, the logic stays the same. They are filled with their complexity, terminology, tasks, and challenges.

Image by Starline — [www.freepik.com](http://www.freepik.com)

Many applications just try to do many things at once and introducing new features getting more difficult. With DDD, you will divide and conquer. By tearing software to separated subdomains, we can achieve dividing problems that are much easier to solve.

The principle of Separation of Concerns(SoC) not only plays a critical role in identifying the subdomains but within each subdomain, we use it as well.

Many applications spread domain logic across the entire project. Across the persistence layer, across the user interface. Such spreading makes it much more difficult to keep all of the business logic consistent.

If you want to keep going on the meta-skill side of building software — I'm publishing short, free lessons in The Claude Code Memory Starter, a tiny email series you can join in one click.

DDD applies an SoC to help direct you by focusing on the domain. Not on details like how to persist data into the database or how to connect to external API. Those become implementation details that you can ve worry about later.

Benefits

The first main benefit is flexibility. Because DDD guides us to focus on small, individual nearly autonomous pieces of our domain, our process and the resulting software is more flexible. We can easily move or modify the small parts with little or no side effects. The project is stable and flexible.

Image by master1305 — [www.freepik.com](http://www.freepik.com)

Another benefit is that code is closely mapped to the customer’s understanding of the problem. DDD gives you a clear and manageable path through a very complex problem. When you look at the code, you can see that it’s generally well organized and business logic all lives in one place.

DDD is not a path for every project, but there are many principles and patterns from which you can benefit. Its real benefit is for complex domains. You can describe domain as complex when it gets challenging to domain experts to express their needs. You know. Like women.

Image by Jcomp — [www.freepik.com](http://www.freepik.com)

DDD provides principles and patterns that help us tackle difficult software problems and even business problems. These patterns are historically successful in solving very complex problems.

The ultimate goal is not to write code, not even building software, but to solve problems. Nobody wants your software; they want what it can give them.

Disadvantages

You will spend a lot of time talking about the domain and the problems that need to be solved. And you will spend plenty of time sorting out what is truly domain logic and what is just infrastructure.

DDD is not always the right path for your applications. And it’s helpful to keep in mind that exist some scenarios where DDD is an overkill. If you have an application or subdomain that is just a data-driven app and doesn’t do much more than a lot of crud logic, there is no needs to use DDD. It would be a waste of time and effort.

Technical complexity doesn’t mean business domain complexity. DDD may not just be a path because your project is technically challenging.

The Book

DDD was presented in 2003 by Eric Evans in a book titled Domain-Driven Design. The book was written for one major reason, and that is for solving complex problems. That’s why a subtitle of Evans's book is “Tackling Complexity in the Heart of Software”.

Summary

Domain-Driven Design helps man to understand women fully. No. I am joking. One book could not be enough.

What I want you to take with you is this. Be more chatty with your clients and always try to understand their needs. If you don’t understand each other, define your ubiquitous language.

Divide and conquer your business logic. Separation of Concerns, loose coupling, subdomains. So many titles for one thought. Divide your code into smaller pieces on every level.

Daniel Rusnok's Newsletter

Every month I will send you an email about with list of my newest articles. It will be ofcourse the friendly links…www.danielrusnok.com

If this resonated, you might also like The Claude Code Memory Starter — a short free email series, one bite-sized lesson at a time.

Recipe to greatly layered architecture!

Digital Craft Workshop — Sun, 14 Jun 2026 15:04:35 +0000

Recipe to greatly layered architecture!

Is it a recipe? Sure. Is it advice on how to NOT make spaghetti? Also, yes. Does the article belong into Software development category? Of course, what is wrong with you? Are you interested? Great, then read more.

Photo by Trang Doan from Pexels

Okay, now it is time to explain what the hell am I talking about. Onion architecture is an approach to design layers of an application.

Spaghetti or also the spaghetti code is the code, that is harshly separable, tangled and passes through multiple layers of an application.

Such code is hard to maintain and hard to extend with any new features. So, Onion architecture is some kind of recipe telling you how to NOT make spaghetti.

Why onion?

As we know, it is simple to detach layers from an onion as well as attach them back again Alright, I guess nobody is attaching onion layers back to an onion, but it can work well as an example for our imagination. Architecture of an onion consist of core and layers. What should be the core in a software application?

Should it be a Presentation of an application? Let me explain. By the phrase Presentation of an application, I mean the part of an application, that is responsible for user interface. In software development, such part is powered by different technologies like WPF, Angular and React. And what is the Presentation of onion? I´d say it’s just a peel. From the measurement point of view, the peel is too far away from the core. So, the Presentation of an application cannot be the core.

Should it be a Database? Let’s think about it. In a database, we can find information. What information about an onion we know? Onion can have a different colour, kind, taste or look. If information can have different values, they are variable. If something is variable, we can’t rely on it. We don’t have a solid core. So, the database cannot be a core either.

What defines an onion by nature? In my humble opinion, it is its genetic information. Genetic information defines how the onion looks like, how it tastes etc. Genetic information formulates the onion. And what is genetic information? Well, it is nothing more than a set of rules.

What or who is forming software applications? Developer? I don’t think so. Simply said, the developer is translating tasks from human language to the language of the computer. So, the software applications are shaped from tasks by humans? Yes! And what are those tasks? Tasks are a list of criteria that the application should do. In software engineering, we have a name for one criterium on the list and it is the Business rule. So, the result of our brainstorm is:

Core of application is defined by tasks or Bussiness rules, which application should fulfil.

Onion Architecture

In onion architecture, core consists of two layers; The Domain layer and its wrapper, the Application layer.

In the domain layer, we will keep entities and value objects of our application. Entity is every class that is describing the behaviour of the object in real-world, which uniqueness is defined by the value of its identifier. For example, human uniqueness is defined by his or her personal identification number. On the other hand, the Value Object’s uniqueness is defined by its value. For example, a phone number or an address.

Part of the core called Application contains every work done with entities or value objects. In the introduction, I talked about tasks or business rules. Example of business rule could be a task “Save customer.” But wait, such a rule will have to work with the database. And at the introduction, we made it clear that the database should not be a part of the application’s core. So where is the database?

If you liked this and want more, I'm sending a short free email series on the same kind of thinking — The Claude Code Memory Starter.

Database can be found in the Persistence layer, marked by green colour in the picture above. In the picture is an arrow pointing at the dependency of the Persistence layer to the Application layer. More precisely Application layer must not use any classes defined in the Persistence layer.

How can we even implement “Save customer” task without a possibility of invoking methods of class in Persistence layer? Persistence layer in Onion architecture can be pictured as a Plugin for the Application layer. What do we need to plug in the plugin? Interface. Where will be an Interface? Well, in the core of the application. We will hold our interface in the Application layer and its concrete implementation will be implemented in the layer of the plugin, in our case, in the Persistence layer. This approach is called Dependency inversion principle. By implementing such an approach, we are achieving database technology independence. Database becomes an implementation detail and our core is completely separated from possible external influences caused by the database.

With the same motivation, the last layers are created. Presentation layer and the Infrastructure layer. As the name suggests, the Presentation layer is responsible for the implementation of the user interface. Because in everyday world there are growing tendencies to use new JavaScript technology, the separation of the presentation layer from the core of an application is a good idea.

Separation of the Presentation layer also brings another advantage. There are more and more electronic devices and every developer will agree with me if I say that the Presentation layer will work best if it is developed in native technology.

Last but not least, the Infrastructure layer. The Infrastructure layer serves for bulking implementations of communications with external technologies. We don’t want to depend on external technologies. For example, it can be a technology responsible for sending emails or file printing.

Before you go: if you want to keep getting practical posts like this in your inbox, The Claude Code Memory Starter is a short free series I think you'll enjoy.

Summary and useful links

Onion architecture is a concrete implementation draft inspired by book Clean Architecture, which author is Robert C. Martin. Mentioned version of Onion architecture was designed by software architect Jason Taylor. Complete repository with sample of implementation can be found at Github.

By using Onion architecture, we can reach the separation of vital rules from the outer world’s technologies. If we don’t tangle into our business rules outer technologies, we can manage the change of technologies more easily. Architecture brings easier use of modern development approaches like Domain-Driven Design and Test-Driven Development.

My introduction into Azure Service Fabric

Digital Craft Workshop — Fri, 12 Jun 2026 15:04:33 +0000

Azure & Cloud

My Introduction into Azure Service Fabric

As a monolithic application developer, I was challenged by my CEO to learn something more about an Azure Service Fabric technology. I would like to share with you what I have learned in the last few weeks.

Newsletter

Subscribe and be the first who get noticed when the new article about software development comes out!

Azure Service Fabric is a platform created by Microsoft that facilitates creating and deploying microservice-based architecture systems. It provides scalability, reliability, and availability for your system.

If you are not familiar with Cloud Computing, here is my Introduction to Cloud Computing:

Introduction to Cloud Computing

Cloud computing is the present and future of software utilization, development and hosting. Let me introduce you its…levelup.gitconnected.com

Microservice architecture

If you want to use Azure Service Fabric, first you must understand what microservice architecture represents.

Microservice architecture is based on multiple independent applications(services), which are communicating mostly via their public API. Service should not see implementation details of other services and vice versa. Microservices provide scalability by design because the system load is divided into more “subsystems”.

Systems like these are harder to maintain than monolithic based systems because the developer must think a little bit differently than he was used to. Every service is a self-based system that should run by itself without relying on other systems.

Cluster

Every Azure Service Fabric project is made of things called Cluster. Cluster is a bulk of resources (Load balancer, applications, IP addresses) needed for the correct functioning of an application. Cluster is made of so-called Nodes.

Node

Nodes are nothing more than usual computers or virtual machines. They use an operating system such as Windows or Linux and have installed an Azure Service Fabric Runtime. The cluster can contain 1:N nodes. These nodes are connected to each other in a network-based communication.

The main purpose of the node is to host your application. One node could host multiple applications which means every cluster can host unlimited amounts of application, as long as there are physical resources up to it.

Application

The result of Azure Service Fabric solution is an application. An application is nothing more than a declaration what does solution contains. An application describes which services it contains.

Stateful and Stateless service

Stateless service is, as title hints, a service without any state. Simply speaking, stateless service does not have any storage to save the state of data. As a stateless service can be also understood a project with database connection. How is it possible?

A project with a database connection is not storing data. The database is storing data. Storing data means saving the state.

On the other hand, Stateful service can store data in special so-called Reliable Collections. I will provide more information about the reliable collection in the next article.

Actor service

As a special kind of Stateful service performs Actor service. Actor service is service based on the Actor Model. The Actor Model is not a product of Azure Fabric Service and it is not invented by Microsoft either. The Actor Model Theory is a simplification of multithreading programming. You can find detailed information about the Actor Model here.

How I think about Actor service is that there are multiple instances of service with own storage per unit that you desire. For example, one user of your application can have his instance of Actor service.

Every Actor service must be provided with identification. It may be string, it may be guid, etc. If it can be string, it can be mostly every casted primitive type of variable you want to use.

If you think about it you can find out, that it can nicely handle one to many relationships between entities. If there is always one instance of service per user ID, there is also dedicated storage for one user. It is one to many relationships solved at the virtual or physical machine level.

So instead of creating queries using where clause with user ID condition you just create an instance of the whole service. And that is what I find very powerful as a developer.

Daniel Rusnok's Newsletter

Every month I will send you an email about with list of my newest articles. It will be ofcourse the friendly links…www.danielrusnok.com

3 Things That Bit Me Before My Claude Code Memory Setup Worked

Digital Craft Workshop — Fri, 12 Jun 2026 05:34:50 +0000

Not a member? Use this link.

I gave Claude Code a memory, and within a couple of days it had eaten every credit on one of my API keys.

That was version three. Version one had built a loop that triggered itself. Version two had my laptop fan screaming every time I closed a terminal. None of them were the clean recall-in, capture-out setup I run now — they were the three wrecks I drove on the way to it.

So this is the part I left out of the clean write-up. Three things that bit me, and what each one is actually warning you about if you go build memory into Claude Code yourself.

None of them were typos or a missing semicolon. Each one looked completely reasonable at the moment I wrote it. That's what makes them worth writing down — these are the mistakes that don't announce themselves until they're running.

1. The hook that triggered itself

My capture step runs on SessionEnd. When I close a Claude Code session, a hook fires, the session's decisions get extracted, and they get written to the memory store. Simple enough.

The first version extracted those decisions by spawning a Claude process to read the transcript. Which meant the capture step was itself a Claude session. Which meant it ended too. Which fired SessionEnd again.

The hook was extracting the act of extracting. Each meta-session closed, triggered another meta-session to capture its decisions, and that one closed and triggered the next. A snake eating its own tail, one link at a time.

It did not run away to infinity, because other limits caught it first. But it ran far enough to scare me, and the lesson stuck harder than most: a capture process must never be the same kind of thing as the event that triggers capture.

If your "extract what happened" step is itself a session, and sessions are what trigger extraction, you have a recursion with no base case that you didn't write on purpose.

The fix is to break the type. The capture process has to be something the lifecycle doesn't watch — a plain script, a detached subprocess, anything that isn't itself a session. Once the extractor stopped being a Claude session, the loop had nothing left to feed on.

This is the kind of bug that's obvious in hindsight and invisible while you're writing it, because at write-time "just have Claude read the transcript and pull out the decisions" is the most natural instruction in the world. The recursion is hiding in the word "session," and you don't see it until it's spinning.

I'd actually been bitten by a cousin of this before — an earlier version of the memory setup spawned seven parallel Claude instances from one "helpful" hook. The full story of that first build is in how I added persistent semantic memory to Claude Code in 15 minutes.

2. The embedder that cooked my laptop

Second version. The loop was gone, capture worked, and then I noticed my laptop fan spinning up every single time I closed a session.

The culprit was where I'd put the embedding step. I was generating embeddings locally with all-MiniLM-L6-v2, a small sentence-transformer model. The word "small" is carrying a lot of weight in that sentence.

Small for a model is not small for something that runs on every SessionEnd. The model file is around 80 MB. Loading it meant spinning up a Python runtime, pulling the weights into memory, and running the encode — and the whole spawn footprint landed near 500 MB of RAM and a real bite of CPU, every time I closed a terminal.

On a desktop you might never notice. On a laptop, closing several sessions an evening, you notice. The machine ran warm, the fan ran loud, and the cause was a memory feature I'd added to make my life easier, quietly taxing the machine every time I stepped away from it.

The thing to internalize here isn't "MiniLM is bad." MiniLM is fine. It's that the cost of a memory pipeline is dominated by where the heavy steps run, and how often they run there. Embedding locally, on CPU, on every session close, is a lot of repeated heavy lifting for a background nicety nobody asked to be expensive.

The move is to get the heavy step out of the hot path. Push embedding to a hosted endpoint, or batch it into one job that runs on a timer instead of once-per-close, or skip local embedding on a laptop entirely. The decision that matters is placement and frequency. The model name barely registers next to it.

Want the Claude Code memory setup I build with? The Claude Code Memory Starter is a free email series.

3. The frontier model that quietly ate my credits

The extraction step — the part that reads a transcript and answers "what did we actually decide here" — needs a language model to do it. When I first wired it, I pointed it at the model I already had keys for: Claude Sonnet. A frontier model, on a key I was also using for a production app.

One transcript through Sonnet is cheap. The problem was the multiplier I'd stopped thinking about. At the end of an evening I close sessions in a burst — three, four, five at once — and each close fired its own extraction against that same shared key.

Within a couple of days the credits on it were gone. Not because extraction is expensive in principle, but because I'd wired the most expensive available model to the most frequent available trigger, drawing from a budget that something real depended on.

The fix had two halves, and both are worth stealing.

First, the right model for the job. Transcript extraction is not a frontier-model task. You're asking it to summarize the decisions in a block of text, not to reason about a hard problem. A free-tier Gemini Flash Lite handles it without complaint, and a small OpenAI model — cheaper than Haiku — sits in as a fallback for the days the free tier hits its rate limit. For this specific job the quality difference is nil and the cost difference is the whole ballgame.

This is the same instinct I wrote up separately: when a cheap model clears the bar, don't quietly reach for a pricier one. More on that in how a Claude Code skill turns an hour of setup into 90 seconds — same lens, different chore.

Second, the key. I'd been extracting on the same Anthropic key my production app billed against, so a runaway background hook and a live product were both pulling from one budget. Separating them — memory extraction on its own provider, production on its own — means a mistake in the plumbing can't take down the thing that actually pays for itself.

So the rule, in one line: match the model to the difficulty of the task, and never let a background convenience share a budget with something that matters. A hook firing on every session close is exactly the kind of process that belongs on the cheapest model that clears the bar, on a key that can fail quietly without taking anything else with it.

What the three have in common

A loop, a hot fan, a drained wallet. They look like three unrelated failures. They're the same one in three disguises.

Every one of them came from underestimating how often a session-lifecycle hook fires. A thing that runs "when I close a session" doesn't run occasionally. It runs constantly, in bursts, in the background, while your attention is on something else entirely. Whatever you put in that path — a process type, a model load, an API call — gets multiplied by a number you are not currently looking at.

The setup I run now is boring for exactly that reason: nothing heavy lives in the hot path anymore. Extraction is detached from the session. The model is cheap and isolated on its own key. The embedding doesn't fight my CPU. None of it can loop, cook, or bill, because the expensive parts were moved out of the path that fires the most.

If you build memory into Claude Code, that's the lens I'd hand you. The question to keep asking isn't "does this work when I run it once." It's "what does this cost when it runs in the background, in a burst, while I'm not watching." Get that one right and the memory layer disappears into the background, which is the only place it's any use.

The clean wiring all of this eventually became — the recall-in, capture-out shape, end to end — is its own write-up, linked below, if you'd rather read the version that works than the three that didn't.

Captions That Read Along, One Word at a Time

Digital Craft Workshop — Wed, 10 Jun 2026 15:55:26 +0000

One evening, the reel looks perfect — until I read along. My voice says "memory," and the word glowing on screen is "billing." One word ahead. The whole reel, every scene, the highlight runs ahead of me, like a bad karaoke machine.

The fix was one character. Finding it took longer than it should have.

Part 3 ended with a SceneAudio object — an audio clip, and a list of words, each with a start and end in seconds:

type SceneAudio = {
  audioPath: string;
  words: { word: string; start: number; end: number }[];
};

This post is about how that data gets spent. It colors each word the moment the voice reaches it.

Why captions at all

Reels are watched on mute. Most of the feed scrolls past with the sound off — on a train, in a meeting, next to a sleeping kid. Without the words on screen, it's just images changing with no context.

Captions carry the reel. For most people who see it, they're its only voice. Static captions — a block that sits there for the whole scene — are the lazy version.

The eye reads the whole block at once, then leaves.

Word-by-word highlighting fixes that. The color fill is a progress bar your eye can't look away from. It pulls you word to word at the speed it's spoken.

That's the karaoke effect — the part of the caption stage that actually earns its place.

Why ASS, not a caption library

ASS — Advanced SubStation Alpha — is a subtitle format: a plain text file describing which words show, when, and how they're styled. libass renders it, and FFmpeg already speaks libass.

My first instinct, though, wasn't ASS. It was a caption library — a React renderer, a canvas animator, one of the npm packages built for animated subtitles.

Every one of them wanted to own the render:

draw to a canvas
spin up a browser
re-encode the video their way

I already had an FFmpeg pipeline compositing scenes. I didn't want a second rendering engine bolted to the side of the first.

ASS is older than all of them, and it does one thing well. The whole caption stage comes down to this: generate a text file, hand it to a filter I'm already running.

No new dependency. No second renderer. A .ass file is just text:

[V4+ Styles]
Style: Caption,Inter Black,68,&H002626DC,&H00FFFFFF,&H00000000,&H80000000,1,0,0,0,100,100,0,0,1,6,3,2,80,80,120,1

That one line is the entire look: Inter Black, 68pt, a 6px black outline and a soft shadow so white text survives over any background. The two colors that matter are PrimaryColour &H002626DC and SecondaryColour &H00FFFFFF.

ASS colors are BGR, not RGB, and read backwards — &H002626DC is #DC2626, the accent color. That's the color a word becomes: white until the voice reaches it, the accent once it has.

The karaoke tag is the whole trick

Here's the function that turns one scene's words into one subtitle line:

function buildDialogue(event: LineWord[][], offsetSeconds: number): string {
  const allWords = event.flat();
  const start = allWords[0].start + offsetSeconds;
  const end = allWords[allWords.length - 1].end + offsetSeconds + 0.1;
  const lineStrings = event.map((line) =>
    line
      .map((w, wi) => {
        const durCs = Math.max(2, Math.round((w.end - w.start) * 100));
        return `{\\kf${durCs}}${escapeAss(w.word)}${wi < line.length - 1 ? " " : ""}`;
      })
      .join("")
  );
  const body = lineStrings.join("\\N");
  const positioned = `{\\an2\\pos(540,1800)}${body}`;
  return `Dialogue: 0,${fmtTime(start)},${fmtTime(end)},Caption,,0,0,0,karaoke,${positioned}`;
}

Every word becomes {\kf52}word, where 52 is the word's duration in centiseconds — a word that takes 0.52 seconds to say. libass walks the line left to right, filling each word over its \kf duration, then moving on. Add up all the \kf values and you get the line's length.

Math.max(2, …) is there for a reason. A word can land with a zero-width timing, like punctuation or a render glitch. That gives it a \kf0 and makes it flash. Flooring it at two centiseconds keeps it animating.

Pinning it so it never jumps

The first version let ASS auto-place the subtitle. A one-word hook sat low; a three-line caption pushed itself up to fit.

Between scenes, the captions hopped around the bottom third of the screen.

The fix is one tag:

{\an2\pos(540,1800)}

\an2 anchors the text by its bottom-center. \pos(540,1800) pins that anchor to x=540 (dead center of a 1080-wide frame) and y=1800 (120px off the bottom of a 1920-tall one).

Whether a caption is one line or three, its bottom edge is always at y=1800. It grows upward from a fixed floor instead of floating.

The one-line bug that highlighted the wrong word

Back to that misaligned reel and the word that was always one ahead.

Everything else in my pipeline runs on absolute time. A scene starts a few seconds in. A word starts a moment later. Absolute timestamps, all the way down.

So when I wrote the karaoke layer, I reached for the same model. Each word gets the timestamp it starts at.

That is not how \kf works. Karaoke durations are sequential offsets from the line's start. Each value measures a span. It says how long to fill this word before moving to the next.

I'd built the line by feeding each word the next word's figure. It was a classic index slip. I wrote words[i + 1] where I needed words[i]. Every fill ran one word long, so the highlight stayed one word ahead of the voice.

The fix was deleting the +1. Each \kf now comes from the word's own end - start, the same line shown above.

When a format looks like one you already know, check whether its numbers mean the same thing. Here they didn't. Everything in the pipeline was absolute, but the karaoke timings were relative.

When scenes don't start at zero

The caption stage has one more job. The scenes don't start at zero — each word's start is relative to its own scene's audio, but the final reel is all scenes concatenated with a 0.4-second pause between them.

So the renderer carries a running offset:

const INTER_SCENE_GAP = 0.4;
let cumulativeOffset = 0;
for (let i = 0; i < scenario.scenes.length; i++) {
  // ... synthesize audio, collect per-word timings ...
  sceneTimings.push({ audioOffsetSeconds: cumulativeOffset, words });
  const isLast = i === scenario.scenes.length - 1;
  cumulativeOffset += narrationDuration + (isLast ? 0 : INTER_SCENE_GAP);
}

buildDialogue adds that audioOffsetSeconds to every word, so scene 3's captions land at scene 3's real position in the finished video. The 0.4s gaps sit between scenes, where there are no words, so the karaoke clock never accounts for them.

Burning it in

The last step is one FFmpeg call:

ffmpeg -i concat.mp4 \
  -vf "subtitles=filename='captions.ass'" \
  -af "loudnorm=I=-14:TP=-1.5:LRA=11" \
  -c:v libx264 -pix_fmt yuv420p -r 30 \
  -c:a aac -b:a 160k -ar 48000 -movflags +faststart final.mp4

subtitles= hands the .ass to libass, which renders every \kf, \an, and \pos onto the frames.

The -af loudnorm next to it is unrelated but worth a note. It normalizes the audio to -14 LUFS, the level Instagram, TikTok, and YouTube Shorts target. Skip it and the reel plays quieter than everything else in the feed.

What's still flat

At the end of the caption stage I have a vertical video. Narrated in my voice. Karaoke words pinned to a fixed line, loudness-matched to the platforms. It plays. It reads. On mute it still works.

It's also completely still. Behind those captions is a static card — a background color, a headline, a stat.

Nothing moves. A frozen image with animated text on top is barely better than a slideshow.

Part 5 takes on the next problem: motion. Each scene gets three SVG layers, rendered through sharp (a Node image library) at 2160×3840, then animated with FFmpeg's zoompan. That's the Ken Burns effect, a slow zoom that makes a still image feel alive. It's the motion baseline, before any GPU gets involved.

Want the Claude Code memory setup I build with? The Claude Code Memory Starter is a free email series.

3 Domain-Centric Architectures Every Software Developer Should Know

Digital Craft Workshop — Mon, 04 May 2026 10:53:59 +0000

SOFTWARE ARCHITECTURE & REFACTORING

3 Domain-Centric Architectures Every Software Architect Should Know

The first concern of the architect is to make sure that the house is usable; it is not to ensure that the house is made of brick. — Uncle Bob

Domain

The expression domain is occurring in software bibles for a very long time now and is heavily discussed in the book Domain-Driven Design by Eric Evans. The domain is the real-world context which you are attempting to solve by writing a piece of software. Simply said, the domain is the thing why software exists and is about.

Evans divides the domain into three subdomains.

Core Domain

The core domain represents a competitive advantage and the software's reason for being. It is a hearth of the software with the most fundamental business rules, use cases, and domain models. It usually is the smallest part of the codebase. In other words, it is the most critical 20% part of the software.

Supporting Domain

Supporting domains are supporting subsystems of software. The core can still exist without them but does not makes it alone to its users. There can be multiple supporting domains in one system. For example, the supporting domain is for the core domain, the same thing as invoicing for Amazon.

Generic Domain

A generic domain is the least custom part and the least important part of the software. It is not specific to your domain, and it is widespread in other systems. I am currently working on an employee's timesheets information system, and the generic domain for this software is an external time tracker for each of the employees.

Left: Common domain, Right: Concrete e-shop example

Summary

It is important to decide what your core domain is and focus your development resources here from a business perspective.

Domain-Centric Architecture

Now when we know what the domain is, you can logically derive that Domain-Centric Architecture puts the domain into the center. Each software architect has a huge responsibility for proper recognition of what is an essential use case and what is just an implementation detail.

Let's pretend that you are buying the house. What is essential for your choice, and what is in second place?

From my perspective, space and usability are the most fundamental reasons for buying a new house. Ornamentation and building material may come right after that and change my decision, but when I am looking at real estate offers online, I am looking at the space and usability for my needs first.

Hexagonal Architecture

Alistair Cockburn invented hexagonal Architecture in 2005. Also known as Ports and Adapters Architecture. Few authors marked the Hexagonal Architecture as an origin of Microservices Architecture.

It is a plug-in system that consists of multiple loosely coupled components which you can connect to the core. The advantage of such division is in easy exchange of each component.

Source and Credits of image: [https://ebrary.net/85161/computer\_science/hexagons\_layers](https://ebrary.net/85161/computer_science/hexagons_layers)

Components communicate with each other via exposed public interfaces(ports). Such interfaces are typically used for notifications or database querying and storing.

Adapters are the glue between components and the outside world. More adapters can be glued to one port. For example, Azure deploying can be managed through CLI, web portal, or Windows PowerShell.

Onion Architecture

Founded by Jeffrey Palermo in 2008. The perspective of Onion architecture is to provide better testability, maintainability, and dependability. It is an architecture based on the Inversion of Control Principle. It is biased towards Object-oriented programming.

Source and Credits of the image to [CodeGuru](https://codeguru.com)

The architecture consists of multiple concentric layers interfacing towards the core domain, moving all coupling towards the center.

Domain Layer

In this layer, you will find all business and behavioral objects. It also contains the domain interfaces. The domain layer can't have any dependency. On the contrary, other layers should depend on the domain layer.

Repository Layer

This is an abstraction for saving and retrieving data from persistence. The layer is also mapping data from persistence to business entities. If you are not familiar with the Repository Pattern, here is the medium post from my friend Sena Kilicarslan.

Repository Pattern Implementation in ASP.NET Core

Service Layer

Consists of interfaces of common operations. It provides and encapsulates the communication between the UI Layer and Repository Layer. Also, it can hold a business logic for an entity.

UI Layer

This is the most outer layer. Here you will find the implementation of the dependency injection principle. It can be a web application, unit test project, or web API.

Pros

Flexible, sustainable, and portable architecture.
No need to create a common and shared project.
It can be quickly tested.
Coupling towards the center.

Cons

It is not an easy architecture for beginners.
Interfaces and abstractions are heavily used, and move through code can be confusing.
Architects mostly messed up, splitting responsibilities between layers.

Clean Architecture

Robert C. Martin, also known as Uncle Bob, invented Clean Architecture in 2012. The architecture is based on the Separation of Concerns principle. It's achieving the separation by dividing the software into layers. The architecture is easily testable, independent of UI, database, or any external agency.

Source and credits of image: [https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

The architecture consists of concentric circles that differ in areas of software. The more outer the circle is, the higher level of software it is. Outer circles are mechanisms, and inner circles are policies.

Source code dependencies can only point inwards. Anything declared in the outer circle must not be mentioned in the inner circle, including classes, functions, and variables.

Entities

The Entities layer encapsulates business rules. It can be an object with methods or a set of data structures and functions. It encapsulates the most general high-level rules, also known as Domain.

Use cases

These are application-specific business rules. Here you implement all of the use cases of the system. Rules do not affect the entities. The layer is not affected by externalities such as database or UI.

Interface adapters

This layer is responsible for converting data from use-cases and entities to format for an external agency. Typical usage is the MVC architecture of GUI. Here is where data is converted from Entities to database tables vice versa. The layer's main goal is a conversion from an internal form of data to an external form.

Frameworks & Drivers

The outermost layer. It is composed of glue code for every external agency, such as a database or web framework.

Summary

Each of the listed architecture works the same. They all have the Domain in the center wrapped by Application Layer as use-cases, and Persistence, Presentation, and Infrastructure in the outer circle represent the implementation details pointing towards the center.

Pros

Heavy focus on the domain.
Less coupled.
Allows using Domain-Driven Design.

Cons

Change is difficult.
Requires more thought.
Initial higher cost.

Sources

How to Switch the Algorithms at Runtime with Strategy Pattern in C#

Digital Craft Workshop — Tue, 28 Apr 2026 07:32:16 +0000

When, Why, and How to use Strategy Pattern in C#. The quick and easy introduction.

[Source](https://www.freepik.com/free-photos-vectors/button)

The Strategy Pattern

Strategy Pattern or SP enables selecting an algorithm at runtime. Simply said, we choose an algorithm based on the incoming dynamic parameter.

Sounds like decision-statement, right? Switching an algorithm based on parameter value? We are talking about a switch or if-else statements, correct?

Well, yes. SP is some kind of decision-statement. But SP follows rules of Object-oriented programming languages and brings theirs advantages to the table like reusability and extensibility. It also meets the requirements of the SOLID code.

Advantages of the Strategy Pattern

It's easy to switch between different algorithms (strategies) in runtime because you're using polymorphism in the interfaces.
Clean code because you avoid decision-statements (not complicated).
More clean code because you separate the concerns into classes (a class to each Strategy).
Decoupled and easily testable code.

When to Use the Strategy Pattern

When you need to use several algorithms with different variations, you need to create a concrete class to implement your algorithm.
When you see conditional statements around several related algorithms.
When most of your classes have related behaviors.

Components of SP

The pattern consists of three components; Context, Strategy, and Concrete Strategies.

Context — Scope, where we are using Strategy. For example, class PhoneNumber.
Strategy — Strategy is a common interface for Concrete Strategies. For example, interface IToStringStrategy.
Concrete Strategies — Concrete classes that are implementing a Strategy interface. For example, IrelandToStringStrategy.

Mostly, the Context holds the object of Strategy in field or property. We will apply the Concrete Strategy based on the incoming parameter and then execute the algorithm by invoking the Strategy's method.

Tutorial

Introduction of Project

Here is the repository with Project. It is a .NET Core console application with simple functionality. It detects whenever you press key 'C' for Czech or 'I' for Ireland. Depended on the pressed key, the application displays the Czech or Irish format of an exemplary phone number.

Console servers as a tool for switching CultureInfo of the application. CultureInfo is mostly driven by an environment like a browser or operating system, but for easier manipulation, I created a simple interactive console.

Strategy

Interface IToStringStrategy works like the prescription of Concrete Strategies. It contains the definition of ToString method receiving phone number value. Implementations of the defined method will convert and format phone number value.

IToStringStrategy.cs

Concrete Strategies

Next are Concrete Strategies of the phone number that are transforming the value into formatted string type.

For Czechia country is the typical format "+420 XXX XXX XXX". I googled that one of the Ireland telephone number formats is "+353 X XXXX XXXX".

Unchanging prefixes are defined as constants in the Prefixes class.

Prefixes.cs

Class CzechiaToStringStrategy holds the implementation of Czech phone numbers. I am using string interpolation for formatting. The syntax is short, readable, and string interpolation takes care of the conversion from long type by itself. After a colon, you can simply define where specific characters of converted value should be placed.

CzechiaToStringStrategy.cs

Class IrelandToStringStrategy implements Ireland's phone number formatting. It is using the same tools to brings the desired result.

IrelandToStringStrategy.cs

Context of Strategy

Class PhoneNumber serves as Context. It also contains ResolveStrategyByCulture method, which returns an instance of Concrete Strategy figured out from the value of CurrentCulture.Name. My application supports only Ireland or Czech culture, so otherwise, an exception will be thrown.

PhoneNumber.cs

Program

Last at the podium will be the Program class with Main method, which is an entry point of every console application in .NET and .NET Core frameworks.

Program.cs

As you can see, I am reading the incoming keys from keyboards and depend on the value I am setting CultureInfo.CurrentCulture. Next, the phone number object is initialized and printed on the screen.

I don't need to call Tostring method, because I am again using string interpolation, and method is invoked automatically.

Summary

Algorithms of ToString methods are dynamically switched by the user's action at runtime. You can reach the same goal with decision-statements, but it has its drawbacks.

The shown tutorial is a very simple demonstration of how to implement the strategy pattern in C# language. Its simplicity is also its weakness and it may leave you unconvinced to use the Strategy Pattern. Below I collect a few interesting links as more proof that taking advantage of the Strategy Pattern has its benefits.

Where next?

To more exploration of Strategy Pattern, I would recommend the Pluralsight course by Filip Ekberg; "C# Design Patterns: Strategy."

Take a look also at this blog post about Strategy Pattern and Dependency Injection. I found it very easy to understand.

You can always go back to the roots of Design Patterns by reading a book of Gang of Four; "Design Patterns: Elements of Reusable Object-Oriented Software."

Finally, if you want to explore more my work about design patterns, here are a few of them.

How to Dynamically Add Behaviors With Decorator Pattern

Decoupling with Chain of Responsibility Pattern in C#

How to manage states with State Design Pattern in C#?

Decoupling with Chain of Responsibility Pattern in C#

Digital Craft Workshop — Sun, 26 Apr 2026 13:13:11 +0000

The article cooperates with the sample project. Walkthrough with the downloaded project is not required, but I recommend it for better understanding.

The sample project consists of two different approaches to validating the user's data within a registration. Two processors simulate the user's registration process.

BasicUserRegistrationProcessor.cs follows the simple path of if statements.

public class BasicUserRegistrationProcessor
{
  public void Register(User user)
  {
    if (string.IsNullOrWhiteSpace(user.Username))
    {
        throw new Exception("Username is required.");
    }
    if (string.IsNullOrWhiteSpace(user.Password))
    {
        throw new Exception("Password is required.");
    }
    if (user.BirthDate.Year > DateTime.Now.Year - 18)
    {
        throw new Exception("Age under 18 is not allowed.");
    }
  }
}

ChainPatternRegistrationProcessor.cs is taking advantage of the Chain of Responsibility Pattern. This implementation applies the same set of validations.

public class ChainPatternRegistrationProcessor
{
  public void Register(User user)
  {
    var handler = new UsernameRequiredValidationHandler();
    handler.SetNext(new PasswordRequiredValidationHandler())
        .SetNext(new OnlyAdultValidationHandler());
    handler.Handle(user);
  }
}

Chain of Responsibility Pattern

Chain of Responsibility Pattern(ChoRP) is a pattern firstly presented in great book Design Patterns: Elements of Reusable Object-Oriented Software.

We can achieve loose coupling in software design by practicing ChoRP. The pattern is a very powerful yet pretty simple to implement in our applications. It allows us to easily decouple parts of code to make it more readable, testable, extensible, and maintainable.

ChoRP comes from a family of the behavioral pattern, also like State Pattern.

How to manage states with State Design Pattern in C#?

Components of ChoRP

ChoRP consists of three components.

Request
Abstraction of Handler
Concrete Handlers

One or more Concrete Handlers will take care of Request in the chained process. Mostly, the Request is some kind of contract or Data Transfer Object of the handling event. In the sample project, it is a User class.

public class User
{
  public string Username { get; set; }
  public string Password { get; set; }
  public DateTime BirthDate { get; set; }
}

I am usually using the interface and the abstract class together as the abstraction for the Concrete Handlers. It contains two methods; Handle and SetNext.

public abstract class Handler<T> : IHandler<T> where T : class
{
  private IHandler<T> Next { get; set; }
  public virtual void Handle(T request)
  {
      Next?.Handle(request);
  }
  public IHandler<T> SetNext(IHandler<T> next)
  {
      Next = next;
      return Next;
  }
}
public interface IHandler<T> where T : class
{
  IHandler<T> SetNext(IHandler<T> next);
  void Handle(T request);
}

T is a generic type of class which represents the Request. Method SetNext() sets a private property Next , which is subsequently invoked in the virtual method Handle(T request) .

Concrete Handler inherits from the abstract class Handler and implements an interface IHandler.

public class OnlyAdultValidationHandler : Handler<User>, IHandler<User>
{
  public override void Handle(User user)
  {
    if (user.BirthDate.Year > DateTime.Now.Year - 18)
    {
        throw new Exception("Age under 18 is not allowed.");
    }
    base.Handle(user);
  }
}

OnlyAdultValidationHandler class overrides Handle method of its parent but also invokes the parent's Handle the method at the end of the method's body. This is a crucial factor for chaining Concrete Handlers. Also, by inheriting from the Handler class, the OnlyAdultValidationHandler gains SetNext method threw which we will set another chain segment.

Chaining Handlers

First, you need to set up the chain via the SetNext method. The method returns IHandler type so you can set Handlers in a row.

SetNext(new Handler()).SetNext(new Handler())

Once we finish the chain definition, we can continue by invoking Handler.Handle(request) which will call base.Handle(user) therefore Next?.Handle(request) ensures that the chain reaction is triggered.

Drawbacks of Coupled Implementations

Why so much workaround? The basic implementation looks much more straightforward and readable than ChoRP implementation, right?

Well, it is not clear at first look, but those validations are tightly coupled. Password Validation is dependent on the result of Username Validation. Only Adult Age Validation is dependent on the result of previous validations.

It is even more evident if you write unit tests that are going to test different scenarios of user registration. You are not able to test Password Validation without introducing value into the user's Username property.

public class BasicUserRegistrationTests
{
    [Fact]
    public void When_Username_Is_Empty_Then_Exception
    _Should_Be_Thrown()
    {
        //Arrange
        var user = new User();
        //Act
        Action act = () => new BasicUserRegistrationProcessor()
        .Register(user);
        //Assert
        act.Should().Throw<Exception>();
    }
    [Fact]
    public void When_Password_Is_Empty_Then_Exception
    _Should_Be_Thrown()
    {
        //Arrange
        var user = new User
        {
            Username = "Daniel Rusnok"
        };
        //Act
        Action act = () => new BasicUserRegistrationProcessor()
        .Register(user);
        //Assert
        act.Should().Throw<Exception>();
    }

But once you apply a ChoRP, then you are not only able to test Password Validation result, but also you are able to test both possible results of Password Validation which are Throw<Exception> when the password property is empty and NotThrow<Exception> when the password property is filled.

public class ChainPatternRegistrationTests
{
    [Fact]
    public void When_Password_Is_Empty_Then_Exception
    _Should_Be_Thrown()
    {
        //Arrange
        var user = new User{Password = string.Empty};

        //Act
        Action act = () => new PasswordRequiredValidationHandler()
        .Handle(user);

        //Assert
        act.Should().Throw<Exception>();
    }

    [Fact]
    public void When_Password_Is_Filled_Then_Exception
    _Should_NOT_Be_Thrown()
    {
        //Arrange
        var user = new User{Password = Guid.NewGuid().ToString()};

        //Act
        Action act = () => new PasswordRequiredValidationHandler()
        .Handle(user);

        //Assert
        act.Should().NotThrow<Exception>();
    }

With BasicUserRegistrationProcessor we are only able to test if Password Validation NotThrow<Exception> when the whole user object is valid. And this is the biggest demonstration of how basic registration implementation is coupled.

[Fact]
public void When_All_Properties_Are_valid_Then_Exception_Should_NOT_Be_Thrown()
{
    //Arrange
    var user = new User
    {
        Username = "Daniel Rusnok",
        Password = Guid.NewGuid().ToString(),
        BirthDate = DateTime.Now.AddYears(-20)
    };
    //Act
    Action act = () => new BasicUserRegistrationProcessor()
    .Register(user);
    //Assert
    act.Should().NotThrow<Exception>();
}

Summary

The power of decoupling is not only in its independent testability but also in its reusability. Such a Handler does not always have to accept a concrete type as a parameter. It can take an abstraction of the specific type like an interface.

Multiple types of Requests can implement such an interface. In such situations, the Handler becomes useable for various processes, and you are not repeating yourself. So ChoRP also supports the DRY.

Soft-deleting Postgres rows without losing the URL slug

Digital Craft Workshop — Fri, 10 Apr 2026 17:17:11 +0000

Six lines of code that let you release a unique-constrained slug back into the namespace without dropping the constraint.

I want soft-delete on my blog posts. I also want slug to be UNIQUE NOT NULL. These two requirements quietly fight each other, and the standard fixes — partial unique indexes, deleted_at IS NULL predicates, separate archive tables — are all heavier than what I needed.

Here's the six-line trick I shipped instead.

The conflict

A blog post has a URL slug like my-cool-post. I want UNIQUE on slug so I can serve /blog/my-cool-post without ambiguity. I also want DELETE to be soft — set status = 'archived' so I can recover the post if I change my mind, and so historical analytics don't get orphaned.

Now the user re-uses the title "My Cool Post" two months later. They want a fresh post at /blog/my-cool-post. The INSERT fails because the archived row still owns the slug.

Master TypeScript as a C# Developer

Get 5 practical emails covering the exact TypeScript concepts that trip up C# developers.

drippery.app

Standard answers:

Partial unique index: CREATE UNIQUE INDEX ON posts(slug) WHERE status != 'archived'. Works, but it's a separate index to maintain and it doesn't handle the case where you want to look up the archived post by its old slug at all (your /blog/<slug> lookup needs to know the old slug is gone).
deleted_at IS NULL everywhere: Now every query needs a predicate. One missed WHERE and you leak archived data.
Separate archived_posts table: Schema duplication, two places to query, FK headaches with analytics tables that point at posts.id.

The trick

When you archive, rename the slug. Append -archived-${Date.now()}:

const archivedSlug = `${post.slug}-archived-${Date.now()}`;

await db
  .update(blogPosts)
  .set({
    status: "archived",
    slug: archivedSlug,
    updatedAt: new Date(),
  })
  .where(eq(blogPosts.id, post.id));

await revalidatePath(`/blog/${post.slug}`);
await revalidatePath("/blog");

That's it. Six lines of business logic.

What this gives you

The original slug is now free. The next INSERT of a post titled "My Cool Post" succeeds with no contention.
The unique constraint stays a plain UNIQUE NOT NULL — no partial index, no predicate, no rewrites of every query.
The archived row is still queryable by ID, by status, by content. You haven't lost anything.
The timestamp suffix makes collisions impossible across multiple archive/restore cycles. Date.now() is millisecond-precise; you won't archive two posts within the same millisecond unless you're shipping at scale I'm not at.
The old URL stops resolving, which is exactly what you want for a deleted post. revalidatePath flushes the ISR cache so the public-facing site reflects the deletion immediately.

What this doesn't give you

Restore doesn't auto-rename back. If you want a "restore" action, you need to handle the case where the original slug is now occupied by a newer post — typically by appending -2 or by failing with a 409 and asking the user to pick a new slug. I haven't built restore yet because nobody's asked for it.
Search engines that already indexed /blog/<old-slug>-archived-1234 will get a 404 when they re-crawl. This is correct behavior for deleted content. If you instead want a 410 Gone, add a route handler that detects the -archived- suffix and returns 410.
Audit trails get noisy slugs. Your activity log will show my-cool-post → my-cool-post-archived-1739812340000. If that bothers you, store the original slug in a separate original_slug column at archive time, and use it for display.

When this is the wrong tool

If you need to keep the archived URL working for legal or SEO reasons (e.g. blog posts that shouldn't 404 because they're cited from elsewhere), this pattern is wrong. You want the partial unique index approach instead, and a "tombstone" version of the page that explains the post was archived and links to a successor.

But if archive means "this is gone, the URL should die, and I want to be able to reuse the title later" — and that's the common case for blog post archives — six lines of slug-renaming is all the complexity you need.

The schema

For completeness, the relevant column on drippery_blog_posts:

slug: varchar("slug", { length: 255 }).notNull().unique(),
status: varchar("status", { length: 20 }).notNull().default("draft"),

No partial index. No deleted_at. No second table. Just UNIQUE on the slug, a status column, and a six-line archive handler that renames the slug on the way out.

Sometimes the best soft-delete is the one that briefly hard-deletes the namespace.

The blog engine behind this post is part of Drippery — a drip email tool I'm building for creators who want automated email sequences without the $39/month price tag.

Want the Claude Code memory setup I build with? The Claude Code Memory Starter is a free email series.

5 Functions, 1 Route, $0/Month: My Entire SaaS Background Job Architecture

Digital Craft Workshop — Thu, 09 Apr 2026 18:51:16 +0000

BullMQ needs Redis. Cron has no retries. I needed background jobs that can sleep for 48 hours, fan out to parallel workers, and survive server restarts — without paying for infrastructure I don't have users to justify yet.

I replaced the entire Redis + BullMQ + cron + monitoring stack with five Inngest functions. Total cost: $0.

AI as a Solo Founder's Tool

A 5-part email series on using AI as more than a search engine — for building, marketing, and shipping alone.

drippery.app

The Full Picture

Drippery — my drip email SaaS — runs five background functions. Together they cover scheduled email delivery, DNS domain verification polling, orphaned file cleanup, and beta user lifecycle.

All five are registered in one Next.js API route. Inngest calls it via webhook. No Redis, no worker process, no cron container.

Here's what that replaces:

Without Inngest	With Inngest
Redis instance (~$10/month on Render)	Nothing
BullMQ worker process	Nothing
Cron container or external service	Nothing
Manual retry logic	Built-in, per-step
Observability dashboard	Inngest dashboard (free)
Distributed locking for cron	Handled automatically
Long-running job persistence	`step.sleep()`
Fan-out worker pool	`step.sendEvent()`

Let me walk through each function.

The Email Pipeline: Scheduler + Parallel Sender

The core email system is a two-function pipeline. The scheduler runs every 15 minutes and asks: which subscribers are due for their next drip email?

export const sendPendingEmails = inngest.createFunction(
  { id: 'send-pending-emails', triggers: [cron('*/15 * * * *')] },
  async ({ step }) => {
    const subscribers = await step.run('fetch-subscribers', async () =>
      findActiveSubscribersWithSequences()
    );

    // For each subscriber: find next due email, check dayOffset + send window
    // Dispatch one event per match
    await step.sendEvent('dispatch', eventsToDispatch);
  }
);

It walks through each active subscriber, finds their position in the sequence, and checks if enough days have passed.

Creators in different timezones shouldn't get emails at 3 AM — the scheduler verifies the current time matches the tenant's preferred send window before dispatching anything.

The key decision: fan-out. Instead of sending emails inside the loop, the scheduler dispatches email/send events. Each event triggers a separate function invocation.

50 subscribers due = 50 parallel runs. No worker pool, no concurrency config.

The other critical detail: drip semantics. One email per subscriber per tick, never the whole sequence at once.

Each email/send event triggers the sender — one subscriber, one email, full isolation:

export const sendSingleEmail = inngest.createFunction(
  { id: 'send-single-email', triggers: [{ event: 'email/send' }] },
  async ({ event, step }) => {
    const { subscriberId, emailId, tenantId } = event.data;

    const [subscriber, email, tenant] = await step.run('fetch-data', async () =>
      fetchEmailContext(subscriberId, emailId, tenantId)
    );

    const finalHtml = replaceMergeTags(email.html, mergeTags);

    await step.run('send-email', async () =>
      sendEmail(subscriber.email, finalSubject, finalHtml)
    );

    await step.run('record-sent', async () =>
      db.insert(sentEmails).values({ subscriberId, emailId, sentAt: new Date() })
    );
  }
);

Each step.run() is independently retryable. If the Resend API times out on send-email, only that step retries — the DB fetch doesn't re-execute.

If the server crashes after sending but before recording, Inngest resumes at record-sent. No double-sends, no lost records.

The 48-Hour Function: Domain Verification Polling

This is the function I couldn't have built with BullMQ — at least not without a lot of scheduling glue.

When a user adds a custom sender domain, Drippery registers it with Resend and starts polling for DNS verification. This can take 5 minutes or 24 hours — you don't know upfront.

export const checkDomainVerification = inngest.createFunction(
  { id: 'check-domain-verification', triggers: [{ event: 'domain/check-verification' }] },
  async ({ event, step }) => {
    const { senderDomainId, attempt = 1 } = event.data;
    const MAX_ATTEMPTS = 576; // 48 hours at 5-minute intervals

    const result = await step.run('check-resend', async () => {
      const resend = new Resend(process.env.RESEND_API_KEY);
      return resend.domains.get(domain.resendDomainId);
    });

    if (isVerified) return { status: 'verified', attempts: attempt };

    await step.sleep('wait', '5m');
    await step.sendEvent('next-check', {
      name: 'domain/check-verification',
      data: { senderDomainId, attempt: attempt + 1 },
    });
  }
);

This function can run for up to 48 hours. step.sleep() suspends the function, frees server resources, then resumes exactly where it left off.

With BullMQ, you'd need explicit delayed job scheduling, persistence logic, and retry handling. Here it's one line: await step.sleep('5m').

The Maintenance Jobs: Cleanup + Beta Lifecycle

The remaining two functions are simpler but follow the same pattern.

Orphan image cleanup runs every Sunday at 3 AM. It compares images in Cloudflare R2 against database references and deletes anything unreferenced:

export const cleanupOrphanImages = inngest.createFunction(
  { id: 'cleanup-orphan-images', triggers: [cron('0 3 * * 0')] },
  async ({ step }) => {
    const r2Keys = await step.run('list-r2', async () => listAllObjects());
    const dbKeys = await step.run('get-refs', async () => extractReferencedUrls());
    const orphans = r2Keys.filter(k => !dbKeys.has(k));
    await step.run('delete', async () => deleteObjects(orphans));
  }
);

Email images are excluded — once delivered, they can't be deleted without breaking past recipients' inboxes.

Beta expiry runs daily at 9 AM. It warns testers 3 days before their 14-day trial ends, then downgrades them:

export const checkBetaExpiry = inngest.createFunction(
  { id: 'check-beta-expiry', triggers: [cron('0 9 * * *')] },
  async ({ step }) => {
    const warningTesters = await step.run('find-warning', async () =>
      findTenantsByBetaWindow(3, 4)
    );
    for (const tenant of warningTesters) {
      await step.run(`warn-${tenant.id}`, async () => {
        await sendWarningEmail(tenant);
        await markWarned(tenant.id);
      });
    }
  }
);

Each tenant gets its own step.run(). If one tenant's email lookup fails, only that step retries — the rest still get processed.

The Cost

Inngest's free tier gives you 50,000 executions per month. My actual usage is well under 10,000 — scheduler ticks, dispatched sends, daily and weekly jobs.

For an early-stage SaaS, the free tier has plenty of headroom.

When I outgrow it, paid plans start at $75/month. By that point, I'll have enough paying users to cover it. That's the scaling curve I wanted.

What's Next

Five functions today. The next one will probably be a subscriber re-engagement job — if someone hasn't opened the last 3 emails, automatically pause their sequence and notify the tenant.

Same pattern: one more function file, zero infrastructure changes.

The entire background job layer of my SaaS is five TypeScript functions, one API route, and zero managed services. When you're building alone, that's the architecture that lets you ship.

If you're curious about Drippery — dead-simple drip email sequences for creators, starting at $0/month — check it out at drippery.app.

I write weekly about what I'm shipping and what's breaking on Substack.

I Thought I Understood Git. Then I Actually Learned the Difference Between Rebase and Merge.

Digital Craft Workshop — Wed, 25 Mar 2026 13:27:36 +0000

I used git rebase long before I actually understood what it does.

I picked it up from a senior developer on my first team. The rule was simple: always rebase before you merge, keep the history clean.

I followed it. I typed the commands. I never questioned it.

Then one day I rebased the wrong branch and rewrote a week of shared history. That was the day I finally sat down and learned what I had been doing.

What merge actually does

git merge takes two branches and joins them. It creates a new commit — a merge commit — that has two parents: the tip of your branch and the tip of the branch you're merging into.

# You're on feature/my-feature
git merge main

The result is a non-destructive operation. Nothing is rewritten. Your history grows a new node with two parents, and both lines of development are preserved exactly as they happened.

      A---B---C  feature
     /         \
D---E---F---G---H  main (merge commit)

The upside — it's safe.

The downside — if you merge large feature branches frequently, the commit history can become harder to read.

What rebase actually does

git rebase moves your commits. It takes the commits on your branch and replays them on top of another branch, one by one, as if you had started your work from there.

# You're on feature/my-feature
git rebase main

# Before
      A---B---C  feature
     /
D---E---F---G  main

# After
              A'--B'--C'  feature
             /
D---E---F---G  main

Notice the prime marks — A', B', C' are new commits. Same changes, new hashes. Rebase rewrites history.

The upside — your history looks linear and clean.

The downside — if anyone else has those original commits (A, B, C), their history now diverges from yours. This is what I did wrong.

The golden rule of rebase

Never rebase commits that exist outside your local repository.

If you've pushed a branch and someone else has pulled it, rebasing rewrites commits they already have. Their history diverges. Pulling becomes painful. You'll see duplicate commits, conflicts that make no sense, and a very confused colleague.

The safe version — rebase only your local, unpushed work. Once commits are shared, merge.

# ✅ Safe — rebasing local work before pushing
git rebase main
git push origin feature/my-feature

# ❌ Dangerous — rebasing already-pushed commits
git push origin feature/my-feature  # already done
git rebase main                      # rewrites shared history
git push --force                     # now you've broken everyone else

Interactive rebase

Once you understand what rebase does, git rebase -i becomes one of the most useful tools in Git.

It lets you rewrite your local commit history before you share it — squash messy WIP commits into clean ones, reorder commits, edit commit messages, or split a large commit into smaller ones.

# Rewrite the last 3 commits interactively
git rebase -i HEAD~3

This opens an editor where you choose what to do with each commit:

pick a1b2c3 Add order validation
pick d4e5f6 fix typo
pick g7h8i9 WIP: still debugging

# Change to:
pick a1b2c3 Add order validation
squash d4e5f6 fix typo
drop g7h8i9 WIP: still debugging

The result — one clean commit instead of three messy ones.

This is what "clean history" actually means in practice — not avoiding merge commits, but being intentional about what you leave behind.

When to use which

Use merge when:

Integrating a completed feature branch into main or develop
Working on a shared branch where others have the same commits
You want to preserve the full context of when and how branches diverged
Merging release branches or hotfixes where an audit trail matters

Use rebase when:

Updating your local feature branch with changes from main before pushing
Cleaning up local commit history before opening a PR (with -i)
Keeping a long-lived feature branch up to date with the base branch
Working solo on a branch nobody else has touched

Never rebase:

Commits that have already been pushed and shared
main, develop, or any branch others are working from

The workflow that actually works

In practice, most teams land somewhere between "always merge" and "always rebase." Here's a workflow that's served me well:

Work locally on a feature branch
Before opening a PR, git rebase -i to clean up commits
git rebase main to update your branch with latest changes
Push and open the PR
Merge the PR into main (with a merge commit or squash merge — team's call)

This gives you a clean PR history while preserving the merge commit that marks when a feature landed in main. Best of both approaches.

What I wish I had understood earlier

Rebase and merge aren't competing philosophies. They're different tools for different moments in a workflow.

Merge preserves history. Rebase rewrites it. Both are useful — but rewriting shared history is always a mistake.

I learned that the hard way. The senior developer who taught me to "always rebase" wasn't wrong — he just assumed I understood what rebase does. I didn't. I copied the command without understanding the consequence.

Now I understand both. And I still rebase — just never the wrong branch.

How does your team handle this? Do you have a strict rebase-only policy, or do you let developers decide? I'm curious whether the "clean history" argument is still winning in 2026. 👇

DEV Community: Digital Craft Workshop

Four Reason to Change your Software

CLEAN CODE & REFACTORING

Four Reasons to Change your Software

Four main reasons to change are

Adding Feature and Bug Fixing

Design Improvement and Optimisation

Refactoring

Optimisation

Summary

Related Reading

Developers are introverts. Domain-driven design can help.

Developers are introverts. Domain-driven design can help to change it.

As developers, we are writing code to build software, but we can’t make good software without talking to clients.

Developers aren’t chatty.

Domain-driven design intervention

Ubiquitous language

Domain and subdomains

Benefits

Disadvantages

The Book

Summary

Related Reading

Recipe to greatly layered architecture!

Recipe to greatly layered architecture!

Why onion?

Onion Architecture

Summary and useful links

Related Reading

My introduction into Azure Service Fabric

Azure & Cloud

My Introduction into Azure Service Fabric

As a monolithic application developer, I was challenged by my CEO to learn something more about an Azure Service Fabric technology. I would like to share with you what I have learned in the last few weeks.

Microservice architecture

Cluster

Node

Application

Stateful and Stateless service

Actor service

Related Reading

3 Things That Bit Me Before My Claude Code Memory Setup Worked

1. The hook that triggered itself

2. The embedder that cooked my laptop

3. The frontier model that quietly ate my credits

What the three have in common

Further Reading

Captions That Read Along, One Word at a Time

Why captions at all

Why ASS, not a caption library

The karaoke tag is the whole trick

Pinning it so it never jumps

The one-line bug that highlighted the wrong word

When scenes don't start at zero

Burning it in

What's still flat

3 Domain-Centric Architectures Every Software Developer Should Know

SOFTWARE ARCHITECTURE & REFACTORING

3 Domain-Centric Architectures Every Software Architect Should Know

The first concern of the architect is to make sure that the house is usable; it is not to ensure that the house is made of brick. — Uncle Bob

Domain

Core Domain

Supporting Domain

Generic Domain

Summary

Domain-Centric Architecture

Hexagonal Architecture

Onion Architecture

Domain Layer

Repository Layer

Service Layer

UI Layer

Pros

Cons

Clean Architecture

Entities

Use cases

Interface adapters

Frameworks & Drivers

Summary

Pros