Comepaolo

From CQRS to Event-Driven Architecture: an architectural pattern walkthrough

Fri, 21 Aug 2026 00:00:00 +0000

It all started with the same suggestion arriving from two different directions.

Summer 2024, the first one; I was working with my previous company on a platform for portfolio monitoring. The Spring Boot backend exposed multiple endpoints queried by the frontend, with a REST API in place for that. Some of these API calls became quite complex, for different reasons. Behind one of these single HTTP connections the server validated, wrote to a database, called two external services, and only then answered. When one of those services had a bad afternoon, the user got a 500. Not because their request was wrong, but because something three hops away was slow.

A colleague I trust gave me advice on that, on more than one occasion: separate the request from its execution, let events carry the work across, and go read about CQRS. I tried to explore that and other patterns here and there, but I never put proper time into it.

Spring 2026, the second one; in a brainstorming session, my manager suggested CQRS and Event Sourcing for an application we were designing, this time for a completely different reason: audit logs out of the box, no separate history table to maintain.

The same words, for two problems that had nothing to do with each other; that was enough to send me reading properly. So take my hand, and let’s walk through that journey together.

Let's get deep on this together :)

What I want to do here is connect a few tiles that were floating around separately in my head, and possibly in yours too: five patterns that keep coming up in the same conversations, what each one is really for, what it costs, and how they relate to one another. We start from a concrete need, that slow endpoint mentioned at first, and we end up somewhere far bigger than it.

These are the five ideas we’ll go through:

CQRS. Split reads and writes into separate code paths.
Event Sourcing. Store facts instead of state.
Asynchronous Request-Reply. Accept the request, execute later.
Transactional Outbox (+ Listen To Yourself). One transaction for your state and your message.
Event-Driven Architecture. Publish the fact, let the rest of the company consume it.

To compare them fairly, every step gets pointed at the same example: an order management system, the back end of any online shop. A customer places an order, changes the delivery address ten minutes later, pays, and eventually the thing ships. A small domain, familiar to everybody, and with one property that becomes important later.

For every step I’ll ask the same two things: what it fixes on that example, and what it charges in exchange. Plus a third one that mattered more to me at the time, which is whether it gets us any closer to fixing that endpoint.

Step zero: The baseline architecture we all know

It’s worth being precise about what we’re comparing against, because it’s tempting to turn it into an easy target, and it doesn’t deserve that. The classic MVC layered application has four properties, and they travel together:

Reads and writes go through the same stack: same endpoint, same service, same DAO.
They use the same model. One Order class that is the business model, the persistence model, and (with a DTO or two of polish) the thing you send over the wire.
It’s one deployment unit, usually against one data store.
Writes mutate state in place. You update a row, the old value is gone.

One path, and the same Order re-shaped four times along it

This usually works. I want to say it clearly, because everything after this section is about alternatives and it would be easy to read the whole thing as a condemnation. Plenty of applications run on exactly this for years, and the people maintaining them sleep fine.

But there are cracks, and each one is the reason for one of the five steps:

The data model is a compromise. One schema serves both writing and reading. The form of that schema is usually write-optimized, meaning that we often end up using some tricks to obtain read-optimized views on top of it (ex., using database views). We hide a conflict of interest.
You can’t scale reads and writes independently. If your traffic is 90% reads, read replicas solve that today, cheaply, with no architectural change whatsoever, giving you more of the same shape. But if the shape itself is the problem, more copies of it don’t help, and you have to rewrite the whole stack.
There’s no history. No snapshot, no replay, no rollback, no audit trail. Not because it’s impossible, but because you have to write that code yourself, as a feature.
It pulls toward a monolith. Nothing forbids splitting it, but the pull of “one model, one store, one deploy” is real.

So, what should we do when these cracks start to look more like reefs?

Step one: CQRS, and why it is much smaller than you think

Let’s start with the definition. CQRS is an architectural pattern, and stands for Command Query Responsibility Segregation. Commands are write operations, queries are read operations, and the claim is simply that the two don’t have to share a model. The idea behind the pattern is simple: one code path handles writes, shaped around the business rules it has to enforce. Another handles reads, shaped around the questions the UI actually asks. They can share a database. They just stop sharing a model.

The split is in the code, not in the infrastructure

This alone addresses the data modelling compromise crack mentioned before. Your write model can be a rich domain object with all its rules, your read model can be a flat denormalised thing that answers “every unshipped order from this week, most valuable first” in one query, and neither compromises for the other.

The benefit is particularly felt in high-performance applications. Since read and write “stacks” are now separated, they can now grow and scale independently. You can go from naive approaches, like having denormalized schema on reads to reduce the need of join oprations, to advenced approaches that involve even using multiple data stores. Which means, storing models in different databases, or with even different technologies (ex., using a Redis cache for read operations, with faster data access).

On the other side, keep in mind that like any pattern, CQRS is useful in some places, but not in others. Many systems do fit a CRUD mental model, and so should be done in that style. CQRS is a significant mental leap for all concerned, so shouldn’t be tackled unless the benefit is worth the jump. It could (and should) only be used on specific portions of a system (a BoundedContext in DDD) and not the system as a whole.

Step two: event sourcing, and the state you never stored

Event Sourcing answers a different question altogether: what do we store?

Worth saying once before going into the details, since it confused me for weeks: CQRS and Event Sourcing are two separate patterns, and the dependency runs one way only. Event sourcing effectively forces CQRS on you (for reasons we’ll get to). Most articles present them as one package.

So let’s get back to that; Event Sourcing is an architectural design pattern, based on a simple concept: determine application state from a sequence of events. Not rows holding current values, but the ordered list of everything that ever happened. Instead of a row that says status = SHIPPED, you store OrderPlaced, then OrderDeliveryAddressChanged, then OrderShipped. Current state isn’t stored at all: you get it by replaying the list.

My first reaction was suspicion, and I don’t think that’s unusual. But then you start noticing how many domains are already shaped like this. A package moving through a logistics network is a sequence of events. A version control repository is a sequence of commits, and Git reconstructs your working tree by replaying them. Your relational database’s own write-ahead log works on the same principle, quietly, underneath the very system you were about to call “the normal way”.

The reason to want this is that the history stops being something you have to build as a feature. If somebody in your domain regularly asks “who changed this, when, and what did it look like before?”, event sourcing answers it for free, and a classic architecture answers it with a hand-written audit table that is always slightly out of date. That’s why it shows up in payments, insurance, betting and logistics, where the past is not a nice extra but the thing being regulated. And if nobody in your domain ever asks about the past, you’re paying for a feature nobody uses.

Two rules come with that definition. An event is something that happened, never something that should happen: that one is a command, and commands can be rejected, while events can’t be. So you write them in the past tense, OrderPlaced and not PlaceOrder, using the vocabulary of the domain rather than of the database. And you never delete them: removing something is itself an event appended to the stream, because the deletion is a fact like any other (with some exceptions, like GDPR; but let’s skirt around that, since we risk going off-topic).

There aren’t many moving parts: the application produces events, an event queue (usually represented by a message broker) carries them, event handlers react to them, doing the actual business logic, and the event store keeps them durably. The ordered sequence flowing through all of it is the event stream.

The application appends facts, handlers react, the store keeps everything forever

Why the two patterns end up together

Storing facts instead of state raises an obvious question. How do you query any of this?

It’s often said that event stores have terrible query performance, and that’s not quite right. An event store is excellent at the one question it exists to answer: “give me every event for aggregate 42, in order”. That’s an indexed range scan, and it’s fast. What it cannot do is answer any question. “Every unshipped order from this week, most valuable first” spans thousands of streams, and no index makes replaying all of them viable.

So the solution here is to build the answer in advance. An event handler subscribes to the stream and projects it into a read model shaped like the question, and if you can build one projection (or snapshot) you can build several: one for the dashboard, one for the search box, another one holding last week’s state if somebody asks for it. The application queries those, never the raw log.

And that is CQRS, reached by necessity rather than by choice. Once your source of truth is an event stream, a separate read model isn’t an option you evaluate, it’s the only way to serve a query at all. This is why the two are almost always taught as one thing: the expensive pattern cannot work without the cheap one, so anybody explaining event sourcing has to explain CQRS on the way. What gets lost is that the reverse isn’t true.

The same split as before, with considerably more machinery

What you buy with all that machinery is the missing history crack, closed completely. You can rebuild any state at any time, which means “what did this look like on the 3rd of March?” stops being a research project. Another interesting consequence regards also debugging: if a user hits a bug that only shows up after a specific sequence of operations, you replay their exact stream into a test environment and watch it happen, instead of guessing.

The reality check

At this point I had a decent map and no idea whether anyone actually lived there. So I went looking for people who had actually built these systems, rather than people explaining them, and the picture is clearly divided.

