Document OCR web app

This tutorial shows you how to use Modal to deploy a fully serverless React + FastAPI application. We’re going to build a simple “Receipt Parser” web app that submits OCR transcription tasks to a separate Modal app defined in the Job Queue tutorial, polls until the task is completed, and displays the results. Try it out for yourself here.

receipt parser frontend

Basic setup

Let’s get the imports out of the way and define a Stub.

import fastapi
import fastapi.staticfiles

import modal
import modal.aio
from pathlib import Path

stub = modal.Stub("doc_ocr_webapp")

Modal works with any ASGI or WSGI web framework. Here, we choose to use FastAPI.

web_app = fastapi.FastAPI()

Define endpoints

We need two endpoints: one to accept an image and submit it to the Modal job queue, and another to poll for the results of the job.

In parse, we’re going to submit tasks to the function defined in the Job Queue tutorial, so we import it first using modal.aio_lookup.

We call .submit() on the function handle we imported above, to kick off our function without blocking on the results. submit returns a unique ID for the function call, that we can use later to poll for its result."/parse")
async def parse(request: fastapi.Request):
    # Use aio_lookup since we're in an async context.
    parse_receipt = modal.lookup("doc_ocr_jobs", "parse_receipt")

    form = await request.form()
    receipt = await form["receipt"].read()
    call = parse_receipt.submit(receipt)
    return {"call_id": call.object_id}

/result uses the provided call_id to instantiate a modal.FunctionCall object, and attempt to get its result. If the call hasn’t finished yet, we return a 202 status code, which indicates that the server is still working on the job.

async def poll_results(call_id: str):
    from modal.functions import FunctionCall

    function_call = FunctionCall.from_id(call_id)
        result = function_call.get(timeout=0)
    except TimeoutError:
        return fastapi.responses.JSONResponse(status_code=202)

    return result

Finally, we mount the static files for our front-end. We’ve made a simple React app that hits the two endpoints defined above. To package these files with our app, first we get the local assets path, and then create a modal Mount that mounts this directory at /assets inside our container. Then, we instruct FastAPI to serve this static file directory at our rooth path.

assets_path = Path(__file__).parent / "doc_ocr_frontend"

@stub.asgi(mounts=[modal.Mount("/assets", local_dir=assets_path)])
def wrapper():
    web_app.mount("/", fastapi.staticfiles.StaticFiles(directory="/assets", html=True))

    return web_app


That’s all! To deploy your application, run

modal app deploy

If successful, this will print a URL for your app, that you can navigate to from your browser 🎉 .

receipt parser processed


If desired, instead of deploying, we can serve our app ephemerally. In this case, Modal watches all the mounted files, and updates the app if anything changes.

if __name__ == "__main__":

The raw source code for this example can be found on GitHub.