Forem: nomad4tech

SOLID was written for this moment

nomad4tech — Mon, 27 Apr 2026 13:35:31 +0000

If You dont write code - who you are?

Everyone is talking about prompts. About token budgets. About cognitive surface. But I think we're still looking at the wrong unit.

The unit is the interface boundary. Always was.

Back before any of this existed

Back when I was writing SQL scripts and mappers by hand, I already had this principle baked into how I worked: every module should know only its contract. Not where the data came from. Not where it goes. Just: here's input, here's output, here's the guarantee.

Think of it like a bakery. The baker doesn't care if the flour came from the warehouse or yesterday's leftover stock. Doesn't care where the bread ends up - the store shelf, a restaurant, a catering order. He just bakes. His job is defined by its boundaries, not by the full supply chain.

That's how I tried to design every system. Each module gets a clear spec. It does its one job. It exposes a clean interface. It knows nothing about its neighbors' internals.

Why it worked then

The benefits were practical and immediate:

Easier to test - validate each piece in isolation
Easier to mock - swap out any dependency without touching the rest
Easier to hand off - a new developer can own a module without understanding the whole system
Easier to explain - narrow scope means clear documentation
Easier to replace - swap implementations without breaking contracts

Different developers could work on different modules in parallel. The system remained understandable even as it grew. Each piece was small enough to reason about, flexible enough to move.

This was the goal before generative AI existed. Before vibe-coding was a word. Before anyone was talking about agents.

What changed with LLMs

The developer is now Claude Code, Cursor, or whatever agent you're using.

And here's the thing - a senior AI developer needs exactly what a senior human developer needs: a clear spec, a narrow scope, and no hidden dependencies.

The same reasons this worked with human developers make it work with agents. The principles didn't change. The developer did.

Principle	With AI
Easier to test	Generated code lives in one small module - trivial to test without touching the rest
Easier to mock	Try different implementations, swap models, experiment freely - the contract holds
Easier to hand off	Drop 5 files into context instead of scanning an entire repo. The model gets exactly what it needs, nothing more
Easier to explain	A narrow module is a narrow prompt. Less ambiguity, fewer hallucinations
Easier to replace	If the generated code doesn't fit - throw it away and regenerate. The interface survives

A well-isolated module with a clean interface can be handed to an agent with a minimal prompt and a clear contract. The agent doesn't need to understand your entire codebase. It needs to understand this boundary - what comes in, what goes out, what the guarantee is.

The rest of the system doesn't care how that module was built. The interface is the guarantee.

The real shift

We're not developers anymore. We're architects.

The generative AI is our senior dev. Our job is to design the factory floor - the contracts, the flows, the boundaries, the guarantees. Not to run the machines.

This is a mindset shift, not just a workflow change. When you stop thinking "how do I write this code" and start thinking "how do I design this boundary so that anyone - or anything - can implement it correctly", the whole game changes.

Your value is no longer in writing the implementation. It's in designing a system where every implementation slot is small, clear, and replaceable.

The founding fathers weren't early. They were right.

SOLID didn't become obsolete with generative AI and vibe-coding.

It became urgent.

Robert Martin wrote about single responsibility, open/closed design, dependency inversion - principles that make systems maintainable, modular, and understandable. At the time, these were best practices for teams of human developers.

Turns out they're also the exact principles that make a system agent-friendly.

Small responsibilities. Clean interfaces. No hidden coupling. Contracts over implementations.

If you haven't revisited Uncle Bob lately, maybe now is the time. Not because the principles are new. Because we finally have a use case that makes their value undeniable.

The prompt is not the unit of architecture. The interface boundary is.
It always was.

I Tired of Trusting Bash Scripts With My Backups

nomad4tech — Mon, 27 Apr 2026 11:24:56 +0000

TL;DR: I created a self-hosted web UI tool for PostgreSQL/MySQL/MariaDB backups from Docker containers. Auto-discovers containers, runs dumps inside them (so pg_dump always matches your DB version), no credentials in config files. Free, MIT licensed, Linux only

One docker compose up - your databases, backed up

GitHub: https://github.com/nomad4tech/backup-manager

Docker Hub: https://hub.docker.com/r/nomad4tech/backup-manager

