cristianoliveira / distributex

A POC of a federated architecture using HTMX & NGINX - micro-frontends/services (same thing)

distributex

This is a POC of a federated architecture combining the Xs of NGINX and HTMX

(AKA microfrontends/microservices same thing)

Architecture

Tech stack

• Main app: HTMX, NGINX, and Tailwind
• Service 1 (Todo list) - Golang & Sqlite
• Service 2 (Chat) - Rust & Websockets
• Service 3 (Tech News) - Python & Hackernews API
• Docker

Why?

I wanted to understand how much I could stretch the idea and how hard would be to have micro frontends and services using HTMX. Spoiler alert, it's surprisingly easy due to HATEOAS.

Main goals

As a dev, you should be able to do/have:

• A DX & UX isolation, which means accessing the service URL gives you the same UX as in the main APP.
• Freedom of choice, it shouldn't matter the stack you pick for the services as long you respect the protocol
• Communication via events not only on the backend but also on the frontend side, thanks to an HTTP header convention (HX-trigger)

Current state

• Main app
  • Serve index.html
  • Proxy requests to services
  • Different clients/themes
    • http://localhost:4040/index.html
    • http://localhost:4040/retro.html
• Todo service
  • Add item
  • Remove item
  • Mark as done
  • Make it reactive to changes from other sessions (websocket?)
• Chat service
  • Allow pick nickname
  • Join a room
  • Send and receive messages
• News service
  • Allow fetch latest news
  • Allow managing favorite news
• Main app serving widgets
  • Todo service
  • Chat service
  • News service
  • Fallback for service loading
  • Handle errors
• Implement the 3rd service
• Cross services communication via events
  • Events emmited by one app is able to trigger another app to do something Eg: When a user adds a new todo the chat app sends a message to the room. See HX-trigger
• Describe infra and deploy a demo to AWS

Getting started

Requirements

Make sure you have

• docker
• docker compose

If you are on OSX we recommend installing colima as a container runtime

Running

make start

That's it, you should be able to access the main application at http://localhost:4040

You also should be able to access the microservices at:

• Todo list manager - http://localhost:4001/
• Chat service - http://localhost:4002/
• Tech News reader - http://localhost:4003/

Live reload mode

You need funzzy (sorry?)

First, start the services with make start then in another terminal do:

make watch

distributex's Issues

feat: handling error gracefully

Currently errors are only logged into stdout. Let's implement a close to real example of error handling for the POC

URLs in README.md return 404

This would probably be better as a PR than as an issue. Unfortunately, I do not have the repo permissions to push a branch and open a PR.

The URLs for the chat and todo service in the Running section of the README return 404s because the routes are not implemented:

You also should be able to access the microservices at:
  - Todo list manager - http://localhost:4001/
  - Chat service - http://localhost:4002/
  - Tech News reader - http://localhost:4003/

This can be resolved in chat by redirecting / to /chat:

use axum::{
  response::Redirect,  // this is new
  routing::{get, post},
  Router,
};
...
let app = Router::new()
.route("/", get(|| async { Redirect::permanent("/chat") })) // this is new
.route("/chat", get(crate::http_handlers::index_page))
...

This can be resolved in todo by redirecting / to /todos:

...
router := mux.NewRouter().StrictSlash(true)

router.HandleFunc("/", Redirect()).Methods("GET") // this is new
router.HandleFunc("/todos", IndexHandler(repo)).Methods("GET")
...

func Redirect() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		http.Redirect(w, r, "/todos", http.StatusSeeOther)
	}
}