Hi!

This is the first article, but definitely not the last one, about headless solutions for online stores and websites.

What is Medusa.js?

Medusa.js is a framework for building headless online stores, where the back-end is based on Node.js and TypeScript. The front-end, can be built with anything. By default, Medusa.js supports Next.js, but you can easily choose Astro or Nuxt.js instead.

Why did we choose Medusa.js?

We chose this framework for several reasons.

The first one is that it is, and will remain, open source, while also offering ready-to-use modules from the start.

The Medusa.js team is doing a great job!

The second reason is that it is a headless solution, which means the back-end and front-end work together independently through a REST API.

The third reason is that the framework is based on Node.js, fully typed, and designed with modularity and flexibility in mind. This was important for our team because we work with technologies based on Node.js, React.js, and Next.js on a daily basis.

What was the reason behind the project?

The need was to build an online store where users could shop online while also connecting the shopping experience with the offline world.

To support vending machines, we needed a flexible and efficient solution. Modularity was also important, as it allowed us to:

• manage multiple sales channels, where one sales channel corresponds to exactly one location,

• connect a selected payment method,

• display products available in the store before purchase,

• show users their previously purchased products in their account after logging in, whether they bought them online or offline.

Architecture

The vending machine has three modes: purchase, return, and service.

• Purchase mode - the customer can buy a product from the fridge by taking it from a specific scale.

• Return mode - the customer can return an empty product container by placing it back on the scale.

• Service mode - the administrator can open the device and, for example, restock it, assign the right products to a specific scale or synchronize products.

Additional technical solutions

Additional solutions we implemented:

• Firestore - between the user and the back-end for fast data exchange,

• MQTT - between the machine and the back-end, we used a lightweight communication protocol often used in IoT systems,

• Stripe - a system for handling payments.

What features did we implement?

Our solution included several interesting features:

1. Sessions - we needed a single source of truth for sessions.

   When we open the device, we need to communicate with it asynchronously.
   In the database, we store data such as:

   1. session ID,

   2. device ID,

   3. hub ID,

   4. locker ID,

   5. session type,

   6. current code,

   7. the mode in which the device was opened,

   8. user ID.

2. Session preview - the administrator can view all currently created sessions. If something happened and the device did not send us information about being closed, we can check it here and analyze the situation.

3. Turning service mode on and off - the administrator can open the device and organize it or replace products.

4. Machine configuration - we added the option to add new devices and assign them to a given location. Thanks to this, one back end can handle multiple vending machines from a single place.

5. Product assignment - products are assigned to a specific scale, and there can be many of them. Apart from basic data, each product also contains information such as the minimum and maximum product weight.

6. Synchronization with the device - the source of truth for products is the product management module in Medusa.js. After assigning products to scales, we can synchronize them with the device using a single button.

7. Notifications - using our automation and notification plugin, we implemented custom notifications that inform administrators about the state of the device.
   For example, when a device goes offline, the administrator receives a notification in Slack that something is happening with it. This allows them to react very quickly.

What did we learn?

The most important lesson is that you need to test. And then test again.

Machines can be unreliable, and you never know what might happen. Together with the team responsible for the software on the hardware side, we faced countless edge cases. We had to predict different behaviors of the user, the software, and the hardware.

More than once, the doors were supposed to open, but then… nothing. The signal was sent, but the software on the hardware side did not detect it. Or it detected it, but the update failed.

Another example was when the device sent us information that the doors were closed, but a simple bug appeared on the back-end side, and the session did not close correctly. The same happened the other way around: for some reason, the doors did not close, and the session could remain open.

Another challenge was the question: what happens if someone bumps into the machine? Will the signal be sent or not?

It is hard to count how many attempts we made when calibrating and assigning weights to the scales.

Summary

This was a very interesting challenge for us because we had not previously worked on projects where communication with IoT systems was required. It is a completely different approach, because here we could not rely on synchronous responses in the same way as in standard web solutions.

Medusa.js is a very flexible and modular solution based on modern technology. It offers a lot of possibilities while maintaining quality and performance.

I hope you enjoyed the article and learned something new about the possibilities this framework offers, as well as how we approached solving these problems.

Cześć!

Jest to pierwszy artykuł i nie ostatni o rozwiązaniach Headless dla sklepów i stron internetowych.

Czym jest framework Medusa.js?

W skrócie Medusa.js to framework do budowy sklepów internetowych o strukturze Headless gdzie Back-end jest oparty o Node.js oraz TypeScript. Natomiast Front-end może być zbudowany z czegokolwiek - bazowo Medusa.js wspiera Next.js ale bez problemu można wybrać Astro albo Nuxt.js.

Dlaczego wybraliśmy Medusa.js?

Wybraliśmy ten framework z kilku powodów. Pierwszym z nich jest to, że jest i pozostanie Open Source, mając już na starcie gotowe moduły.
Zespół Medusa.js wykonuje świetną robotę!

Drugim powodem jest to, że jest to rozwiązanie Headless, czyli back-end i front-end współpracują ze sobą, w niezależny sposób opierając się o REST-API.

Trzecim powodem to framework oparty o Node.js, w pełni otypowany i stworzony z myślą o modularności i elastyczności. Dla naszego zespołu było to ważne gdyż na co dzień pracujemy w technologiach opartych o Node.js, React.js, Next.js.

Jaki był powód?

Potrzebą było zbudowanie sklepu internetowego w którym można zrobić zakupy online jednocześnie łącząc zakupy w świecie offline.

Do obsługi Vendingów potrzebowaliśmy elastycznego i wydajnego rozwiązania. Istotna jest także modułowość która pozwoliło na:

• zarządzanie wieloma kanałami sprzedaży (jeden kanał sprzedaży odpowiada dokładnie jednej lokalizacji),

• podpięciem wybranej formy płatności,

• przedstawienia produktów które są dostępne, w sklepie przed zakupem,

• możliwością wyświetlenie użytkownikowi wcześniej zakupionych produktów w jego panelu po zalogowaniu (czy to w kanale online czy offline).

Architektura:

Vending posiada trzy tryby: zakupowy, zwrotowy i serwisowy.

1. Zakupowy - klient może kupić produkt znajdujący się w lodówce, biorąc go z konkretnej wagi.

2. Zwrotowy - klient może zwrócić pusty pojemnik po produkcie odkładając z powrotem na wagę.

3. Serwisowy - administrator może otworzyć urządzenie i np. uzupełnić magazyn, przypisać odpowiednie produkty do danej wagi czy też zrobić synchronizację produktów.

Dodatkowe rozwiązania technologiczne:

Dodatkowe rozwiązania które wdrożyliśmy:

• Firestore - między użytkownikiem, a back-endem do szybkiej wymiany danych,

• MQTT - między maszyną, a back-endem zastosowaliśmy lekki protokół komunikacyjny często używany w systemach IoT,

• Stripe - system do obsługi płatności

Jakie wdrożyliśmy funkcjonalności?

W naszym rozwiązaniu znalazło się kilka ciekawych funkcjonalności:

1. Sesje - potrzebowaliśmy jedno źródło prawdy dla sesji.
   W momencie gdy otwieramy urządzenie to musimy komunikować się z nim w trybie asynchronicznym. W bazie danych zapisujemy dane tj.

   1. ID sesji,

   2. ID urządzenia,

   3. ID hab’u,

   4. ID locker,

   5. Typ sesji,

   6. Aktualny kod,

   7. Tryb w jakim zostało otwarte urządzenie,

   8. ID użytkownika,

2. Podgląd sesji - administrator jest wstanie podejrzeć wszystkie obecne utworzone sesje. Jeśli wydarzyła się jakaś sytuacja i urządzenie nie wysłało do nas informacji o zamknięciu to możemy w tym miejscu to sprawdzić i zrobić analizę.

3. Włączanie i wyłączanie trybu serwisowego - administrator jest wstanie otworzyć urządzenie i zrobić w nim porządek czy też wymienić produkty.

4. Konfiguracja maszyn - dodaliśmy możliwość dodawania nowych urządzeń i przypisywania ich do danej lokalizacji. Dzięki temu, jeden back-end może odpowiadać za obsługę wielu Vendingów z jednego miejsca.

5. Przypisywanie produktów - produkty są przypisywane do konkretnej wagi których może być wiele. Każdy produkt oprócz danych podstawowych zawiera jeszcze np. minimalną i maksymalną wagę produktu.

6. Synchronizacja z urządzeniem - źródłem prawdy dla produktów jest moduł do zarządzania produktami w Medusa.js. Po przypisaniu produktów do wag, za pomocą jednego przycisku możemy zrobić synchronizację z urządzeniem.

7. Powiadomienia - za pomocą naszego pluginu do Automatyzacji i Notyfikacji wdrożyliśmy customowe notyfikacje informujące o stanie urządzenia. Na przykład gdy urządzenie wejdzie w tryb Offline, to administrator dostaje powiadomienie do komunikatora Slack, że coś się z nim dzieje. Dzięki temu bardzo szybko można zareagować.

Czego się nauczyliśmy?

Najważniejsza lekcja jest taka, że.. trzeba robić testy, i jeszcze raz testy. Maszyny są zawodne i nigdy nie wiesz co Cię może spotkać. Razem z zespołem odpowiedzialnym za software po stronie hardware’u, mieliśmy niezliczoną serię różnych edge-case’ów. Musieliśmy przewidzieć różne zachowania użytkownika, software’u i hardware’u.

Nie raz było tak, że drzwi powinny się otworzyć, a tu.. klops - sygnał został wysłany, jednak software po stronie hardware’u go nie wykrył.. albo wykrył ale aktualizacja się nie powiodła.

Innym przykładem jest to, że urządzenie wysyłało do nas informacje o zamkniętych drzwiach ale pojawił się trywialny błąd po stronie back-endu, i sesja się nie zamykała poprawnie. Tak samo było w drugą stronę, drzwi z jakiegoś powodu się nie zamknęły i sesja mogła nie zostać zamknięta.

Kolejną zagwozdką było pytanie - co jeśli maszyną ktoś szturchnie, sygnał zostanie wysłany czy nie zostanie?

To ile prób robiliśmy w przypadku kalibracji i nadawaniu wag, uWagom, aż ciężko policzyć.

Podsumowując

Było to dla nas bardzo ciekawe wyzwanie gdyż wcześniej nie mieliśmy okazji pracować w projektach w których potrzebą było komunikacja z systemami IoT, a to jest totalnie inne podejście gdyż tutaj nie moglibyśmy polegać na synchronicznych odpowiedziach tak, jak w przypadku standardowych rozwiązaniach webowych.

Medusa.js to bardzo elastyczne i modułowe rozwiązanie oparte na nowoczesnej technologii pozwalające na bardzo wiele zachowując przy tym jakość i szybkość działania.

Mam nadzieję, że artykuł się spodobał i dowiedziałeś się czegoś nowego o możliwościach jakie oferuje ten framework, a także jak podeszliśmy do rozwiązania problemów.