Building an image processing app with GraphQL and async serverless

Here's how I used GraphQL to build an image processing app that converts an image to sepia asynchronously

Async image processing


  • Image processing is best done asynchronously so that the state is not lost when the app is refreshed
  • Serverless functions can be used to run the image processing logic
  • Realtime GraphQL helps you be in sync with the processing state
  • Hasura GraphQL Engine  gives instant realtime GraphQL APIs over Postgres
  • Source code: client, image processing logic

(We've also written a short tutorial on how to build an image storage integration with Hasura Cloud that auto-tags our images for us, with Cloudinary and Autocode.)


In this post we'll build a basic image processing app that lets you upload an image and add a sepia tone to it asynchronously. We will not go into the code subtleties as this is more of a philosophical rant about how async image processing apps can be built using realtime GraphQL and serverless.  

We'll use:

Hasura gives you realtime GraphQL APIs over any Postgres database
  • An event sourcing system to trigger external webhooks on mutations


  • Knowledge of consuming a GraphQL API
  • Knowledge of some front-end framework. An example is given with ReactJS, but you could use anything.


This app follows the 3factor.app architecture pattern. 3factor app is an architecture pattern for resilient and scalabale fullstack apps. Read more about building 3factor apps with event-driven programming. It involves:

  • Realtime GraphQL
  • Reliable Eventing
  • Async serverless
Older architecture vs 3factor architecture

In case of our image processing app, the flow boils down to:

  1. The client uploads the image to cloud and inserts the image URL into the database with a GraphQL mutation. The client then watches the changes in the database for that particular image with GraphQL subscriptions.
  2. When the image URL has been inserted in the database, Hasura's event system calls an external webhook with the image details
  3. The external webhook converts the image to sepia tone, uploads the converted image to cloud and updates the database with the converted image URL
  4. The client receives the update when the converted image has been uploaded to the database (GraphQL subscriptions)


First step is to get a realtime GraphQL server running in the form of Hasura GraphQL Engine.

Click here to deploy it to Heroku's free tier with free Postgres (no credit card required).

Data model

We need only one table for this app.

When you create this table called images, Hasura provides the following root fields in its GraphQL schema:

  • images: To query or subscribe to the data from images table (comes with clauses such as where, order_by, limit)
  • insert_images: To insert one or more images into the images table
  • update_images: To update one or more images in the images table
  • delete_images: To delete one or more images in the images table

Image processing logic

We need our image processing logic that takes our uploaded image and adds a sepia tone to it. This could be written in any language or framework and deployed on any platform. For example, in NodeJS, you can write this logic using JIMP and serverlessify it using Zeit. The code would look something like:

The above function simply takes an object of the following form, converts it to sepia and stores the converted image at /tmp/<id>.png.

	"id": 233,
	"image_uri": "https://mycloudbucket.com/image"

Once the image has been converted, you also want to update the converted image URI to the database.

Event sourcing

Hasura lets you define event triggers that listen on mutations and invoke an external webhook with the mutation data. We will create one such event trigger that listens on insert_images mutation and calls the webhook that performs the logic discussed above.

Creating an event trigger in Hasura

With this, our backend is ready.


Most of the logic happens on the backend, so the front-end stays fairly clean. The front-end has two screens:

  • Upload screen: Uploads image to cloud, inserts the image URL in the database and redirects to the Convert screen with URL param id=<image_id>
  • Convert screen: Waits for the image to get processed and shows the converted image

Upload screen

This screen does the following:

  • Takes image from user
  • Uploads image to cloud
  • Inserts this image in the database with GraphQL mutation
  • Redirects to the new screen with URL parameter id=<image_id> where image_id is the unique id of the inserted image

The GraphQL mutation for inserting the image to the database looks like:

The above mutation inserts the image URI to database and returns the id of the inserted row. Next, you redirect to the Convert screen where you wait for the processed image.

Convert screen

In the convert screen, you look at the id of the image in URL parameters and make a live query to the database with GraphQL subscriptions. The subscription looks like:

While rendering the UI, you would check if the received  converted_image_uri is null. If it is, you show a loading indicator, or you show the converted image. If done in React with Apollo's Subscription components, it would look something like:

As you see, in the above component:

  1. If there is an error in subscription, we render some error UI.
  2. If the subscription is in loading state, we show a loading UI.
  3. If the subscription response is empty i.e. there is no row in the database where id is equal to the given id, we say that the id in the URL parameters is invalid.
  4. If we get a response but the converted_image_uri is null, we assume that the processing is still in progress
  5. If we have a valid converted_image_uri, we render it.

Finishing up

We discussed a pattern to build async image processing applications. You could use this architecture to build mostly all kinds of async applications. Check out 3factor.app and hasura.io to know more about building resilient and scalable fullstack applications.

If you have any questions, stack them up in the comments and they'll be answered ASAP.

26 Mar, 2019
Subscribe to stay up-to-date on all things Hasura. One newsletter, once a month.
Accelerate development and data access with radically reduced complexity.