It pays off in some places. The creator of Axon Framework (a, probably “the”, state-of-the-art framework that allows to apply CQRS + Event Sourcing in Java), in a thread about real-world adoption, lists banks running core payment systems on it, airport management systems processing radar data, and the betting industry, “because of the strict auditing requirements and high value of past events.” Someone rebuilding tracking for a large logistics firm put it more sharply: the traditional model, “CRUD, locks, relational DB, is the one that ADDS a lot of complexity here, not the event sourcing stack we chose.” That’s the strongest case for the pattern. Not that it’s powerful, but that in the right domain it’s simpler than the alternative.

And it could be a disaster in others. A team processing 40,000 IoT messages a second, exactly the “high throughput” territory you’d expect to be a good fit, tried it and scrapped it: it “adds massive amounts of complexity, and what would be a simple problem to solve in standard architecture becomes a whole sprint for your team.” Their conclusion was to stick with a traditional architecture until it can’t cut it, then refactor, rather than choosing it from the start.

So the thing that decides isn’t throughput, it’s whether the domain really is a sequence of facts that somebody needs to audit. High volume on its own buys you nothing here. It just makes the overhead more expensive.

My take, after all that reading: full event sourcing across a whole domain is right for a narrow slice of systems, and for most applications adopting it wholesale costs more than it gives back.

The ideas underneath were still right, though, even where the full pattern was wrong. Separate the intent from the execution, write down what the user asked for before you do it, treat a request as a durable fact instead of an open connection. All of that seemed valuable at a much smaller scale, in one endpoint or one module. Which left me with a question I felt slightly stupid asking: does the small version have a name, or was I just describing a queue with extra steps?

Step three, Asynchronous Request-Reply: the same idea, one endpoint wide

It does have a name: Asynchronous Request-Reply, and it’s about the interaction between client and server.

A client sends a request whose processing is slow, or depends on downstream systems you don’t control. The classic answer is to hold the HTTP connection open and hope. The pattern’s answer is to stop doing that. The server accepts the request, returns 202 Accepted immediately with an identifier (a job ID), and the client either polls that identifier on a status endpoint, or gets notified later via webhook or WebSocket. When the work is completed, the status endpoint will return an HTTP 302 (Found) response with a resource URL that the client can be redirected to.

Underneath, the incoming request becomes an explicit command object, something like ProcessPaymentCommand, and goes on a queue. Background workers pull commands off and execute them.

Accept now, execute later, let the client come back for the result

Now look at what it buys.

Retries come for free, because the failure branch isn’t error handling bolted on afterwards, it’s the same state machine as the success branch. When the external API is down, the command sits in PENDING and gets tried again later. Your user doesn’t get a 500 for something that was never their fault.

You also get load smoothing. Traffic spike, flash sale, whatever: the API’s job is now to write a row, which it does very fast. Ingestion runs at spike speed, execution runs at whatever pace your workers can sustain, and the queue absorbs the difference between the two.

And almost by accident you end up with an audit trail of intent. That stored command is a record of what the user wanted, so if a bug corrupts your final state, you still have the original request sitting there and you can replay it. It feels like an event sourcing benefit, and it came from a single table.

And now the cost, because this step is cheap but not free. Your client needs somewhere to collect the result, which means polling endpoints or webhook delivery, infrastructure you didn’t have before. And the awkward one: business errors now surface after you’ve answered 202. You can no longer tell the user “your card was declined” in the response to their own request. That has to travel back through a notification, an email, or a status endpoint, and designing that path properly is usually more work than the worker loop itself. Anything the user must know immediately has to stay in the synchronous validation step, which puts real pressure on where you draw that line.

Still, this is the shape I was searching for from the start, and the one my colleague had been describing all along: intent separated from execution, at exactly one boundary, with no framework and no event store behind it. One table and a loop. This article could stop here, but since we are engineers, we noticed that something else can be improved. Let’s get deeper into the rabbit hole.

Step four: the dual write, and the Transactional Outbox

Step three left the worker doing its job against a single database, which is a comfortable place to be: one database means transactions. Now give that worker the one extra responsibility every real system eventually needs. Once it has saved the order, it also has to tell somebody else, so it publishes a message to a broker.

That’s two writes, to two different systems, with no transaction covering both, and it has a name: the dual-write problem. The database transaction can commit while the publish fails, and you get an order that nobody downstream ever hears about. Or the publish succeeds and the transaction rolls back, and the rest of the company reacts to an order that doesn’t exist. You can wrap the database write in a transaction. You cannot enrol the broker in it. So the two can disagree, and when they do, nothing tells you.

The usual mitigations, retries and try/catch and publishing only after the commit, all narrow the window without closing it. The process can die inside the window. There is no arrangement of two independent writes that is atomic. The only real fix is to stop having two writes.

Meet the Transactional Outbox pattern: instead of publishing to the broker, insert the message into an outbox table in the same database transaction as your business data. Then a separate process called a relay reads the outbox and publishes onward.

on handling a command, inside ONE transaction:
    save(order)                                  # business state
    insert(outbox, OrderPlaced(order.id, ...))   # the message, same transaction
    commit                                       # both, or neither

relay process (separate, runs continuously):
    for row in outbox where not published:
        publish(broker, row.payload)
        mark(row, published)                     # at-least-once: consumers must be idempotent

Business data and message in one commit, or neither

The relay itself can be boring. In the Spring world could be a @Scheduled job that reads the unpublished rows and hands them to a message broker, like Kafka.

Now look at that relay loop again, because it doesn’t fully escape the problem either. It publishes, then it marks the row as published, and those two steps aren’t atomic: a crash in between sends the same message twice. The outbox hasn’t deleted the risk, it has moved it, from “the message might be lost” to “the message might arrive twice”. That trade is the point of the exercise, because a lost message is unrecoverable while a duplicated one is an engineering problem with known solutions.

That’s called at-least-once delivery: every message arrives, some arrive more than once, and the responsibility shifts to whoever receives them. Those receivers have to be idempotent, meaning that handling the same message twice leaves the system in the same state as handling it once. In practice that’s an identifier carried in the message (the order ID is usually sitting right there) plus a uniqueness constraint or a “have I already processed this one?” check that turns the second attempt into a no-op. Once messages are moving between systems, idempotency stops being a detail and becomes a house rule.

Step four and a half: joining the dots

It’s worth stopping here to look at a small variation on the outbox, because this is where everything links back to the earlier steps.

Listen To Yourself is a variation on the Transactional Outbox where you simply invert the order. Instead of writing your state and an outbox row together, you publish the event to the broker first, and then let your own service consume its own event and update its local state from it. There is only one write, so there is nothing left to disagree with, and the broker becomes the source of truth.

Sound familiar? It’s basically step three, Asynchronous Request-Reply, implemented with events instead of a command table. The endpoint accepts the request, publishes the fact, answers 202, and the real work happens later when your own consumer picks the event up. Same separation between intent and execution, different transport. The price is the one from step two: your own state is now eventually consistent with the event you have just published, so anything reading immediately afterwards can still see the previous value, and you have to decide whether your domain tolerates that.

Event Sourcing closes the circle from the other side. If the event you publish is also the event you store, then the outbox table and the event store stop being two different things. There is no second write to disagree with, because the write is the event. The dual-write problem doesn’t get solved so much as it stops existing, and that was part of what step two had been selling all along.

Step five: zoom out, and it’s Event-Driven Architecture

The last step doesn’t need any new machinery, only a change of scope.

Everything so far has been inside one application. The outbox row was published to a broker so your own background worker could pick it up. Now stop thinking about your service and think about the whole company.

That same OrderPlaced event, published to a shared enterprise broker like Kafka, isn’t just yours anymore. Billing consumes it to issue an invoice. Inventory consumes it to decrement stock. Shipping consumes it to create a label. Analytics consumes it because analytics consumes everything.

None of those services called your API. You didn’t call theirs. You don’t know they exist, and, this is the important part, you don’t have to change your code when a fourth one shows up next quarter. You published a fact, and whoever cares about it, cares.

The outbox pattern, with a wider audience

That’s Event-Driven Architecture, and it’s just the outbox pattern with a wider audience.

That also changes what the outbox is for; it’s the safety mechanism that lets you adopt EDA without losing data. Without it, every service publishing to the shared broker has an unguarded dual write, and your beautifully decoupled architecture is silently losing messages at every node.

On the other side, keep in mind that even that “globally decoupled” application comes with a cost. You give up global ordering, so events about the same entity can reach a consumer out of sequence. You inherit at-least-once delivery organisation-wide, so every consumer needs the idempotency we keep coming back to. Debugging stops being a stack trace and becomes a correlation ID chased across five services’ logs. And the subtle one: your event schema becomes public API. A REST endpoint has known callers you can go and talk to. The coupling didn’t disappear, it moved into the payload, where it’s harder to see.

What I actually took away

