HTMX QUTE QUARKUS

Description

It began as a simple project, a way to learn how to build hypermedia applications using HTMX. But as you dive deeper, new ideas emerge, leading to more exploration in search of insights. This journey is fascinating but time-consuming. Eventually, I found myself building a scalable, high-performance, and maintainable web application. With an enterprise Java background, the journey took shape quickly!

For the server side, I chose Quarkus to embrace the reactive programming model offered by the Mutiny library. Quarkus itself has a robust and well-developed ecosystem, including tools like Qute for template rendering, Quarkus REST, CSRF protection, authorization, Hibernate Panache, and more—all of which sped up development. I’ve never been a big fan of the Spring ecosystem and had been looking for a replacement; Quarkus has more than fulfilled that role.

Coming from a background in enterprise microservices, I wanted to deepen my understanding of architectural design and used this project as a means to explore these patterns. I ended up adopting the Ports & Adapters (Hexagonal) architecture. The resulting structure made the project remarkably flexible and scalable, especially useful for larger applications. It allows the application to be modularized into smaller, manageable instances. EventBus from Vert.x was invaluable, enabling communication between REST and domain layers using the CQRS pattern, which naturally supports scalability through its request/reply model. Scaling the application with additional instances became almost seamless.

Of course, the heart of this project was HTMX. I’m not a fan of the current state of web development, especially when simple enterprise web pages require a new language and a mountain of libraries just to manage basic operations. To me, this approach adds unnecessary mental overhead and resource strain. Ideally, the client should be lightweight and resource-efficient. HTMX was exactly what I’d been seeking—a way to develop without the bulk and redundancy. For years, I struggled to resonate with REST, until I began reading Hypermedia Systems and traced the evolution of the web. I had a revelation: modern web practices had drifted from the fundamentals, resulting in bloated and convoluted stacks.

The learning curve was steep; mastering HTMX meant rewriting the entire application multiple times. Impatience cost me initially, as I hadn’t yet grounded myself in the basics of the hypermedia approach.

Oh, I almost forgot—the core idea behind this project was to create a simple but effective to-do application. I’ve used plenty of note-taking apps, calendars, and other tools, but I wanted something I could deploy on my Raspberry Pi and rely on daily for managing life’s tasks. Inspired by the elegance of Vim, I aimed for simplicity and high functionality, with a similar minimalist vibe. The application even includes a command-line interface to manage tasks and other functions, which was a fun challenge to implement.

To build the command-line interface, I learned how to create a parser using a state machine, and I added real-time updates with Server-Sent Events (SSE), a technology that allows the server to push updates to clients asynchronously—a feature I’m thrilled with! I’m not a designer, but I’m really happy with the final look; it’s simple, functional, and fits my needs, and that’s what matters.

Now, I’m thrilled to finally launch this project and share it with the community. The journey taught me so much, taking over a year—but it was worth every moment.

Getting Started

Prerequisites

• maven 3.8.6+
• java 23+
• docker (database, identity-provider)

Installation

1. Clone the repo

   git clone [email protected]:nanobreaker/htmx-qute-quarkus.git

Usage

Build

./mvnw clean install -Pmonolith

Run

./mvnw quarkus:dev -Pmonolith 

Roadmap

• Add calendar functionality
  • Calendar domain model
  • Calendar repository
  • Calendar commands & queries
  • Calendar command & queries handlers
  • Calendar resource (REST)
• Integrate with Debezium & Apache Pulsar
  • Build Outbox implementation to update User, Todo and Calendar based on domain events
  • Domain events will be generated by Debezium
  • Apache Pulsar (similar to Kafka) to use as transport layer for events delivery
• Split monolith into microservices
  • User microservice
  • Todo microservice
  • Calendar microservice
• Create script to set up local development cluster
• Create GitHub actions
  • Run E2E tests
  • Build project artifacts and publish to public nexus repository
  • Build docker images and publish to public repository
  • Deploy application to dev cluster

Spikes

• Is it worth implementing Aggregate Root pattern for the domain layer?
• Is it worth using Apache Pulsar with Debezium for such small project?
• Good practices for handling authentication/authorization in micro-service cluster

Ports & Adapters Diagram

Simplified structure

• Primary Adapters

  • REST
  • Messaging System

• Primary Ports

  • Commands (change domain model state)
    • User Commands
    • Todo Commands
    • Calendar Commands
  • Queries (query models)
    • User Queries
    • Todo Queries
    • Calendar Queries

• Domain

  • Domain Models
    • User Model
    • Todo Model
    • Calendar Model
  • Command Handlers
    • User Command Handlers
    • Todo Command Handlers
    • Calendar Command Handlers
  • Query Handlers
    • User Query Handlers
    • Todo Query Handlers
    • Calendar Query Handlers

• Secondary Adapters

  • Database drivers
    • postgresql

• Secondary Ports

  • Repositories
    • User Repository
    • Todo Repository
    • Calendar Repository

High level overview

Adding project specific details

Change-Data-Capture Flow Diagram

Licensing

The code in this project is licensed under MIT license. Check LICENSE for further details.