$ open source · GPL-3.0 — need a commercial license? imqueue.com →
// TUTORIAL — CHAPTER 1

Introduction

A step-by-step guide to building back-end services for a car-washing web application with @imqueue — for those who prefer to learn by example.

A car-wash booking app

In this tutorial we build the back-end for a car-wash booking application, one service at a time, covering the fundamentals of the @imqueue framework along the way.

Here is what the finished application looks like to its users:

Register screen Login screen Profile details screen Profile garage screen Time table screen

The complete source code for the tutorial application is available on GitHub.

Architecture

Let's say we're building the web application on a React/Relay/GraphQL front-end, served by a GraphQL API endpoint that sits in front of a set of @imqueue-based back-end services.

While a front-end team builds the user interface, we focus on the back-end. We split it into small, decoupled services that can be developed in parallel by small teams:

  • User service — manages user data. Stack: Node.js/TypeScript, @imqueue over Redis, MongoDB.
  • Auth service — handles authentication. Stack: Node.js/TypeScript, @imqueue over Redis, JSON Web Tokens.
  • Car service — serves car data. Stack: Node.js/TypeScript, @imqueue over Redis, a static data source cached in a custom in-memory store.
  • Time-Table service — manages reservations and reservation events. Stack: Node.js/TypeScript, @imqueue over Redis, PostgreSQL.
  • API service — a GraphQL endpoint that orchestrates access to the services above. Stack: Node.js/TypeScript, @imqueue over Redis, graphql, graphql-relay, express, express-graphql.

The high-level architecture looks like this:

Application high-level architecture A React/Relay/GraphQL front-end talks over GraphQL/HTTP to an API Service, which orchestrates four @imqueue back-end services over RPC: User (MongoDB), Auth (Redis/JWT), Car (in-memory) and Time-Table (PostgreSQL). FRONT-END BACK-END GraphQL / HTTP @imqueue · RPC Web App React / Relay / GraphQL API Service GraphQL endpoint User Service Node.js · TS Auth Service Node.js · TS Car Service Node.js · TS Time-Table Service Node.js · TS MongoDB Redis · JWT In-memory PostgreSQL

Setting up the toolchain

The @imqueue command-line tool can wire its scaffolding into third-party services — GitHub, DockerHub and Travis CI. When you create a service with the tool, you can get a ready-made repository, continuous integration and one-command Docker image builds out of the box. So the first step is to install and configure @imqueue/cli.

Prepare the development environment

You'll need Node.js 22.12 or newer, ideally installed via NVM. You'll also need Redis, MongoDB and PostgreSQL — install them however you prefer, whether via Docker images (Mongo, Redis, PostgreSQL) or directly on your system.

Install @imqueue/cli

The integrations with GitHub, DockerHub and Travis CI are entirely optional. Without them, the tool simply creates local folders and files; you choose during installation whether to enable them.

If you do want the integrations, prepare your GitHub and DockerHub namespaces (a personal account or an organisation) and create a GitHub personal access token granting @imqueue/cli permission to create and write to repositories in that namespace.

Then install the tool:

npm i -g @imqueue/cli

Installation ends with an interactive configuration wizard — follow the steps to finish configuring @imqueue/cli.

For the full setup details — requirements, upgrading and shell completions — see the Installation & Configuration chapters of the CLI User Guide.

With that in place, we're ready to create our first service.