I set out to fill in a missing piece, and ended up tracing, accidentally and roughly backwards, the path the industry took to arrive at event-driven architecture. What a journey!

In hindsight, the first thing I can do is go back to those two suggestions and finally answer them.

To my manager: it’s clear now what he meant. He was pointing at event sourcing as a way to get proper auditing of every change to the entity, for free. On that specific system, though, I still don’t think it would have been the right fit. The audit trail would have been a real gain, but that domain was complex, and complex in the way that resists being modelled as a list of events.

To my colleague: it’s clear now that he was pointing at asynchronous request-reply, or some variation of it. Here I partly agree. His suggestion was a general one, move the whole architecture in that direction, and that part I don’t buy: it doesn’t remove the complexity, it relocates it. The same code lives somewhere else, and the request that used to fail with a 500 now gets a 202 and fails later, out of sight.

I said partly, though, because there were a few contexts where a system like that made a lot of sense, and we built one without knowing the pattern had a name. The customer needed to submit a large batch of requests at once, each one potentially slow, and was fine with them being handled asynchronously. Perfect fit, and we ended up with asynchronous request-reply by accident.

What I concretely take away is to use these ideas surgically. Weigh the cost every time, and be happy to know one pattern more than you did last time. And these days, when somebody drops “we could use events here” into a brainstorming session, I at least know now which of the five things they’re pointing at.

Sources

CQRS and Event Sourcing, Michael Ploed at SpringOne2GX 2015. The walkthrough I followed for steps one and two.
CQRS is not an Architecture, Greg Young, 2012.
CQRS, Martin Fowler, 2011.
What do you mean by “Event-Driven”?, Martin Fowler, 2017.
Event Sourcing, Martin Fowler, 2005. The original write-up of the pattern.
Anyone using Axon or CQRS/event sourcing in real life? Reddit thread with a comment from an Axon maintainer, quoted in the reality check chapter, 2017.
Asynchronous Request-Reply, Azure Architecture Center, 2026.
Transactional Outbox, Chris Richardson, 2019.
Event-driven architecture style, Azure Architecture Center, 2026.
A Spring Boot outbox implementation, if you want to experiment with a working code example.
The header image is Webb Opens Treasure Chest, from NASA.

The Canestreet Website: From a Simple Showcase to the Tournament's Core ERP

Sun, 17 May 2026 00:00:00 +0000

If you type canestreet.it into your browser’s search bar, you’ll land on a sleek, modern website. The subject is instantly clear: a summer basketball tournament. The splash screen greets you with action shots from the past editions, and a quick glance reveals everything you’d expect from a sports hub. Team registration, live results, official rules, and a curated about section.

It looks exactly like what a professional tournament needs. And, as you might have guessed, it’s a website I built 😏

Canestreet is the name of a small summer basketball 3x3 tournament we host every year in my hometown Jesi, Italy. We’ve been running it for eight years now. What started out as a casual joke among friends has evolved into a highly anticipated summer event. And with that growth came a mountain of logistical headaches.

This article isn’t about the tournament itself (there is a whole other piece on that). Instead, this is a spin-off story. It’s a deep dive into a tool I briefly mentioned in the main article, but one that deserves its own spotlight: the Canestreet digital ecosystem.

The Good Ol’ Times: Rough Basketball and Small Needs

Canestreet was born in 2018, primarily as a fun way to break up the sweltering Italian summer heat. A few friends and I set up a modest event on a small basketball court owned by a local church.

In those early days, we didn’t need much technology. Word of mouth was our primary marketing engine. We only needed eight teams to make the tournament viable, and we reached almost all the players through friend-of-a-friend networks.

To give the event a slight digital footprint, we created an Instagram page. It was mostly fueled by memes, funny team descriptions, event announcements, and stories updating the match results. It was the perfect, low-friction hotspot to keep players engaged.

One of the Instagram Posts from the early days. What a simpatico umorista I was

We kept replicating the model year after year, even when we upgraded to a much larger playground. For nearly five years, Instagram remained our de facto point of contact with the outside world.

On the organizational side, however, we needed a bit more structure to track rounds, points, and final brackets. Pen and paper quickly became a nightmare for a tournament with more than 50 players. Our grand upgrade? A massive web of Google Sheets. At the time, it was a medium perfectly tailored to the size of our needs. But as the tournament continued to balloon, we began craving something that felt a bit more professional.

The Google Sheet we used in the first editions. The whole tournament was based on that.

The First Website: The Showcase We Needed

We managed to run the tournament for three consecutive years before Covid brought everything to a grinding halt. That forced hiatus gave us time to rethink our next steps. More importantly for this story, it handed me, as a programmer, an abundance of free time to invest in whatever random side project crossed my mind.

That lockdown boredom was the exact cradle where the first version of the Canestreet website was born.

Homepage of the old website. Slay

I wanted to give the tournament a proper virtual home. Instagram would still be our primary way to engage users, but like any growing entity, we needed a dedicated space on the web to showcase who we were outside of social media silos. Let’s be honest: an Instagram page isn’t the best business card when you’re pitching to a serious potential corporate sponsor.

Like any good engineer, I started by collecting requirements. What does a tournament website actually need?

A Homepage: A visual showcase with photos and a compelling description of the event.
Contacts: Where to find us, and an easy way for local businesses to reach the main organizer for sponsorships.
A News Section: A place for updates that could be easily shared via a single permalink.
Some nice-to-have: A registration portal, an interactive rules page, and live match results.

Reconciling all of these features was a massive challenge for me at the time because my web development experience was pretty limited. I had experimented with a few small projects using Angular and headless CMSs (see the origins of CovidAnalysis and my blog for more funny stories!), but I had never built a comprehensive, production-grade web application.

Following the breadcrumbs of convenience led me straight to a precise technology. I had to strike a deal with the framework I disliked the most—the monster that powers half the web, yet is widely mocked by developers everywhere.

Yes, I’m talking about WordPress.

That's how I imagine me working on a Wordpress project (credits: Nano Banana)

I genuinely dislike WordPress. It’s a CMS born for simple blogging that has been aggressively bent, twisted, and forced by themes and plugins to act as a solution for every website requirement under the sun. It’s flexible, sure, but forcing a tool so far outside its original scope always felt fundamentally wrong to me.

Yet, because it was an industry standard, it was the most pragmatic place to start experimenting. I knew that learning my way around a tool used by half the internet would eventually be a useful skill to have in my back pocket.

So, I held my nose, bought the domain thecanestreet.it, and linked it to a hosted WordPress instance. That’s the resulting stack I came out with:

Component	Technology	Cost	Why We Used It
Framework	WordPress	Free (OSS)	The industry standard for quickly building functional web spaces.
Page Builder	Elementor Plugin	Free Tier	Allowed drag-and-drop page creation without deep frontend experience. I didn’t want to invest too much time on that.
Sports Engine	WP Club Manager	Free	A pre-built plugin used to handle matches, players, and standings.
Registrations	Google Forms (iFrame)	€0	Embedded directly into the page to collect user sign-up data.
Hosting & Domain	Self-Hosted	€25/year	Necessary to get a custom domain, Linux hosting and the WordPress database.

Quite cheap, but not free as you can see. I spent a month tinkering with the Elementor plugin, building out the pages we needed one by one. I built the homepage, added an “About” and “Contact” page, and even embedded a PDF viewer to display the official FIBA 3x3 rules. Finally, I spun up a news section utilizing the native WordPress blog architecture.

This first iteration actually survived for four years. Over time, I expanded its capabilities by adding a third-party plugin for live sports casting and embedding a basic Google Form iFrame to handle player sign-ups.

The solution was minimal, but it got the job done. The glaring downside? The sheer amount of manual data manipulation required behind the scenes. The pain points were two in particular:

Registrations: Teams submitted forms, but everything after that was manual labor. We had to manually export the data from Google Sheets, email the team captain to confirm, and spend days chasing people down to validate physical sports insurance and federation certificates.
Live Scoring: The sports-casting plugin required an immense amount of configuration. Updating scores during a fast-paced game was tedious, and getting brackets to align properly with complex FIBA tie-breaker rules required constant manual intervention.

Every time a developer handles a repetitive task that could easily be automated, an angel loses its wings 🥴 I knew I needed a change.

The Second Website: The AI Breakthrough

Then came the dawn of 2026, and everything shifted.

Over the previous several months, generative AI tools designed specifically for coding evolved from amusing novelties into powerhouse assistants. The launch of advanced coding models completely revolutionized our day-to-day engineering workflows.

These tools successfully took over the heavy lifting of concrete syntax and boilerplate implementation, freeing us up to focus on high-level architecture, system design, and product specifications. I was fortunate enough to be working at a company that actively encourages using tools like Claude Code, even subsidizing licenses for our personal development. It’s a massive win-win: continuous self-training for the employees, and unlimited building potential for the engineers.

She just wanted an ice cream

