Temporal Electronic Signature

Temporal Electronic Signature is a demonstration of Temporal Node.js SDK used with XState to write workflows. By implementing an electronic signature system, we have to use all most important features of Temporal: activities, signals, queries, timers. Thanks to XState, the code we have to write is more predictable and prevents race conditions to happen.

validated-signature.mp4

Temporal Meetup

Watch the presentation of this project at the November 2021 Temporal Meetup.

What can be done with the application?

• User selects a PDF document and validates her choice. It creates a signature procedure.
• Uploaded document is shown and the user has to validate her choice, or cancel the procedure.
• An email address is asked. A confirmation code will be sent to this address that will unblock the procedure.
• The user has to fill the code she received by email.
• If the code was correct, the document is signed and shown to the user.
• If the procedure is not validated after one minute, it expires automatically.

How it works

The Stack

The application is built around three packages: app, api and temporal. The front-end is built on SvelteKit and TailwindCSS. The back-end uses AdonisJS.

The Workflow

The workflow is impleted using XState. XState is a library to create state machines in JavaScript. A state machine is a way to represent code with explicit states, that can be in one state at a time, and that goes from one state to another one via transitions. Statecharts are an improvement of state machines that bring some interesting features, such as hierarchical states, delayed transitions or service invokation. These features are used in the workflow.

Let's see how the workflow is organized with states. Open the visualizer

Setup

Those are the instructions to launch the signature system locally.

Except docker-compose package, all commands will have to be executed in separate shells and kept alive.

Dependencies

First, let's install dependencies at the root of the repository.

yarn install

Temporal

We have to launch Temporal server and Temporal worker.

Environment variables

Go to packages/temporal directory, create a .env from .env.example.

You will need credentials to authenticate to a SMTP server. If you do not have one, you can use your Gmail account credentials. If you have enabled 2FA on your Google account, you might need an additional step.

Temporal server

Execute the following command:

cd packages/docker-compose

docker-compose up -d

Temporal worker

Launch a Temporal worker:

cd packages/temporal

yarn start.watch

If you encounter issues, such as dyld: lazy symbol binding failed: Symbol not found, try the following actions:

• Install Node.js version 14
• Install node-gyp: npm install -g node-gyp

Back-end

Go to packages/api directory, create a .env by copying .env.example.

Then launch the API with the following command.

cd packages/api

yarn dev

Front-end

Launch SvelteKit development server with the following command.

cd packages/app

yarn dev

The front-end will then be accessible at http://localhost:3000.

If not, check the URL printed in the logs.