DEV Community: nomad4tech

I built a time tracker without touching the code: declarative architecture programming with Claude

nomad4tech — Sun, 04 Oct 2026 13:35:40 +0000

I ran an experiment: build a complete product without writing or editing a single line of code myself. Not a script, not a prototype - a web app with a backend, a database, a phone layout, an installable PWA, a Chrome extension and a landing page. In my spare time after my regular job, over a few days.

Before the "even a time tracker needs vibe coding" comments: yes, I know, a time tracker is not a spaceship. I am a backend developer, and everything under the hood (the API, the database, the modules) I could have written by hand, without any model. It was planned and designed by me, and the model only filled in the implementation. The point is not that the app is hard. The point is that a complete, working product can be made without ever looking at the code.

The frontend is a different story. I am not a frontend developer, so there I worked at the level of intuition and engineering understanding: how it should feel, how it should behave, what goes where. That is a level above the code. So here is the question I want to put to you up front: if an app is built this way, is it still "yours"? Would you take a good app made fast by a model over a good, slower and smaller one written by hand? I have my own answer below, and I would like to hear yours.

The result is Overdraft, a personal time tracker. It has no users yet. I just released it, and I never planned to advertise it. I made it for myself and for my son. This post is about how it was made, and what I think that says about where programming is going.

The idea

I wanted something simple: press play on a task, and later see where the time actually went. Not a timesheet, not a team tool. A mirror for personal time, and maybe a way to regulate "wasting" it.

A few rules came from that, and they are all mine:

One running task at a time. Start another one and the current one stops by itself.
A daily cap per task. Two hours of games is fine; the counter turns red when you cross it.
Four fixed lists: Backlog, Progress, Today, Tomorrow. No custom lists and no long-term projects. Backlog holds only what is really coming up, and Today and Tomorrow are a tiny one-day planner.
Tracked time cannot be edited, so the numbers stay honest.
Sleep counts too. You have 24 hours a day, and sleep is part of the budget.

How it was actually built

The idea, the product decisions and the architecture were mine. The code was written entirely by Claude, through Claude Code. I did not open an editor to fix "just one line". If something was wrong, I said what was wrong, and the model changed it.

What that looked like in practice:

I described the module boundaries first. Backend: Java 21, Spring Boot, PostgreSQL, Flyway, split into auth, board and progress modules with explicit contracts between them. Frontend: Vite, React, TypeScript, one flat structure. Each module has a short CLAUDE.md that states what it owns and what it must not know about.
I kept a set of written standards that the model loads in every session: language rules, commit format, how secrets are handled, how Docker is laid out, how a plan must mark decisions that the standards do not cover. The model does not have to guess my taste; it reads it.
I worked in small steps and kept decisions in writing. Open questions, known bugs and future ideas went into plain markdown files in the repo, not into my head.
I reviewed behavior, not code. I used the app, looked at the screen, said "this feels wrong", and described what it should do instead.

The repository today has about 25,000 lines of Java, TypeScript, CSS and SQL, 23 database migrations and 184 commits made over six days. I wrote none of those lines.

What came out

Web app with the four lists, drag and drop, a task page with a time chart, groups with colors, optional daily caps.
Stats: week, month, year and all time, as bars, lines or an activity calendar, with group filters, a CSV export and a side-by-side comparison of any two days.

A day strip under the board: a timeline of sessions by hour, or a "breakdown" of the whole day as one bar (missed time, sleep, groups, what is left).
Phone version: one list per screen, swipes between lists, a bar with the running task on every page, swipe to stop it.
PWA: installable, works offline for reading, push notifications when a cap is reached or a timer was left running.
Chrome extension: start and stop tasks from the toolbar, with the running time on the icon.

Three interface languages (English, Russian, Ukrainian), encrypted task text in the database, Google sign-in, one-command deploy to a small VPS.
A landing page, with screenshots and videos recorded by scripts on demo data, also produced with the model.

Declarative programming is old news. This feels different

We have been writing declaratively for a long time: you say what you want (SQL, HTML, config) and the engine decides how. What I did here is one level up. I did not describe the code. I described the architecture: what the parts are, what each one owns, where the boundaries are, what is forbidden, and what the product must feel like. The implementation was left to the model.

Maybe it deserves a name like declarative architectural programming. I am not sure the term is right, but the split is real: the human owns the idea, the constraints and the taste; the model owns the typing.

What I learned

Written boundaries matter more than clever prompts. Short per-module notes about what a module may and may not touch kept the codebase consistent across dozens of sessions.
Standards in files beat repeating yourself. Every correction I made twice became a rule in a file.
You still have to know what you want. The model is fast at building the wrong thing too. The product's strictness (one task, four lists, no editing) came from me, and it is what makes the app small enough to finish.
Verification is the new bottleneck. I could not skim the code for bugs, so I used the product like a user would. Bugs I found while doing something else went into a KNOWN_ISSUES.md file instead of being lost.
It is not free in effort. Time and attention still go into it, just not into typing. If you want the result to look and behave exactly the way you imagine, you have to work for it: form your ideas clearly, in small atomic pieces, and in a sensible order. Vague input gives vague output.