I decided to burn down the old WordPress site and build a custom application from scratch. I didn’t want just a public showcase anymore; I wanted a fully bespoke Enterprise Resource Planning (ERP) system tailored perfectly to the chaos of a 3x3 basketball tournament.

I brainstormed architectures, aiming for modern tech stack performance while keeping hosting costs at a grand total of zero, or near-zero Euros per year.

Component	Technology	Cost	Why We Used It
Framework	Next.js (React)	€0	Single codebase for both frontend UI and API backend routes.
Hosting	Vercel	€0	Seamless deployment and incredible loading speeds.
Database	Supabase (PostgreSQL)	€0	Relational powerhouse on a generous free tier.
Assistant	Claude Code	Sponsored	Handled the heavy boilerplate lifting in seconds.
Domain	canestreet.it (GoDaddy)	€10/year	Sticked to the provider since i have previous sites here (using other ones i could have expeded even less).

I had a functional, bare-bones prototype running in less than an afternoon. I was completely stunned. In just a few hours, I managed to build the core repository skeleton alongside clean, responsive designs for the home, about, contact, and rules sections.

Homepage of the new website. Type shit

Galvanized by this newfound velocity, I kept iterating. Within a week, the public-facing application was complete. The following week, I turned my attention to building a custom administrative back-office dashboard.

Built entirely around the real pain points we gathered over seven years of running tournaments, the new system seamlessly automates our entire operation:

Automated Registrations: Teams register directly via custom web forms. The app parses the data, alerts the staff, and fires off beautiful automated confirmation emails once approved.
FIBA-Compliant Live Engine: No more fighting generic sports plugins. Our backend automatically takes registered teams, generates round-robin groups, dynamically calculates standings based on complex FIBA 3x3 tie-breaker rules, and populates the playoff brackets in real-time for spectators.
Dynamic Sponsor Management: Sponsors can be added, categorized (Gold, Silver, Technical), and updated instantly via the dashboard, automatically rendering them across the platform.
The Court Jumbotron: Solving an old logistical problem, I built a dedicated “Showcase View” meant to be projected on TVs or laptops around the courts. It loops through real-time scores, upcoming match timetables, and active sponsor loops without needing manual refreshes.
Three-Point Contest Module: A streamlined micro-dashboard to register players for our annual shootout, input their scores live, and broadcast a real-time leaderboard to the crowd.

Some screenshots from the mobile version of the website. Fully responsive, 100% compatible with every device.

Conclusion and Takeaways

Looking back at the trajectory of this project, it is genuinely incredible what a single independent developer can achieve with modern tools. Building a system of this complexity in my limited free time would have easily taken me several months of grueling weekend work in the past.

Working with these AI tools as a developer can be overwhelming. In particular, when they were initially introduced, the experience was almost addicting, like gambling. You prompt your intentions, achieve your result, and cannot wait for your PC-shaped slot machine to let you insert the coin for the next round.

It is important that you do not fall into that rabbit hole and that, with time and iteration, you learn how to steer this technology. Having this power in your hands without proper discipline would allow the architecture to degenerate into an unmaintainable mess.

Let’s remember that we are engineers at the end of the day. We are responsible for the codebase, not Mr. Claudio. It is more critical than ever that we maintain absolute control over the code, thoroughly understand the output, and never go on full autopilot. Total reliance on automation is the easiest way to make a complex software project fail.

Do you know what’s the best part of thiw project? The entire Canestreet platform is completely open-source and available on my GitHub! The tournament is my hobby, and this code is simply the engineering cherry on top. If you run a local sports tournament and want a tailored, automated management system to make your event shine, feel free to clone the repository. Just remember to give credit to your favourite developer from Jesi 🥰

The Canestreet Website Project on GitHub

GitFit: Because Your Morning Run Deserves a Green Square Too

Wed, 04 Mar 2026 00:00:00 +0000

What does your GitHub contribution graph say about you?

If you’re like me, it says you write code. You commit features, fix bugs, refactor messy functions. Some weeks the graph lights up green. Other weeks? Dark, empty squares that whisper “where were you?”

But here’s the thing: those empty weeks? I wasn’t idle. I was running. Cycling. Pushing myself physically in ways that took just as much discipline—maybe more—than writing clean code. I was growing, just not in a way GitHub could see.

And that bothered me more than it probably should.

The Invisible Work

Autumn, 2025. I’d just changed jobs, and like anyone in a period of transition, I was doing a lot of reflecting. Am I growing? Am I better than I was last year?

The answer was yes—but not in the ways I expected. Sure, I was coding at work, building features, solving problems. But I’d also committed myself to something else: taking care of myself. Morning runs tracked on my Pixel Watch 2. Gym sessions, strength training, actual consistent exercise for the first time in… well, let’s not count the years.

I’d track everything with Fitbit—runs syncing over to Strava, gym sessions logged, movement counted. I’d watch the stats tick up, feel good about my progress. Then I’d check my GitHub profile and see… nothing. Just the commits from work.

GitHub contribution graph showing mostly empty weeks

Here’s what I realized: as a developer, those green squares actually matter to me. Not in a “gaming the system” way, but in a genuine “visible progress is motivating” way. When I see a solid week of commits, it feels like proof I showed up.

So why shouldn’t my morning 5K count?

The Programmer’s Reward Problem

Let me be honest about something: caring about your GitHub contribution graph is a little silly. It’s vanity metrics. It can be gamed. It doesn’t actually measure quality or impact.

And yet.

We’re programmers. We respond to feedback loops. We like seeing things work. When you write code, push a commit, and see that green square appear—there’s a tiny dopamine hit. “I did something today.”

For months, I’d been doing plenty of things. But GitHub didn’t know that. My contribution graph told a story of inconsistency, of sporadic effort. It didn’t show the 6 AM wake-ups, the kilometers logged, the discipline maintained.

I wanted those green squares to tell a fuller story. Not just what code I wrote, but what kind of person I was becoming.

That’s when the idea clicked: What if I could sync my fitness activities to GitHub?

GitFit: The Solution I Didn’t Know I Needed

The concept was surprisingly simple:

Fetch my latest activities from a fitness tracking API
Create commits in a private GitHub repository for each activity
Let those commits show up as green squares on my public contribution graph
Keep the actual workout data private (because nobody needs to see my pace per kilometer—trust me)

Architecture diagram showing Strava API to GitHub via Actions

I started with Strava as the first integration—their API is well-documented and straightforward to work with. But the vision is bigger: eventually adding Fitbit, Google Fit, whatever system I’m using to track my gym sessions and runs.

The beauty of this approach? My workout data stays completely private, locked away in a repo only I can access. But the fact that I worked out? That shows up. One green square per activity. Or two, or three, or five—depending on how far or long I went.

I built the whole thing with Python and GitHub Actions. Every day at 6 AM UTC, a workflow spins up, checks Strava for new activities, and creates corresponding commits. The code lives in a public repo on GitHub—open source, because why not?

Example Strava activity that generated commits

The setup takes maybe 10 minutes if you follow the README. You need:

A Strava account (obviously)
Two GitHub repos: one public for the code, one private for the commits
A handful of API tokens and secrets
The willingness to enable “Show private contributions” on your GitHub profile

And then? It just works. Every run, every ride—automated, synced, visible.

The Bigger Picture

I know how this sounds. “You built an automation to make your GitHub graph prettier? Really?”

Yes. Really. But it’s not about the graph.

It’s about recognizing that growth happens in more ways than we often give ourselves credit for. It’s about creating systems that remind us to value the effort we’re investing in becoming better—not just better developers, but better humans.

We spend so much time optimizing our code, our workflows, our productivity. Why not optimize for the things that actually matter? Health. Balance. Sustainability.

GitFit is absurd in the best way. It’s a deeply technical solution to a fundamentally human problem: the need to feel like we’re making progress.

If you’re someone who responds to visible metrics—and if you’re reading a programmer’s blog, you probably are—then maybe you need your own version of this. Maybe it’s syncing your reading goals, your creative projects, your volunteer hours. Whatever form of growth you’re investing in that doesn’t naturally show up in the places you look for validation.

Build the thing that lets you see your own effort.

Because when your GitHub contribution graph finally reflects the full picture of how you spent your time, you might discover something surprising: you were doing better than you thought all along.

GitFit is open source and available on GitHub. The setup takes about 10 minutes, and it’s compatible with any Strava account. Your workout data stays private—only the commits show up.

My new workstation for 2025

Sat, 08 Nov 2025 00:00:00 +0000

What’s more personal than your own workstation setup?

Creating the perfect setup is a thing that I genuinely enjoy doing. Choosing the right desk, chair, monitor, and accessories can make a huge difference in comfort and productivity, and I honestly love the process of researching and assembling everything, giving it a personal touch.