Short Demo: https://youtu.be/3rXkPmOpDNc

How I got here

I've used and seen others use bash scripts for backups. Usually it's a massive script, or a set of scripts and pipelines - at minimum: create a dump, compress it, upload to S3, delete old files. All wired up via cron or systemd.

I've watched this approach fail in ways that hurt:

someone deleted the crontab. ("crontab -r" instead of "crontab -e" its terrifyingly easy to mistype, and you won't even notice)
someone deleted the backup script itself during a cleanup
dump silently failed because there wasn't enough disk space, or the database container was restarted mid-dump

In every case, we found out the same way: when a restore was actually needed, and the last backup was five months old.

I'm a Java developer and an aspiring vibe coder (not sure whether to be proud or embarrassed about that). At some point, in my free time, I decided to solve this for myself - it was supposed to be a simple JAR: a config file, a backup pipeline, notifications. That's it.

Then I added an API. Then a frontend. Then it kept going...

The app grew into a proper self-hosted tool. I played around with Docker Hub and GitHub,and at some point I wanted to take it further - to build something useful for the community. Something approachable, lightweight, and worth maintaining as an open-source project.

Why "just use pgBackRest/restic/Barman" wasn't my answer

My answer: those are better tools for serious workloads. If you need incremental backups, WAL archiving, point-in-time recovery - go use pgBackRest. It's excellent - I have a lot to learn from it.

But my situation was simpler: multiple servers, multiple Docker-based projects, databases living in containers. I wanted to open a UI, create a task, and not think about it again.

bash script - I write it, I maintain it, I remember to add rotation, error handling, disk space checks. I already did that. Then I built this.
restic - powerful, but no Docker-native workflow, no UI, setup per-project.
pgBackRest - its own config system, its own repository concept. Overkill for "give me a daily dump and email me if it fails."

Backup Manager is for people who want to click a button, not write a config.

The core idea: one place to manage all your backups

The original problem wasn't just "automate a dump." It was: multiple servers, multiple Docker containers, no single place to see what's backed up and what isn't.

The solution I wanted was simple - connect to any server, pick a container and DB, set a schedule, done. Everything in one UI. No SSH-ing into machines to check cron logs, no wondering if the script on server #14526 is still running.

The technical decision that makes this work cleanly: Backup Manager runs dumps inside the container via Docker exec API, not on the host. Three things fall out of this naturally:

1. pg_dump always matches your database version. No "client/server version mismatch" errors. Ever. The binary is the one that shipped with your database image.

2. No credentials in config files. You don't even need to know database credentials at all. PostgreSQL resolves $POSTGRES_USER/$PGPASSWORD from the container's environment. MySQL uses $MYSQL_ROOT_PASSWORD. The backup tool never sees them - they're resolved at dump time, inside the container.

3. Data streams directly to the app host. No temporary files on the database server. No memory buffering regardless of database size. For large databases this matters.

A few other things worth knowing

Auto-discovery. The app finds database containers automatically - you pick from a list, not a config file. Database size is shown in the selection screen.

Disk space pre-flight. Before every dump, free space is checked against 1.5× the size of the previous dump. If there isn't enough room, the dump won't start.

File rotation. Set how many backups to keep. Old files are deleted automatically after each successful backup.

Remote servers via SSH. Add an SSH connection and all databases on that host appear in the same UI. The Docker socket is proxied through the SSH tunnel - it's never exposed directly to the network. This works the same way Portainer and Watchtower handle it.

S3 upload is optional. AWS, MinIO, Yandex Cloud, or any S3-compatible storage. If S3 is unavailable, the dump still runs and saves locally.

Email notifications on success and failure. Multiple recipients supported - useful when a backup task belongs to a shared server and more than one person needs to know if something breaks

Heartbeat monitoring. The app pings healthchecks.io (or any compatible service) by schedule. If the app goes down - you get an alert. If the monitoring service itself goes down - Backup Manager emails you. Silence is a signal, not a green light.

Deployment

services:
  backup-manager:
    image: nomad4tech/backup-manager:latest
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - ./backups:/app/backups
    environment:
      - SPRING_PROFILES_ACTIVE=docker

docker compose up -d

Local Docker socket is detected automatically. Default login: admin / admin - change it immediately in Settings -> Account.

What else is included

Gzip compression enabled by default, per task
Test S3, email, and heartbeat integrations directly from the UI before saving
Inline task editing - no need to recreate tasks to change a schedule
Full backup history with details
REST API with Swagger documentation
Container re-creation via docker-compose down/up doesn't break tasks - containers are resolved by name, not ID

Limitations (being honest)

Linux only - Windows and macOS are on the roadmap
Early stage - tested on databases up to ~500 GB, but edge cases are still being found
AI Involvement - I used AI coding assistants to speed up development. However, all architectural decisions, core logic, and testing strategies are entirely mine
- 💡 A Note on the UI I’m a Java dev, not a frontend engineer. I’ll be honest: the web interface was 100% generated by AI assistants. My role was defining the UX flow, API contracts, and wiring it all together. It’s a testament to how far developer tools have come
Single maintainer - that's me! Response times may vary depending on my availability, but feedback is always welcome

What's next

UI-based restore, backup encryption, webhooks, MongoDB support, incremental backups...

Why I'm sharing this now

This is my first self-hosted tool I'm putting out publicly. It's not perfect. But I use it on my own production servers, and it does exactly what I built it to do.

The best thing that can happen to it at this stage is real-world usage on setups I didn't anticipate - databases I haven't tested, network configs I haven't seen, edge cases I haven't hit.

If this looks useful - try it and break it. -> https://github.com/nomad4tech/backup-manager

Issues, stars, and feedback all help. If something breaks or doesn't work the way you expect - open an issue. That's genuinely the most valuable thing anyone can do for the project right now.

Building a Minimal Telegram Bot Library for Java - Handler Chain Pattern

nomad4tech — Sun, 15 Feb 2026 18:51:12 +0000

I needed a Telegram bot for a side project. Looked at existing Java libraries - they're packed with features I didn't need. All I wanted was to send API requests and route updates to handlers based on logic I control. So I built my own thin wrapper.

The Problem

Most Telegram bot libraries for Java come with:

Heavy abstractions (command frameworks, conversation flows, state machines)
Opinionated architectures
Dependencies you might not want

For a simple bot that monitors groups and sends notifications, this felt like overkill. I wanted:

Direct access to Telegram API
Custom routing logic without fighting a framework
Minimal dependencies (just HTTP client + JSON)
Works standalone or drops into Spring Boot

But the real issue wasn't features - it was cognitive overhead. Every library has its own mental model: "our way of structuring commands," "our conversation state system," "our middleware pipeline." You spend time learning the library's abstractions, hunting through docs for configuration options, debugging implicit behaviors that aren't mentioned anywhere.

And then you hit the edge cases. The library does 90% of what you need, but that last 10% requires fighting the framework. You're three layers deep in someone else's architecture trying to figure out why your handler isn't firing, or why metrics are being logged to a format you don't use.

Sometimes it's easier to write your own "bicycle" - but one that takes you from point A to point B, not one that tries to perform heart surgery and deliver a newspaper on the way. I just wanted to call Telegram API and route updates. Why learn someone else's architecture for that?

The Solution: Handler Chain

The core idea is simple - each handler decides if it processes an update:

@FunctionalInterface
public interface UpdateHandler {
    boolean handle(Update update);
}

Return true → "I handled it, stop the chain"

Return false → "Not mine, try next handler"

That's the entire pattern. No magic, no annotations, no forced structure.

Example Handler

@Component
public class StartCommandHandler implements UpdateHandler {

    private final TelegramApiClient apiClient;

    @Override
    public boolean handle(Update update) {
        if (update.getMessage() == null || 
            !"/start".equals(update.getMessage().getText())) {
            return false; // not my update
        }

        apiClient.sendMessage(chatId, "Hello!");
        return true; // handled, stop chain
    }
}

No base classes. No decorators. Just: check condition → do work → return boolean.

Why This Works

Single Responsibility: Each handler has one job. StartCommandHandler only cares about /start. ButtonsCallbackHandler only cares about button clicks. They don't know about each other.

Composable: Dispatcher is itself an UpdateHandler. You can nest dispatchers, filter updates through pre-handlers, build trees of logic - it's just function composition.

Spring-friendly: In Spring Boot, all handlers auto-wire:

@Bean
public UpdateDispatcher dispatcher(List<UpdateHandler> handlers) {
    return new UpdateDispatcher(handlers); // Spring injects all beans
}

Spring collects every @Component implementing UpdateHandler and passes them in. No manual registration needed.

Design Philosophy: Obvious Defaults

I wanted zero cognitive load to get started. Call new TelegramApiClient(token) and it just works. Connection pooling? Configured. Retry logic? Enabled. Polling timeout edge cases? Handled automatically.

You only configure when defaults don't fit:

Need a proxy? Pass a custom OkHttpClient
Want different timeouts? Use TelegramApiConfig.builder()
Otherwise? Just use the constructor, it works

Same with handlers - no decorators, no registration APIs, no config files. Implement the interface, return a boolean, done.

Adding features means adding classes, not complexity. Want button handling? Write ButtonsCallbackHandler. Want admin commands? Write AdminCommandHandler. Each new feature is a new handler class - the core stays unchanged.

This means the library has limited built-in functionality. But that's intentional. I'd rather give you 5 simple building blocks than one complicated configuration system that tries to handle everything.

Production Details

A minimal library still needs production-grade internals:

Connection pooling: OkHttp with configurable pool size, keep-alive, timeouts. Defaults tuned for Telegram API (single host, long-lived connections).

Retry logic: Exponential backoff for transient errors (network issues, 5xx responses). But NOT for getUpdates - long polling already has offset-based recovery built in.

Polling timeout quirk: This took me hours to debug. Telegram holds the long polling connection for up to 30 seconds if no updates arrive. If OkHttp's readTimeout ≤ pollingTimeout, it kills the connection before Telegram responds, and the polling loop stops.

The library handles this automatically - it dynamically adjusts readTimeout per-request to always exceed the polling timeout by 35 seconds. Works regardless of what timeout value you configure.

Graceful shutdown: stopPolling() interrupts the polling thread immediately via thread.interrupt(). No waiting for the 30-second timeout to expire.

TelegramBotPollingService service = new TelegramBotPollingService(
    apiClient, dispatcher, true // autoStart
);
// Polling runs in background, shutdown hook stops it on exit

What I Learned

Simplicity scales. The library is ~500 lines of code. No command router, no conversation state, no wizard builders. Just: here's the API, here's the update, return true/false. Users build their own patterns on top.

OkHttp internals matter. That readTimeout > pollingTimeout bug cost me hours. The fix is simple once you know it, but debugging "why does my bot stop every 30 seconds" was painful.

Spring's auto-wiring is powerful. Letting Spring inject List<UpdateHandler> means users just write @Component handlers and they auto-register. Zero configuration boilerplate.

Open source infrastructure is real work. I thought "publish to GitHub" meant pushing code. Turns out you also need: proper Maven POM, package repository setup, README with examples, social preview images, release notes. The code was maybe 60% of the effort.

First Open Source Library

This is my first time publishing an open source project. I built it for myself, then spent time cleaning it up, writing documentation, and setting up proper packaging. Not gonna lie - there's some impostor syndrome around releasing code publicly, even though I use it in production and it works fine.

But that's kind of the point of open source, right? Share what works for you, maybe it helps someone else. If it doesn't, no harm done.

Repository: https://github.com/nomad4tech/telegrambot4j

Example project: https://github.com/nomad4tech/telegrambot4j-demo

The demo shows handlers for commands, inline buttons, and callback handling. Copy-paste starting point if you want to try it.

When NOT to Use This

If you need:

Complex conversation flows with state tracking → use a framework
Built-in command parsing, permissions, middleware → heavier libraries have this
Webhooks → currently only long polling supported

This library is for people who want direct API access with minimal abstraction. If you're building a complex chatbot with branching conversations, you probably want more structure than this provides.

Takeaway

Not every project needs a framework. Sometimes the best abstraction is almost none at all - just enough structure to avoid repeating yourself, not so much that it dictates how you work.

If you're building a Telegram bot in Java and existing libraries feel too heavy, give this a shot. And if you find bugs or want features, PRs welcome - learning as I go here.