Is it mine?

This is the part I have not settled. The app came from my idea, my rules and my architecture, yet I did not write the code. The backend I could have typed myself; the frontend and the extension I steered by intuition and engineering sense, without reading the code. It feels strange to say "I made it" and "I did not make it" about the same thing.

My current answer: I am the author of the product and of the decisions, and the model is the author of the typing. A film director does not operate the camera either. But I notice that the line is blurry, and that it moves every few months.

Honest status

No users, no marketing, no revenue. It is early access and free, and it started as a tool for me and my son. If you try it, I would like to hear what is wrong with it.

Web app: https://app.overdraft.nomad4.tech
Landing page: https://overdraft.nomad4.tech
Chrome extension: https://chromewebstore.google.com/detail/mgciphgekdeipgbablncehlmjmlciadb

Your turn

Does it count as "yours" if you design everything and a model writes everything?
A fast, polished app from a model, or a slower, smaller one written by hand: which would you ship?
If you have tried a similar experiment, what broke first for you: the idea, the architecture or the review?

Tell me in the comments. And if you track your time, tell me what the one feature is that you could not live without.

Disclosure: this article was also written entirely by a model (Sonnet 5.5), from my notes and the project files, as part of the same experiment.

I got tired of refreshing Telegram. So I built a bot that does it for me

nomad4tech — Tue, 05 May 2026 09:38:11 +0000

It started with a stupid habit 🫠

Every morning (or even during the day) I'd open a news channel to check one thing - some specific topic I actually cared about. Twenty minutes later I'd be three threads deep into something completely unrelated, mildly annoyed at myself, and no closer to the thing I opened the app for

Telegram has no keyword alerts (as far as I know). No filters. No way to say "notify me when this appears, ignore everything else." You either follow the channel and see everything, or you don't follow it and miss things.

So I built @telescope_one_bot 🙂

What it does

Simple premise: you tell it which public channels to watch and which keywords to look for. When a new post matches - you get a notification. That's it.

You don't open the channel. You don't scroll. You just get the relevant thing delivered.

Keyword matching works in three modes:

Single word - prefix match. football matches footballer, footballing, etc.
Number - exact match. 2026 won't match 20261.
Phrase - full phrase match. rent apartment only triggers on that exact phrase.

You can add channels in any format: @username, https://t.me/username, or even the web Telegram URL (https://web.telegram.org/k/#@username). Scanned every 60 seconds on the free tier.

Real use cases (not made up)

A friend who works in resale used it to track drops and signals across several channels. He said the 60 -second scan interval was the deciding factor - for him, being a minute late means missing the window entirely. He's waiting for faster checks and higher channel limits in Premium.
When my wife and I were apartment hunting, she refreshed rental groups constantly. We added all the local chats to the bot with keywords 2 rooms, pets allowed - and just...stopped checking manually. It worked. (I also realized exclusion keywords would make this even more useful - already on the roadmap)
I use it myself for news. I follow channels I'd never want to read in full, but I care about specific topics. Now I don't read them - I just get pinged when something relevant drops.

The tech behind it

The bot is built with Java 17 + Spring Boot, uses PostgreSQL for storing user data and channel state, and is powered by my own open-source library - telegrambot4j.

If you've seen my previous post about telegrambot4j - Telescope is what I built with it. The handler chain pattern I described there is exactly what drives the bot's command routing. Building Telescope also pushed me to extend the library itself. The inline keyboard support - InlineKeyboardButton, InlineKeyboardMarkup, and the convenience sendMessage overload - was added in v1.1.0 specifically
because the bot needed it. Real usage drives real improvements ☺️

The channel monitoring layer uses a custom Telegram API integration (not the Bot API - that only works for bots, not for reading public channels). That part is closed-source, but everything bot-facing is built on telegrambot4j.

The code for Telescope itself is closed-source. But the project page with README, feature list, and roadmap is here: github.com/nomad4tech/telescope-bot

Current state

The bot is live and fully functional. I'm in early access mode - collecting real usage data, watching what breaks, figuring out what people actually need before building more.

Free tier:

Up to 2 channels
Up to 10 keywords
Scanned every 60 seconds

Premium (coming soon) will include more channels, faster checks, per-channel keyword filters, advanced search filters, and webhooks for your own app. Free tier stays free.

Available in English and Russian

What I'm figuring out

This is my first attempt at shipping something for real users, not just for a client or selfhosted use. This is a solo side project I'm hacking on outside of my main job - I just genuinely enjoy building tools and figuring out how things work under the hood. But shipping for real users is different....You can't just close the ticket and move on. You care whether people actually use it. And honestly - figuring out growth and user support turns out to be just as interesting as the coding part

I don't have a growth playbook. I'm doing the obvious things: posting where Telegram users hang out, writing this, being honest about where it's at. We'll see what works.

If you try it and something's confusing, broken, or missing - I genuinely want to know.

Drop a comment here, open an issue on telegrambot4j, or reach me directly via @nomad4tech on Telegram

Try it: @telescope_one_bot

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.