Here in Milan I’ve moved a few times. It’s not easy to establish a perfect setup when you’re renting apartments for short periods. And most importantly, not being my own landlord means I can’t always make the changes I’d like. All of those factors brought me to not invest too much effort on that on the last three years.

On my previous apartment, as an example, my set up was quite basic. And with basic, I mean a lot basic: my desk was a picnic table I’ve stolen from my parents’ house, since the previous apartment didn’t have a desk in it. And my chair, well, the classic plastic IKEA chair stolen from the living room. I’ve bought the cheaper monitor on Amazon, a cabled cheap keyboard and mouse combo, and used my old laptop as a second screen. It worked, but it wasn’t exactly ideal for long working hours.

At that time, I was on my first real job after university. Having moved in Milan only a few months before, and not knowing where I’d have been the month after, I didn’t want to invest too much in a proper setup.

Then two years later, I moved to my current apartment. To be honest, I was quite lucky on that one: I’m near the city center, in a nice area, with a good rent price. The apartment is not too small, and despite living still with two roommates, I have my own room, and it is a spacious one. Most importantly, I had the lucky chance to find here a desk already in place. And honestly a good one. I think it is something from IKEA, a nice white wooden one, with a good size and a clean design. It can even be heightened with some legs extension when needed, becoming a standing desk (even if it is quite tricky to do so). But the point is: I finally had a proper space to work on.

On the first two years here, I kept using my old monitor and peripherals. Recently though, I decided it was time for a change. It was a combination of factors.

On the first place, I started to feel uncomfortable while working from home with the old setup and peripherals. The monitor was not at the right height, the keyboard and mouse were not ergonomic at all, and the chair was just not made for long working hours.

Secondly, I had a bit of luck on the working side. After a few years at the same company, I resigned and moved to another company, which provided me a dedicated budget for the home office setup. Not a huge one, but enough to make a difference. It was the perfect excuse to invest in a better setup.

The new setup

After some research and consideration, I did few upgrades! Look at how polished and professional it looks now:

My workstation in tutto il suo splendore

Here’s a breakdown of the components:

Desk & Chair

My desk is a spacious, minimalist model with enough room for a monitors, a laptop, and accessories. I use an ergonomic chair that supports my back during long work sessions. An investment I highly recommend, and that in my case came for free since I’ve taken it from my previous office 👀

Monitors & Computer

I run a pseudo dual-monitor setup: one 27” display for main tasks, and the MacBook Pro monitor opened as a side space, for notes, reading, and chat. There’s a small stand for the monitor to match the height of the main display. I prefer having this arrangement over like an assembled pc, for flexibility reasons: once I finish to work, I can switch to my home laptop and continue my personal project there.

Peripherals

A mechanical keyboard with tactile switches and a wireless mouse make typing and navigation a pleasure. The vertical mouse is a must, to avoid any kind of wrist problem.

Audio & Lighting

For calls and music, I rely on noise-cancelling headphones. Adjustable LED desk lamps provide soft, even lighting, reducing eye strain and improving video call quality.

Music & Decor

I recently bought a new turntable, and it’s been a fantastic addition to my workspace. There’s something special about vinyl that digital music just can’t replicate, and it adds a nice aesthetic touch to the room. And to finish, a white mat over the desk ties the whole setup together.

Turntable detail. Best self-present ever

That’s it guys! That’s my setup that will accompany me over 2025, and hopefully the next few years as well. I’ve everything that I need for work and leisure, all in one place. If you have any questions about my setup or want to share yours, feel free to reach out!

CodyColor Multiplayer: From a Thesis Project to a Startup Game

Sun, 21 Sep 2025 00:00:00 +0000

2019 was a year of big changes in my life.

I had just graduated with my bachelor’s degree that February. My course was Informatica Applicata: that’s roughly equivalent to Computer Science outside Italy. I already liked programming, even though, looking back from where I am now, I was just at the beginning of my journey.

Me and my beloved colleghi urbinati

I still remember my thesis well: Utilizzo del pattern Publish-Subscribe e dei Message Broker nell’implementatione di giochi online Multiplayer e Applicazioni Distribuite 🗣📢🔥

A very roboant name for a thesis, isn’t it? It was based on experiments I did with message brokers (mainly RabbitMQ) and the publish-subscribe pattern, during an internship at a software company in my town.

It was an interesting topic, one that hadn’t been covered during my studies. But as I discovered during my internship, message brokers are essential in microservice, or even simpler multi-service architectures, especially when handling asynchronous communication.

As part of my thesis, I also built a small browser-based multiplayer game. It was simple but fun: every player controlled a ninja cat who could throw fireballs at others on a Super Mario–like map.

A screen from the thesis about the NinjaCat gameplay.

The real highlight, though, was the backend. Building on my RabbitMQ experiments, I developed a small Node.js application that used RabbitMQ to manage multiplayer rooms. Communication between client and server ran over WebSocket.

On the day of my thesis defense, I even prepared a live demo! Without the skills to host it on a real server, I hacked together a setup on my home PC, exposing both the client and backend to the internet. It worked, and the professors could interact with the game live. Their surprised faces made it worth it.

So, why am I telling you all this? Because one of those professors was particularly impressed. At that time, he was launching a university spin-off company aimed at developing small games and tools for teaching children in elementary and middle school the basics of programming. After seeing my demo, he invited me to join his company.

It was an unexpected but exciting proposal. I decided to seize the opportunity and see where life would take me.

CodyColor Multiplayer

About a month later, I joined the company: Digit Srl.

Digit was a small start-up, backed by the University of Urbino. Out of four employees, two were researchers continuing their projects, while the other two were recent graduates — me and another guy.

Selfie with my Digit colleagues!

My focus was on building a multiplayer game called CodyColor.

CodyColor is actually a coding method: a set of simple rules that can be turned into different types of games. The company already had an offline version, played with physical tiles and pawns, and the plan was to bring it online.

Here are the basic rules:

The playing field is a 5x5 grid (though it can be any size).
Each square can be colored yellow, red, or grey.
Each player controls a robot, Roby, who moves based on the color of the square:
- Yellow → rotate 90° left
- Red → rotate 90° right
- Grey → move forward

After a turn, Roby continues to the next square in its new direction.

Bringing It to Life

Digitalizing CodyColor was not easy, especially since I had zero experience with game development. But I did what I always do: learn by example.

For the frontend, I used AngularJS (yes, the grandparent of Angular). For the backend, I built a NodeJS app, communicating with the client via a single WebSocket channel. All of the heavy work was made possible via StompJs, implementing the publish-subscribe pattern over WebSocket.

With some help from the colleagues, the project began to take shape. I first built a single-player version with a simple AI opponent. I worked with the HTML canvas, added drag-and-drop robots, and integrated resources from the offline version.

To my surprise, the game started to come alive. Within a month, I had a working single-player prototype.

Screens from the CodyColor game.

Switching to Multiplayer

The next step, of course, was multiplayer.

Over the following months, we managed to make the magic happen again. We didn’t just create a multiplayer version—we also built a battle royale mode, where dozens (even hundreds) of players could compete in the same room.

Children from an elementary school playing with CodyColor in a Battle Royale.

We added a shared leaderboard and even allowed players to log in with federated identities. Using Firebase Authentication and Firestore, we could manage this almost for free, given the small user base.

As a fun spin-off, I developed a wall version of the game. It ran on a TV in our company’s display window. A QR code invited passersby to scan it, instantly joining a match against the AI visible on the screen.

Codycolor Wall in the Digit Srl showcase.

Conclusion

In the end, I had built a real product with my own hands—despite starting with almost no knowledge of JavaScript.

CodyColor Multiplayer remains one of the projects I’m most proud of. Not because of its complexity, nor its code quality (honestly, the code was terrible). But because it showed me what I was capable of: learning on the go, solving problems step by step, and pushing through challenges instead of giving up.

It’s one of the projects where I grew the most as a developer—and it all started with a simple opportunity I decided to take.

Visualizing the Pandemic: The Story Behind CovidAnalysis

Sat, 30 Aug 2025 00:00:00 +0000

The Covid pandemic was one of the strangest periods of our lives.

For a few years, the world seemed to stop in its tracks. Streets went silent, cities emptied, and our daily routines were suddenly reshaped by lockdowns and strict restrictions on movement. It was a time that forced us to rethink society, freedom, and even ourselves.

And, of course, the reason behind it all was grim: illness and death. Millions were affected by the COVID-19 virus, while millions more went through an emergency vaccination campaign that promised a way out of the crisis.

In the middle of this, I was in my final year of university. The pandemic hit Italy in the early months of 2020, bringing with it the first nationwide lockdown. After a brief window of relief during spring and summer, new restrictions followed in the months ahead. Life felt like a cycle of reopening and shutting down, always with a lingering uncertainty about what would come next.

But after the first shock, something unique happened in Italy—something that, as far as I know, very few countries attempted. COVID-related data—numbers of infections, hospitalizations, deaths, and later vaccinations—were made publicly available as open data. Updated daily, they were shared on a dedicated GitHub repository. To me, this was remarkable: a real act of transparency and, in a way, efficiency from our Protezione Civile. It’s not common for governments to publish this kind of information in such a structured and accessible way.

The COVID-19 Repository from the Protezione Civile

It was in the autumn of 2020 that I stumbled upon this repository. By then, the air was thick with news—some accurate, some misleading, some pure speculation. That’s when a thought struck me: what if I try to make sense of the data myself, instead of drowning in unverified headlines and rumors?

The CovidAnalysis Project

In November 2020, I started the CovidAnalysis Project, a not-so-original name for a small GitHub repository where I experimented with visualizing the data published by the Protezione Civile.

The CovidAnalysis Project on GitHub

The repository looked very different in its early days compared to what you can see now. At first, I simply created basic plots using Matplotlib’s PyPlot library. Nothing fancy—just simple charts to get a clearer view of the numbers.

I began with the basics: the number of deaths and infections, both as weekly incidence and absolute values. I was particularly interested in the data from my own region, Le Marche, since local information wasn’t always easy to find in national news.

Example of the first basic charts.

As I got more comfortable, I started experimenting with more advanced analysis. I built geographical maps showing data per region and province, calculated derivatives to track daily increases or decreases, and even tried to estimate the infamous RT and R0 indexes per region—later adding vaccination data as well.

Example of geomap chart.

What made this project truly fascinating was its immediacy. The data wasn’t historical or archived: it was unfolding in real time. Every day I could update my charts and see the impact of new cases, comparing how infections rose or fell against the thresholds the government used to determine lockdown measures.

CovidAnalysis quickly became more than just a coding exercise. For me, it was a powerful way to make sense of the chaotic reality around me, and to replace anxiety with understanding.

Let’s Go Public!

By December 2020, I started realizing that all the information I was generating was pure gold. It felt like a waste to keep it only for myself. Wouldn’t it be great to share these insights with others?

The first step was automation. I set up a GitHub Action with a cron job. Every morning at 4 a.m., the Action would spin up a container, run the Python scripts, generate fresh plots, and export them as JPEGs. The images were then committed back into the repository on the deploy branch.

The second step was exposing the data. I decided to build a small Angular Progressive Web App (PWA) to display all the charts my scripts generated daily.

How CovidAnalysis appears from PC

In less than a week, I had the first version up and running. To keep things simple (and free), I hosted it directly on GitHub Pages. Zero cost, minimal friction, and suddenly my data wasn’t just mine anymore—it was available to anyone.

Tweaks and Optimizations

Over time, the website became more than just a data portal—it turned into a playground for experimenting with style and features. I started treating it as a design exercise, trying out Angular’s Material UI and fine-tuning the details of the interface.

How CovidAnalysis appears from mobile

I also restructured the site into multiple sections: one dedicated to national Italian data, another focused on my home region of Le Marche, and a third where I pulled in pandemic-related news directly from Twitter.

On the design side, I couldn’t resist adding a dark mode, along with an automatic theme switch based on the user’s system preferences.

But the feature I’m most proud of was the notification system. I experimented with push notifications: whenever new daily data was processed, users would receive a notification. To achieve this, I combined service workers with a minimal backend deployed on Heroku.

CovidAnalysis high level architecture

Conclusion

What started as a small experiment in my final year of university quickly grew into something much bigger. CovidAnalysis was never meant to be a polished product. It was a playground where I combined curiosity, coding, and a very real need to make sense of the world around me.

Along the way, I learned how to fetch and process open data, automate workflows with GitHub Actions, build and deploy a frontend with Angular, and even push the boundaries of PWAs with notifications. But more than the technical lessons, this project gave me something deeper: a way to cut through the noise of misinformation and uncertainty during one of the most confusing times of our lives.

Looking back, I see CovidAnalysis as more than just a coding project. It was my way of understanding reality through data, of feeling a little more in control when everything around us felt unpredictable.

The Comepaolo Blog: How I built my personal website

Thu, 28 Aug 2025 00:00:00 +0000

How has this website been built?

If you work in software and you’re wandering around my blog, maybe this is the first question that comes to mind. Is the blog powered by a CMS? Is it just a static website, an Angular PWA? Could I build something similar for myself?

If you’ve ever thought about that, you’re in the right place. Let’s start from the beginning.

Please appreciate my meme talent, thank you

The origins

When I first bought the domain riccardomaldini.it, turning it into a blog wasn’t part of the plan.

We’re talking about 2018. I was still in university, just starting to dive into the magical world of software development. During a Networking course, I began to understand how the Internet actually worked. This whole network of websites linked together across the world seemed almost magical.

That’s also when I started thinking about my digital identity: what if I bought a domain for myself? The domain riccardomaldini.it was still unused, and it would’ve been a shame if someone else took it and used it for something unrelated to me.

So I decided to buy it. I had no idea what to do with it at the time. I couldn’t even build a website yet, but I wanted to secure it for the future me. On Aruba (the hosting provider I used), the price was ridiculously cheap — something like 3 euros per year — so I didn’t hesitate.

The first real use of the domain came from my Play Store projects. Publishing apps on the Play Store requires providing Google with a webpage containing a Privacy Policy and Terms & Conditions. So I purchased hosting space from Aruba and uploaded a very simple static site with those policies (auto-generated, of course — I’m not a lawyer yet 🙂).

The first version: a very static CV website

Fast forward to 2021. We’re in the middle of the COVID pandemic. I was in my last year of university with a few exams left, but also with much more experience than before and, for the first time, a lot of free time (thanks, lockdown).

That’s when I started experimenting heavily with web design. I was learning Flutter, Angular, and even some Python/TypeScript for my first web server experiments. I worked on the DiAry project and CovidAnalysis (I’ll definitely talk about those in the future). At the same time, I began experimenting again with my personal website.

My first idea was to turn it into an online CV. I wanted a place to showcase my studies, skills, and (limited) work experience. So I developed the first version: a static, hand-written HTML page with CSS, built on top of a template from html5up.com. Honestly, I think everyone started from there 😄

The first template I used was Photon, a versatile personal template. Then I tried Miniport, which was a bit more CV-oriented, and finally settled on Strata.

The first version of the website, created with Strata.

It worked for its purpose… but it was also very limited. It was just a static page, and every change required a lot of manual editing in HTML and CSS.

The first paradigm shift: file-based CMS

Another option was to use a CMS. I experimented with WordPress, and I liked the idea of having a “framework” to handle all the logic behind the scenes so I could focus on writing content. But I quickly ran into three problems:

WordPress is primarily designed for blogs. Plugins make it very flexible, but using it for a CV website always felt a bit forced.
The CV templates available were either ugly, paid, or really hard to customize.
WordPress requires a MySQL database and a PHP runtime. Each of these adds cost to a hosting plan.

All of this made me look for alternatives.

The breakthrough came when I discovered the concept of file-based CMS. This idea, which started gaining momentum around 2020, offered an alternative: instead of using a database, the CMS would rely on the filesystem itself, saving content as regular files. This immediately caught my interest — especially because it meant I could avoid paying for a MySQL database.

That’s how I found Grav, a simple file-based CMS that worked perfectly. It even provided “skeletons” — pre-made templates you could unpack directly into your hosting space and start using right away.

I switched to Grav with a CV-themed skeleton called Hola, which I heavily customized for my needs. This version of the website lasted for years. It was flexible, easy to use, and very low-maintenance. Adding a new project, education, or work experience was as simple as editing a post and uploading a few photos — Grav handled the rest.

A snapshot from the original Grav Hola Template. For a long time, my website was a copycat of this one.

Shifting to the blog approach

At the beginning of 2025, I started rethinking the purpose of my website. My life had changed. Presenting myself only through a CV felt reductive. I’m not just a list of education and work experience.

Sure, you can download my CV if you want, but a CV doesn’t give me space to elaborate — to write full articles about projects or experiences, like the one you’re reading right now.

That’s when I decided to switch to a blog format. I created The Comepaolo Blog with a new purpose: to have a place where I could share and discuss my projects and experiences in depth.

The first version of the blog used, once again, a Grav theme: Mediator, a theme inspired by Medium’s design. It’s actually the same theme I still use today, even if a lot has changed under the hood.

I created the initial content, set up the skeleton of the site, and added a few customizations. I even contributed to the open source project of the theme with some optimizations.

The actual bloggish-style of the website, based on the Mediator theme

The second paradigm shift: Jekyll

More recently, I started experimenting with Jekyll. This came mainly from professional needs — I had to build a documentation website for an API set.

Jekyll is a static website generator. It lets you write your content as Markdown files (or other markup formats), completely separating content from presentation. It’s written in Ruby and uses a meta-language called Liquid to customize templates.

I fell in love with Jekyll almost instantly. It’s easy to use, the learning curve isn’t steep, and the concept behind it is clever and straightforward. GitHub even supports it out of the box for GitHub Pages, making it the de-facto standard for static websites.

While digging around, I discovered that the Mediator theme for Grav was actually a port of a Jekyll template — also called Mediator. At that point, the path was obvious: it was time to migrate my website to Jekyll and turn it into a real software project.

The comepaolo-blog Project

The current version of my website lives inside the comepaolo-blog project, which started as a fork of the Mediator Jekyll theme originally created by dirkfabisch. Mediator was designed as a clean, Medium-inspired theme, and it gave me a solid and elegant foundation to build upon.

The actual comepaolo-blog project on GitHub.

I didn’t just fork it and leave it untouched, though. Over time, I shaped it to better reflect my needs and style. Some changes were simple customizations to the blog layout and sections, while others were more structural. For example, I extended the post tag system so that tags are now more prominent: each post shows its tags, and clicking on them brings you to a dedicated page listing all related articles.

Another important addition was the legal section. On my Grav site, I had hosted privacy policies and terms for my apps, and I wanted a smooth transition without breaking links. I rebuilt that section in Jekyll with a design consistent with the rest of the site.

I also introduced the possibility to react and discuss about a given post using Giscus, an open source alternative to Disqus, based on the GitHub API and the Discussions feature of the repository.

The biggest structural shift, however, was in how the site is deployed. Instead of manually uploading files or relying on a provider’s hosting tools, the whole process now runs through GitHub Actions. Each commit to the main branch triggers an automated build and deploy, and the output is directly published on GitHub Pages under my personal domain.

Conclusion

From static HTML pages, to Grav, and now to Jekyll, the website has grown step by step along with my own path as a developer. What began as a simple CV placeholder has become a fully versioned, automated, and customizable blog.

The main advantage of this setup is that it behaves like a proper software project. Every article, design tweak, or configuration change is tracked in Git; deployment happens automatically through GitHub Actions; and the structure encourages experimentation without the fear of breaking things.

In the end, Comepaolo Blog is still just my personal space online—but one that reflects not only who I am, but also how I work.

And for me, that combination feels just right.

Article update (March 2026): I’ve rewritten the blog template (again!) with my friend Claude Code, updating the theme to its v2! An article is incoming, see the new code under the Comepaolo v2 repo!

MaldiniCV: How I automated my Curriculum Vitae with GitHub Actions

Sat, 23 Aug 2025 00:00:00 +0000

Every student coming from a science-related university has, at some point, experimented with writing documents in LaTeX. It’s a neat system designed for preparing documents, mostly used for academic purposes (nearly every scientific paper in the world is written in LaTeX), but not limited to that. Unlike tools such as Word, LaTeX is a document preparation system. It separates the content of the document from its presentation (the template), and makes it easy to represent complex elements like mathematical formulas in a textual way.

LaTeX templates are often professional and fine-tuned. The system itself feels almost like programming — technically, it’s a markup language — which is one of the reasons it became so popular in the scientific world.

I first discovered LaTeX at university, and I kept using it well beyond that context. One of the first “non-academic” uses I found was writing my Curriculum Vitae. At some point, I stumbled upon a template called LuxSleek-CV, originally created at the University of Luxembourg. It struck the perfect balance between elegance and readability, and it quickly became my official CV template.

But writing it — whether in Overleaf or locally — soon revealed a bigger problem: versioning. Maintaining my CV wasn’t as simple as I’d hoped. Every update meant opening my editor, re-compiling the .tex file, exporting the PDF, and making sure I didn’t overwrite the wrong version. Over time, I ended up with a folder full of files named things like CV-final-v2.pdf, CV-updated.pdf, and of course, the infamous CV-really-final.pdf.

The versioning hell without a versioning system. This could escalate very quickly, trust me.

The struggle was real. At one point, I even gave up and switched to a simple Word document — probably the least “programmer” thing a programmer could do.

MaldiniCV

I spend my days working with version control, automation, and CI/CD pipelines. So I asked myself: why should my CV be exempt from those good practices?

That’s how MaldiniCV was born.

MaldiniCV project on GitHub.

Instead of treating my resume like a static document, I decided to treat it like a piece of software. The content lives in a GitHub repository, written in LaTeX, and every time I want to “release” a new version of my CV, I simply push a Git tag. Behind the scenes, a GitHub Actions workflow compiles the source, generates a polished PDF, and publishes it as a release artifact. No manual steps, no confusion about which file is the latest — just clean automation.

From there, I structured the repository much like a small application. The src/ folder holds my main LaTeX file, while the .github/workflows/ directory contains the automation logic. The heart of it all is a workflow that installs the right TeX packages, builds the PDF, and attaches it to a GitHub release.

It might seem like overkill for a CV, but in practice it means I never have to think about formatting quirks or local environment issues again. If I can push code, I can update my resume.

The Workflow in Action

Here’s how it plays out in real life.

Let’s say I add a new job or a side project to my CV. I commit the change to the LaTeX source and push it up to GitHub. When I’m ready to “publish” the new edition, I tag it like I would a software release:

git tag v1.2.0
git push origin v1.2.0

That tag is the trigger. GitHub Actions wakes up, installs a LaTeX environment, compiles my CV into a PDF, and creates a brand-new release in the repository. Within a minute or two, the final document is available to download straight from the Releases page.

Releases screen of the project, with the version v1.0.0

What I love about this is how natural it feels. Versioning my CV is just like versioning code: the history is visible, the process is repeatable, and the output is always reliable.

Why Automate a CV?

On the surface, automating a CV might sound like a niche experiment. But I’ve found it surprisingly impactful.

For one thing, it eliminates all the little frictions of keeping documents current. I don’t worry about which PDF I last sent, or whether the formatting broke on my machine after a package update. The build process is consistent and runs in the cloud.

It also adds a layer of professionalism. Each release of my CV is versioned, timestamped, and archived. If someone asked me for the version I used in an application months ago, I could retrieve it instantly. It’s like having a changelog of my professional life.

And maybe the biggest win: peace of mind. I know that the link to my GitHub Releases page always points to an authoritative, up-to-date version of my resume. That alone makes it worth it. When needed, it is sufficient to provide to a recruiter a link to the latest release, as for any software library. Cool, isn’t it? :)

Right now, MaldiniCV does one thing well: it builds and releases my CV automatically. It is an open source project, you can even fork it and make it yours.

In the end, though, the beauty of this setup is its simplicity. My CV has become just another project — one that benefits from the same tools and practices I use every day as a software engineer. And that feels exactly right.

Hoops in the Heart of Jesi: The Rise of Canestreet 3x3

Sun, 22 Jun 2025 00:00:00 +0000

Summer, 2018 — Jesi.

It was one of those summers when time feels endless. I had just wrapped up my internship and was halfway through writing my bachelor’s thesis. Honestly, the hardest part of my university career was already behind me.

The days were long and slow. And then—someone had an idea.

The Spark

Basketball is kind of a big deal around here. Jesi spent several years in Serie A before facing some unfortunate setbacks. The passion for the sport stuck around, and many locals still play.

One of those hot summer evenings, I met up with my group of friends in the city center. Among those friends was Michele, 21 at the time. He’d always played basketball, and was one of the first in our group to land a steady job. But his real superpower? He’s the guy who organizes. Planning Ferragosto? No problem—Michi’s already booked a camping spot in San Vicino. Want to go on holiday in Greece? He’s found the cheapest hotel in the archipelago and made the reservation. He’s the rock of the group.

So when he suggested turning the San Sebastiano parish into a basketball arena, we knew he meant business.

And just like that, The Canestreet was born.

The First Time

Jesi wasn’t new to basketball tournaments. Years ago, some were held at the sports complex near the high school, and even earlier, right in the main square—with big-name guests. But it had been a while since anything like that had happened. The goal was simple: fill the summer void with something fun. 3x3 basketball is a street sport—games take place on a half-court, tournament-style, with short, fast-paced matches.

Ballers under SanSeba's sunset

The plan was to host an amateur tournament with some of Michele’s teammates. The venue? San Sebastiano, a parish in downtown Jesi, just across from his house. The tournament’s name: The Canestreet. Why that name? Honestly, no clue. It’s a mashup of canestro (basket) and street, not even quite captivating, actually. But when Michi makes a call, there’s no room for democracy.

To pull it off, Michele needed a team. A few of our friends jumped in immediately—Federico, his best friend, and Lorenzo, a teammate. Soon after, I joined too.

That's me! And the staff too, chillin' under the tendone

I had never played basketball. But I had something else: a laptop and a bit of creativity. So I became the computer guy—running our Instagram page, trying to hype up the event with stories and posts, and experimenting with ways to reach people. I also ended up being the sound guy—plugging in the speakers, cueing up the playlists, packing everything down at night. It wasn’t glamorous, but it was fun. And all of that, with exactly zero euros in the budget.

Within a month, the Michele Mosca organizational machine was in full swing. We gathered enough teams, secured permission from the parish, bought a few cheap medals, and pulled off our first tournament. We had no sponsors (well, none we could publicly acknowledge), and no funding.

But it worked. The event was a blast.

And most importantly—it felt like something.

The first canestaff, est. 2018

Growing Pains and Giant Leaps

That first success was a spark, and it lit a fire. The following year, we moved to a larger space: San Pietro Martire, a parish with more room and more visibility. We joined the official FIP 3x3 Summer Circuit. We added categories. Got real sponsors. Learned to plan better. Messed up, learned again.

Snapshot from the 2020 finals

Every summer became a new challenge.

By 2024, we had moved to Piazza della Repubblica—the beating heart of Jesi. With support from the municipality, we installed a modular court and hoop in the middle of the square, right under the obelisk. The sound of basketballs bouncing off cobblestones became the new summer anthem.

We introduced under-age categories, both male and female open tournaments, and even a 3-point contest, including a version just for amateurs. Each edition brought new energy, new faces, and new memories.

No exaggeration: Canestreet has become a true part of Jesi’s summer identity—and equally a part of our lives as organizers. It’s all thanks to Michele’s wild idea and the drive of a guy who keeps leading us on this crazy ride.

The Canestreet in Piazza Della Repubblica for the second time, 2025

Side Projects, Big Lessons

Along the way, Canestreet became more than a tournament. It became my personal playground for experimentation.

The CaneScoreboard

In the early years, we didn’t have access to electronic scoreboards. So I built one. The CaneScoreboard (github, live demo) is a simple web app connected to a Firebase backend that lets us display live scores, fouls, and time. One screen is in editor mode (for updates), the other in display mode (for the audience). Low-latency. Real-time. It may not be beautiful, but it works—and it feels amazing to see people rely on something you made with your own hands.

TheCaneScoraboard display mode in place, 2019

The Website — thecanestreet.it

I also created and maintained the website, which serves as our digital headquarters. Built with WordPress, it includes sign-up forms, live brackets and results, sponsor visibility, and tournament rules. It may not be a full-blown platform, but it’s a living, evolving part of the project—and a place where I got to mix my coding, UX, and design skills.

thecanestreet.it homepage

The Instagram — @canestreet3x3

Our Instagram page is where the vibes live. I collaborate with friends who shoot photos, and I design infographics and announcements using tools like Canva and GIMP. Social media may not win tournaments, but it definitely brings people to them.

Canestreet started as a small neighborhood project. Today, it’s a city-wide celebration of basketball, friendship, and initiative. And for me, it’s been a personal lab—an experience that mixed creativity, technology, and community spirit in the best possible way. I can’t wait to see where it takes us next!

Live Scores, Real Pride: The Story Behind BetAssist

Mon, 16 Jun 2025 00:00:00 +0000

“What’s the project you’re most proud of?”

Every software developer has faced this question at least once. Maybe during an interview, maybe in a conversation with a colleague, a friend—or even with themselves. Most of the time, it’s not an easy one to answer.

It was June 2022. I was deep into the hiring process with a foreign software company. Not a big tech giant, but one of those solid mid-sized companies with a structured, multi-step approach. One of those steps was a behavioral interview. The interviewer asked about my values, how I approached challenges, and how I’d handled difficult situations.

That’s when the famous question came up again.

I paused for a few seconds. I had worked on many projects over the years, so picking just one wasn’t easy. But after a moment of reflection, I decided to stop overthinking and go with the most honest answer that came to mind:

“BetAssist.”

That was my bet.

First BetAssist header on the Google Play store.

The Idea

I genuinely think BetAssist is the project I’m most proud of. It’s an Android app I started building back in 2017. Its main purpose? To track football betslips with live score updates and offer betting suggestions.

For the unfamiliar, a betslip is essentially a form that records the details of a sports bet. At the time, in Italy, it was still common to place bets in physical shops and walk away with a paper receipt. You had to track your results manually—either by following each game individually or checking scores across various apps or websites. The official betting apps either weren’t great yet or weren’t widely adopted.

That’s when the idea hit me: What if all of this could be done in a single app?

The Process

In 2017, I was in my second year of a Computer Science degree. I had just finished an object-oriented programming course in Java and was eager to apply those concepts in the real world.

At that time, Android apps were still written in Java. So I picked up a book I still have in my Google Drive to this day: Android Programming for Beginners by John Horton. It was a hands-on introduction to Android development using Android Studio. The book’s main project was a simple note-taking app, which was used to teach UI design, app lifecycle, persistence, networking, and more.

I followed the guide chapter by chapter. But in the back of my mind, I was already thinking about BetAssist. “This ListView for notes would be perfect for a betslip list!” That single thought drove my motivation and learning throughout the book.

By the time I finished, I was ready to move on to something of my own.

The MVP

The first version of BetAssist was simple: a betslip editor.

BetAssist had a mascotte also. It didn't have a name, but was used on some of the graphics and logo, inspired by the Android original logo.

Users could create betslips by combining clubs from various European leagues. They could define matches, choose outcomes like 1X2 or over/under 2.5 goals, assign dates, and—crucially—receive phone notifications when the matches ended.

I had so much fun building it. I loved the immediacy of Android Studio. I could see results instantly, even on my personal phone. I even designed the UI myself—experimenting with colors, layouts, and a logo (which got me to learn a bit of Photoshop along the way).

But despite how fun it was, I knew it wasn’t quite there yet.

It was, at that stage, little more than a glorified note-taking app. It hadn’t yet solved the core problem. It wasn’t a product—it was a personal sandbox. But I already had ideas for version 2.

Things Getting Live

To become truly useful, BetAssist needed one critical upgrade: live scores.

I didn’t want to get tangled in web scraping, and there was no chance I’d enter scores manually. So I started looking for APIs. That’s when I found Football-Data.org—a free API with access to near real-time football scores from major European leagues.

The free tier was generous and perfect for my needs. Even today, I think it’s a gem: live scores (with a ~10-minute delay), solid coverage, and reasonable rate limits. For a small monthly fee, you could even unlock global data—but I never needed to.

Quick overview on the BetAssist Architecture

Like many early developers, I started small. A university friend and I built a backend in PHP (yes, forgive us—it was all we knew besides Java), hosted on Heroku. Every 10 minutes, the backend would ping the Football-Data API, collect score updates, and store them in Google Firestore.

Why Firestore? It integrated seamlessly with Android, had a generous free tier, and—let’s be honest—I wasn’t ready for anything more complex at that point. But it worked. And looking back, it was kind of impressive that it worked at all.

Eventually, I added a section for browsing upcoming matches, with quick actions to start building betslips. And most importantly, live score notifications were now in place. The betslip lifecycle was finally complete.

BetAssist had become a real product.

And it was the best feeling in the world.

Growing Together

With the app working, I couldn’t wait to share it with the world. I created a developer account on the Google Play Store and prepared for launch.

Original screenshots from the BetAssist app.

I’ll spare you the gritty details (maybe another blog post someday), but publishing your first app is a trip. Keystore generation, signing builds, making screenshots, writing copy, creating privacy policies—it’s a lot.

But eventually, BetAssist was live.

Seeing real people download and review something you built is electrifying. The download count ticked up. Comments started appearing. It wasn’t millions of users—but it was mine.

Over the years, the app grew, and so did I. I added match predictions (basic regression models running on the device), partnered with websites, improved the design, and refactored endlessly as my coding skills matured.

At one point, I even monetized the app. I added banners, and later a paid “Pro” version without ads. To my surprise, it actually brought in some money. Not a fortune, but enough to feel real.

Eventually, I stopped the monetization. I wasn’t sure whether it was fully legal to earn revenue without a proper partita IVA (Italian VAT number), and I didn’t want to risk it.

But truthfully, the money was never the point.

The Present

Today, BetAssist is mostly in hibernation.

The Heroku backend was shut down about a year ago. I think the app is still available on the Play Store, though only partially functional.

BetAssist was never meant to be a business. It was my lab. It was where I learned to write real code, ship to real users, and fix real bugs.

It was the first time I saw something go from an idea in my head to a thing in people’s hands. And I believe every developer needs that kind of project—one that belongs entirely to them.

In the end, the most important feature of BetAssist wasn’t live scores, push notifications, or betting logic. It was momentum—the creative spark it gave me, the confidence it built, the curiosity it unlocked.

So if you’re a developer stuck in tutorials, wondering what to build next—just start. Solve your own problem. Scratch your own itch. It doesn’t have to be revolutionary. It just has to matter to you.

Because sometimes, the best way to grow isn’t by reading more books. It’s by betting on yourself.

And honestly? That’s a bet worth taking.