Blog of software writer Chee Yeo

FastAPI Realtime events with mongodb changestreams and S3 file uploads

Tue, 17 Mar 2026 00:00:00 +0000

APPLICATION CODE: https://github.com/cheeyeo/FastAPI_S3_Uploads

In a Previous post, I discussed how to setup a mongodb change stream on a collection and using it through the pyMongo driver. In this post, I hope to explain how I used the same concept but in a FastAPI application to provide real-time updates on file uploads.

While working on a file upload example using FastAPI and S3, I came across the issue of how to report progress on a file upload via the API backend to a React dashboard. The solution I came up with was:

Using the mongodb change stream to broadcast progress updates. Since each upload is already stored as a document, we can enable watch on the collection and publish an update to the progress as it progresses.
Create a websocket backend endpoint, that allows the React UI to connect to whenever an upload occurs. This websocket will contain the progress updates.
Update the React UI whenever progress is received to show a progress bar.

The change stream code is as shown below:

async def watch_uploads_changes():
    pipeline = [
        {
            "$match": {
                "operationType": {"$in": ["insert", "update", "replace", "delete"]}
            }
        }
    ]
    # call watch on the uploads collection; async_uploads ref the uploads collection
    async with await async_uploads.watch(
        pipeline, full_document="updateLookup", full_document_before_change="required"
    ) as stream:
        async for change in stream:
            doc_id = change["documentKey"]["_id"]
            before = change.get("fullDocumentBeforeChange", {})
            after = change.get("fullDocument", {})

            await broadcast(
                {
                    "event": change["operationType"],
                    "document_id": str(doc_id),
                    "before": before,
                    "after": after,
                }
            )

async_uploads refers to the uploads collection fetched by the pymongo async client. The watch loop monitors changes to the uploads collection for any inserts, updates and replacements. Within the async with loop, we iterate over the stream iterator for each change event as it arrives. The event is passed to the broadcast method which publishes the events to all subscribed websockets.

The websocket endpoint is as follows, which is a generic example from the documentation:

CLIENTS = set()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    CLIENTS.add(websocket)

    try:
        while True:
            await websocket.receive_text()
    except WebSocketDisconnect:
        CLIENTS.remove(websocket)

We store each websocket into a CLIENTS set. Whenever we broadcast an event, we iterate over all the websockets as follows:

async def broadcast(data):
    text = json.dumps(data, default=str)
    for client in CLIENTS.copy():
        try:
            await client.send_text(text)
        except Exception:
            CLIENTS.remove(client)

While this is not the optimal solution, it works well for this example application.

Within the typescript code for the UI, we created an upload list and an upload card component for each upload initiated. Within each UploadCard object, we make a websocket connection to the backend. If the id in the data received matches the ID of the upload card and the event from the change stream is of type ‘update’, we start to update the progress bar component.

import { useState, useEffect, useRef } from 'react';
import ProgressBar from "./ProgressBar";

const WS_URL = 'ws://localhost:8000/ws';

export type UploadCardProps = {
  uploadId: string;
  filename: string;
  initialProgress: number;
};

const UploadCard = ({ uploadId, filename, initialProgress }: UploadCardProps) => {
  const [progress, setProgress] = useState<number>(initialProgress);
  const ws = useRef<WebSocket | null>(null);
  const [message, setMessage] = useState<string>('');

  useEffect(() => {
    ws.current = new WebSocket(WS_URL);

    if (!ws.current || ws.current.readyState === WebSocket.CLOSED) {
      const ws2 = new WebSocket('ws://localhost:8001')
      ws.current = ws2
    }

    ws.current.onopen = () => {
      console.log(`WebSocket for ${filename} connected`);
      // Optionally send a message to subscribe to updates for this uploadId
      // ws.current?.send(JSON.stringify({ subscribe_to_upload: uploadId }));
    };

    ws.current.onmessage = (event) => {
      try {
        const data = JSON.parse(event.data);

        // if error exists close WS and show error
        if (data.event === 'update' && data.document_id === uploadId && data.after.status === 'error') {
          console.log(data.after.exception);
          setMessage(data.after.exception);
          ws.current?.close()
        }

        if (data.event === 'update' && data.document_id === uploadId && typeof data.after.percentage === 'number') {
          setProgress(data.after.percentage);
        }

        if (data.after.percentage === 100) {
          // close websocket after completion
          setMessage(data.after.s3_key + '\n' + data.after.s3_url)
          ws.current?.close()
        }

      } catch (err) {
        console.error("Error parsing websocket message for uploadId", uploadId, err);
      }

    };

    ws.current.onerror = (error) => {
      console.error(`WebSocket error for ${filename}:`, error);
    };

    ws.current.onclose = () => {
      console.log(`WebSocket for ${filename} closed`);
    };

    return () => {
      if (ws.current && ws.current.readyState === WebSocket.OPEN) {
        ws.current.close()
      }
    };
  }, [uploadId, filename]);

  return (
    <div className="upload-card">
      <div className="upload-card-filename">{filename}</div>
      <ProgressBar 
        progress={progress} 
        progressText={progress > 0 ? `${Math.round(progress)}%` : 'Initializing...'} 
      />
      <div>
        <pre>
          {message}
        </pre>
      </div>
    </div>
  );
};

export default UploadCard;

Lastly, we need to start the watcher loop on application startup. We use the asynccontextmanager to define a lifespan context function which allows you to perform startup and shutdown tasks:

@asynccontextmanager
async def lifespan(app: FastAPI):
    task = asyncio.create_task(watch_uploads_changes())
    yield
    task.cancel()
    # close db clients on app exit
    await async_client.close()

app = FastAPI(
    title="File uploads example",
    description="Example of file uploads in FastAPI",
    version="1.0.0",
    lifespan=lifespan,
)

We pass the watch_uploads_changes function into the asyncio.create_task method which runs in its own coroutine. The yield passes control back to the FastAPI application. When the application exits, we perform cleanup by calling task.cancel() and close the mongodb client connection.

The boto3 client was used for uploads to S3. I used the upload_fileobj method as it allows you to pass extra config and a callback to report progress:

config = TransferConfig(
    multipart_chunksize=CHUNK_SIZE,
    multipart_threshold=5 * GB,
)

S3_CLIENT.upload_fileobj(
    Fileobj=file.file,
    Bucket=S3_BUCKET,
    Key=filename,
    ExtraArgs={"ContentType": file.content_type},
    Config=config,
    Callback=ProgressPercentage(file, upload_id),
)

The TransferConfig object from boto3 enables you to switch on multipart upload if the threshold is exceeded. In this example, we set it to a maximum of 5 GB with a chunk size of 1024MB.

We define a ProgressPercentage object to track the progress. This is defined in the boto3 docs as a function but you can also provide your own classes so long as it implements call:

class ProgressPercentage:
    def __init__(self, file: UploadFile, id: str):
        self._filename = file.filename
        self._size = float(file.size)
        self._seen_so_far = 0
        self._lock = threading.Lock()
        self._id = id

    def __call__(self, bytes_amount):
        with self._lock:
            self._seen_so_far += bytes_amount
            percentage = (self._seen_so_far / self._size) * 100

            # Below uses non-async mongo client as the callback is non async
            nonasync_uploads.update_one(
                {"_id": ObjectId(self._id)},
                {
                    "$set": UpdateUploadSchema(
                        current=self._seen_so_far,
                        percentage=percentage,
                        status="in progress",
                        updated_at=datetime.now(),
                    ).model_dump(exclude_unset=True)
                },
            )

Within the __call__ function, we used the byes_amount parameter which is passed by the boto3 library to calculate the percentage of how much has been uploaded. We use the non-async client to update the associated record of its progress.

Since we are writing to the collection for each update, we trigger the watch loop for change streams which then publishes data to the UI via websockets.

Using the hybrid approach, I was able to track and display progress bars for S3 Uploads.

You can test it out at https://github.com/cheeyeo/FastAPI_S3_Uploads

MongoDB changestream in python

Tue, 10 Mar 2026 00:00:00 +0000

In a Previous Post, I discussed how to setup and run a mongodb replicaset locally for the purpose of using MongoDB changestreams. This post will discuss an approach of using changestreams in the context of using the python mongodb driver.

MongoDB changestreams publish or broadcast real-time changes made to a database or a collection as change events, which allow applications to subscribe to real-time changes and react to them accordingly. A change stream is a real-time stream of database changes that an application can react to in real time. Examples of such usage might include analytics dashboard or a live ordering system.

To enable change streams, there is a set of minimal criteria to be met:

The database must be in a replica set or sharded cluster.
The database must use WiredTiger storage engine v1.
The replica set or sharded cluster must use replica set protocol version 1.

The example below uses the pymongo.MongoClient to create a test database and a collection of users to demonstrate:

DATABASE_URL = f"mongodb://{get_settings().mongo_db_root_username}:{get_settings().mongo_db_root_password}@mongo1:27017,mongo2:27017,mongo3:27017/"

client = MongoClient(DATABASE_URL)
db = client.get_database("teststreams")

users = db.create_collection("users")

pipeline = [
    {
        "$match": {
            "operationType": {"$in": ["insert", "update", "replace", "delete"]}
        }
    }
]

with users.watch(pipeline, full_document="updateLookup") as stream:
    for change in stream:
        print(change)

We created a configuration option called pipeline which specifies the operation type we are interested in watching. In this example, we are interested in change events for inserts, updates, replace and deletes. By default, change streams only return the delta of fields during the update operation. To return the most current majority-commited version of the updated document, we set full_document="updateLookup" which returns a full_document field that shows the current version of the document affected by the operation.

The watch function is an iterator loop that blocks while waiting for change events to arrive. If we were to create an additional user of name Alice, we receive the following insert event:

{
    '_id': {
      '_data': 'XXXX'
    }, 
    'operationType': 'insert', 
    'clusterTime': Timestamp(1773749951, 1), 
    'wallTime': datetime.datetime(2026, 3, 10, 12, 19, 11, 657000), 
    'fullDocument': {
        '_id': ObjectId('69b946bf78a20b5c76acb971'), 
        'name': 'Alice'
    }, 
    'ns': {
        'db': 'teststreams', 
        'coll': 'users'
    }, 
    'documentKey': {
        '_id': ObjectId('69b946bf78a20b5c76acb971')
    }
}

Note that the operationType is set to insert and the full document is provided under the fullDocument key since we set full_document to be updateLookup.

If we were to add a new field of email to the same user, we trigger a replace event as follows:

{
    '_id': {
        '_data': 'XXXX'
    }, 
    'operationType': 'replace', 
    'clusterTime': Timestamp(1773750282, 1), 
    'wallTime': datetime.datetime(2026, 3, 10, 12, 24, 42, 534000), 
    'fullDocument': {
        '_id': ObjectId('69b946bf78a20b5c76acb971'), 
        'name': 'Alice', 
        'email': 'test@example.com'
    }, 
    'ns': {
        'db': 'teststreams', 
        'coll': 'users'
    }, 
    'documentKey': {
        '_id': ObjectId('69b946bf78a20b5c76acb971')
    }
}

If we were interested in obtaining a version of the document before and after the changes are made, we need to set changeStreamPreAndPostImages to true when creating the collection.

Pre-image refers to the document before it was updated. Post-image refers to the document after it was updated. According to the documentation, when using fullDocument: "updateLookup" with a $match filter, we need to set it as a document deletion returns a null value in the fullDocument field which prevents the change stream from finding the resume token and would return a resume token not found error.

The updated codebase is now as follows:

DATABASE_URL = f"mongodb://{get_settings().mongo_db_root_username}:{get_settings().mongo_db_root_password}@mongo1:27017,mongo2:27017,mongo3:27017/"

client = MongoClient(DATABASE_URL)
db = client.get_database("teststreams")
users = db.create_collection("users", changeStreamPreAndPostImages={"enabled": True})

pipeline = [
    {
        "$match": {
            "operationType": {"$in": ["insert", "update", "replace", "delete"]}
        }
    }
]

with users.watch(pipeline, full_document="updateLookup", full_document_before_change="required") as stream:
    for change in stream:
        print(change)

The returned event now includes a fullDocument and a fullDocumentBeforeChange fields. The below shows and update event on the user record after the email field is changed:

{
    '_id': {
        '_data': 'XXXX'
    }, 
    'operationType': 'replace', 
    'clusterTime': Timestamp(1773752106, 1),
    'wallTime': datetime.datetime(2026, 3, 10, 12, 55, 6, 639000),
    'fullDocument': {
        '_id': ObjectId('69b94d6978a20b5c76acb975'),
        'name': 'Alice', 
        'email': 'alice@example.com'
    }, 
    'ns': {
        'db': 'teststreams', 
        'coll': 'users'
    }, 
    'documentKey': {'_id': ObjectId('69b94d6978a20b5c76acb975')}, 'fullDocumentBeforeChange': {
        '_id': ObjectId('69b94d6978a20b5c76acb975'), 
        'name': 'Alice', 
        'email': 'test@example.com'
    }
}

The full gist is provided below:

Using the built-in change stream feature, we are able to track changes to individual records, collections and databases. This allows us to build event-driven applications such as progress updates and custom user alerts on demand without polling.

The next post will examine how to incorporate this into a working FastAPI application to provide asynchronous real-time updates.

Running a MongoDB ReplicaSet in docker

Sun, 01 Mar 2026 00:00:00 +0000

While working on a web API project which required the use of mongodb, I had to switch the configuration from a single node setup to running a replicaset in order to test MongoDB changestreams. While it is straightforwards to run a single node mongoDB database, it gets a bit challenging to run a multi node replicaset using docker compose.

As per the example provided on the official mongodb website, you can use the following bash script to set up a 3 node replicaset:

#!/usr/bin/env bash


docker network create mongoCluster

docker run -d --rm -p 27017:27017 --name mongo1 --network mongoCluster mongo:latest mongod --replSet myReplicaSet --bind_ip localhost,mongo1

docker run -d --rm -p 27018:27017 --name mongo2 --network mongoCluster mongo:latest mongod --replSet myReplicaSet --bind_ip localhost,mongo2
 
docker run -d --rm -p 27019:27017 --name mongo3 --network mongoCluster mongo:latest mongod --replSet myReplicaSet --bind_ip localhost,mongo3

docker exec -it mongo1 mongosh --eval "rs.initiate({
 _id: \"myReplicaSet\",
 members: [
   {_id: 0, host: \"mongo1\"},
   {_id: 1, host: \"mongo2\"},
   {_id: 2, host: \"mongo3\"}
 ]
})"

However, I still need to login to the running primary container in order to run additional scripts such as setting up an application database and users.

The mongodb container has the ability to run custom setup scripts mounted into the /docker-entrypoint-initdb.d directoty. It supports both .js files which are executed by mongosh and .sh files which are executed by the shell. An ideal approach would be to use docker compose to orchestrate the setup. The docker compose would need to overcome the following issues:

Mounting a custom keyfile to fix the authentication error for running containers in a replicaset.
Running the custom setup scripts to initialize the application database and users.
Running a utility container such as mongo express for development.

The gist below is a complete docker compose template I used to overcome the issues mentioned above:

We designate mongo1 as the primary node. We overwrite the entrypoint script to generate a custom keyfile usig openssl. Note that this should be outside of the template but for brevity we leave it in for now. This is the part that failed for me and after numerous attempts, one of the key point is to chown the keyfile to the mongodb group and user and shown on line 9. We proceed to initialize the replicaset on line 10, passing in the keyfile and replicaset name.

Note that we also saved the keyfile in a shared volume of sharedconfig which makes the keyfile accessible to the other containers. The setup for mongo2 and mongo3 remains the same as mongo1 but passing the arguments directly into the entrypoint script of the container.

On line 24, we mount a user script to create the application database and user:

db = db.getSiblingDB(process.env.MONGO_INITDB_DATABASE);

db.createUser({
    user: process.env.MONGO_USER,
    pwd: process.env.MONGO_PASSWORD,
    roles: [{
        role: 'readWrite',
        db: process.env.MONGO_INITDB_DATABASE,
    }]
});

db.createCollection("uploads", {changeStreamPreAndPostImages: { enabled: true }});

The script initializes the application database using db.getSibilingDB. By default, mongosh defaults to using the test database. It proceeds to create a database user which is used by the application to connect to the database. The user has read write permissions on the database. It continues to create a collection which has MongoDB changestreams enabled.

In line 65, we included a new container called mongo-setup. This is like a utility container that runs mongo-setup.sh to register the nodes of the replicaset:

#!/usr/bin/env bash


# Wait until the mongo-master responds
until mongosh --host mongo1 -u ${MONGO_DB_ROOT_USERNAME} -p ${MONGO_DB_ROOT_PASSWORD} --eval "db.adminCommand('ping')" > /dev/null 2>&1; do
  sleep 2
done

echo "mongo1 is ready. Initiating replica set..."

mongosh --host mongo1 -u ${MONGO_DB_ROOT_USERNAME} -p ${MONGO_DB_ROOT_PASSWORD} --eval "try { rs.status() } catch (err) { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo1:27017',priority:2},{_id:1,host:'mongo2:27017',priority:1},{_id:2,host:'mongo3:27017',priority:1}]});}"

The script checks that the primary is ready and once it is, it runs the rs command to register all three nodes into a replicaset based on a priority order:

rs.initiate({
  _id:'rs0',
  members:[
        {
            _id:0,host:'mongo1:27017',priority:2
        },
        {
            _id:1,host:'mongo2:27017',priority:1
        },
        {
            _id:2,host:'mongo3:27017',priority:1
        }
    ]
})

From the above, it adds all the mongo containers to the replicaset rs0 with mongo1 being the primary and the other containers are designated as secondary.

The final piece is to enable mongo-express to provide an admin UI to the database. This is shown in line 78 where we use the mongo-express image. Note that as we are running a replicaset now, we need to reference all 3 nodes as such:

mongodb://${MONGO_DB_ROOT_USERNAME}:${MONGO_DB_ROOT_PASSWORD}@mongo1:27017,mongo2:27017,mongo3:27017/?authSource=admin

The above would allow the container to access all the databases in the replicaset.

Note that we need to create a custom network which is used by all the containers as the database and replicaset initialization script can only reference hostnames.

Running docker exec -it mongo1 mongosh -u sa -p Password123 --eval "rs.conf()" on the primary shows the configuration of the replicaset:

The screenshot below shows mongo-express UI running.

While it is not perfect, it does solve the issue of manually running a custom shell script. The full gist can be viewed here.

Using Gemini CLI for software development

Thu, 26 Feb 2026 00:00:00 +0000

This post is a review of my current experience of using Gemini CLI for software development. One of the key skills as a software developer at the moment, is to be ready for working alongside a foundational model such as Gemini. I have seen countless posts and job specs asking for ability to work, create and review code generated by a foundational model, in an approach known as vibe coding.

My understanding of vibe coding as a concept is that we provide the model with a list of features and requirements as context and allow the model to autogenerate the entire project for you. In my use case, I’m interested to see how this applies to current projects that have already been developed, in the areas of automation.

I use one of my current personal project as a testbed, a simple FastAPI application to upload image files to S3. It has a single API endpoint /upload/s3 and I have been testing all the upload via the Swagger UI Docs. I have the current features which I want to delegate to Gemini CLI to handle:

Create a React UI frontend to handle file uploads via the API.
Run basic linting and formatting using ruff of the python backend.
Create a set of pre-commit hooks for ruff.

Before all the above, we need to install the Gemini CLI and set it up first. On Linux, it can be installed globally via the Gemini CLI installation guide. It is recommended to obtain an API Key via the Google AI Studio app and export it as an environment variable using GEMINI_API_KEY or via the command prompt after starting the CLI with gemini.

Start the CLI within the application project folder. On the CLI, I ran the command /init to allow Gemini to analyze the current application project folder and generate a custom GEMINI.md, which will be used as context to the Gemini agent.

Next, you can enter your own custom prompt into the CLI to the gemini agent. In my first request, I asked the agent to generate a simple React UI to work with the FastAPI upload service using the following prompt:

> implement a react ui frontend to allow file uploads to the api

The agent proceeded to create a sub directory called frontend with a simple but fully functioning React UI that includes a file uploader to allow multipart uploads to the API. The screenshot belows show the artifacts created:

The agent also updated the GEMINI.md file with its own outputs and steps.

I examined and validated the React source code created in TypeScript and it appears to be valid code. Next, I installed the frontend dependencies using npm in its sub directory and started the API in another terminal for testing. The UI can indeed upload files via the API to S3 as shown in the screenshot below:

The next automation step was to run linting and formatting on the python backend code using ruff. Although I could run the commands manually, I wanted to test the agent ability in executing shell commands. I passed the following prompt to the agent:

@main.py run ruff check
@main.py run ruff format

The agent was able to detect and format the main.py file using ruff automatically as shown in the screenshot below:

Lastly, I asked the agent to setup pre-commit hooks using ruff. Unfortunately, I did not mention using the uv tool so it was unable to find it and subsequently pre-commit was not installed correctly. However, it did manage to create the .pre-commit-config.yaml file and updated the GEMINI.md with the required instructions. The version of pre-commit installed for ruff was the older version so I had to manually update it in the generated config file:

To allow the gemini CLI access to the local file system, you would need to grant it permission. Every interaction with the file system would ask for your permission first using one of the following three options:

Allow once: Runs the command one time.
Allow always: Trusts this specific command for the rest of the session.
Deny: Stops the agent.

Since it’s able to run shell commands, the recommendation is to start the CLI in sandbox mode, which runs all shell commands inside a Docker container:

gemini --sandbox

Within minutes of setting up and running Gemini CLI, I managed to create a working React UI and setup automatic linting with pre-commit hooks. This is a productivity boost. Rather than using it for code generation, I will attempt to focus on how this can be used to automate development tasks and use it as an additional tool in the SDLC process.

You can extend the capabilities of the Gemini CLI by using agents or extensions. In future posts, I will explore the capabilities of these features. For instance, using the Github extension, you could connect the GIthub repository to your workflow and get the agent to generate features from a todo list which you can review as a pull request.

Custom commands allow you to package frequently used prompts into a single package which can be shared and distributed within a global or project level.

In summary, the use of Gemini CLI in SDLC has been interesting and productive in the short time I experimented with it. I will be using it in future endeavours to understand how it could benefit software development. One of the interesing thing I found was that its not always right. When asked to install the pre-commit hooks, it installed the older version, which I had to manually adjust. One must still check its outputs to ensure it is accurate.

Review of paper 'DeepSeek-OCR Contexts optical compression'

Mon, 02 Feb 2026 00:00:00 +0000

In the paper DeepSeek-OCR: Contexts Optical Compression, the authors proposed a novel approach to transform long LLM contexts into images as a form of compression. The core idea is to encode long textual context as an image before sending it to an LLM in order to save on the number of textual tokens sent to an LLM as images use less tokens and can encode more textual information compared to text alone. Optical compression through the use of vision tokens can result in higher compression ratios.

DeepSeek-OCR is a new architecture that supports this approach described above. It consists of the following components:

DeepEncoder
Decoder

Firstly, an image input is converted into 16x16 patches, similar to how Vision Transformers work. The patches are sent as input into the encoder. The encoder is responsible for extracting image features and apply compression to visual representations.

The DeepEncoder consists of 2 main models connected sequentially:

SAM-Base 80M model
CLIP-Large 300M model

The image below shows the architecture of the DeepSeek-OCR model:

Between the two vision models are 2 additional convolutional layers which the paper labeled as compressors that performs further downsampling of the vision tokens.

The idea is that the SAM ViT model outputs vision tokens ( local / self attention ) which the compressor downsamples before they are sent to the CLIP model to apply global attention to, which becomes the embedding layer. The first patch embedding layer from the CLIP model is removed to achieve this.

Since the 2 layer convolutional kernel performs 16x downsampling, a single 1024x1024 image can result in only 256 tokens.

The decoder is a DeepSeek-3B model which uses a MoE architecture. During inference, the model can activate 6 out of 64 routed experts and 2 shared experts with about 570M activated parameters. The model is chosen as it has the efficiency of a small language model.

The decoder tries to reconstruct the original text representation from the compressed latent vision tokens output from the DeepEncoder and learns a non-linear mapping through OCR-style training approaches.

In terms of training, the entire architecture is trained as an end-to-end OCR model. The training dataset is carefully curated to include a mix of OCR as well as text and image data. 4 sets of data are curated as follows:

OCR 1.0, which consists of traditional OCR tasks such as scene image and document OCR
OCR 2.0, which includes generated charts, formulas and plane geometry with annotations
General vision data
Text-only data

For OCR 1.0 dataset, the authors curated 30M pages of PDF data which includes over 100 languages collected from the Internet.

For OCR 2.0 dataset, over 10M synthetic images of charts such as bar and composite charts are created using pyechatys and matplotlib. The dataset also includes chemical formulas using the SMILES format from PubChem as data source. Additional plane geometry images are also created via Slow Perception which has data augmentation applied in the form of geometric translation-invariant transforms, resultig in an additional 1M images.

A similar approach of using techniques in DeepSeek-VL2 was used to generate general vision data for tasks such as captioning, detection and grounding.

Another dataset of text-only data is also created in-house and contains only text. All the text data is processed to be of length 8192 tokens which is the same sequence length of DeepSeek-OCR

For evaluation, the authors evaluated the model using the following conditions:

Compression-decompression
Document parsing

In terms of evaluating compression-decompression, only documents with tokens from 600 to 1300 from the English portion of the Fox benchmark was used for evaluation. A single prompt of “\nFree OCR." was used to control the model's output. All input images are resized to 512x512 or 640x640. The ground truth text was tokenized using the DeepSeek-OCR tokenizer and the number of text tokens was compared against the number of vision tokens used for decoding. From the results, a 10x compression can achieve a precision of 97% but the prevision falls as the compression increases but at 20x compression, a precision of 60% can still be reached. The authors attributed the decline to the complex layout of long documents and that they become blurred at 512x512 or 640x640 resolution. A viable solution is to render texts on single layout pages.

The table below shows the compression-decompression results:

For evaluating document parsing, the model was evaluated against the OmniDocBench benchmark, which is a benchmark for evaluating diverse document parsing in real-world scenarios. With only 100 vision tokens at 640x640 resolution, the model surpasses GOT-OCR2.0 which requires 256 tokens. The results also show that different types of documents require fewer tokens to achieve good results e.g. for books and documents, the model can achieve good performance with only 100 vision tokens. For newspapers with longer texts, more tokens are required for compression.

An additional set of qualitative studies are also carried out:

Deep Parsing
Multilingual recognition
General vision understanding

For deep parsing, the OCR 2.0 dataset allows the model to accept prompts to parse images within documents through secondary model calls. It can extract charts, geometry and chemical formulas with a unified prompt. For books and documents, deep parsing can output dense captions for natural images in documents. Using prompts, the model can automatically identity what type of image and it is and output the required results.

In terms of multilingual recognition, the model has been trained on over 100 different languages and can show that it can recognise layout and multilingual text for different languages.

For general vision understanding, the model has been trained on an additional set of syntheic images and as such, it is able to identity and extract images from within images using prompts.

The paper shows the promise of using vision tokens to compress complex textual information. One good use of this could be in the compression of long, multi-turn histories with LLM interactions.

The paper also points out that using OCR evaluation techniques alone is insufficient to fully validate the context-optical compression and other more detailed evaluations are required for future studies.

@misc{wei2025deepseekocrcontextsopticalcompression,
      title={DeepSeek-OCR: Contexts Optical Compression}, 
      author={Haoran Wei and Yaofeng Sun and Yukun Li},
      year={2025},
      eprint={2510.18234},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2510.18234}, 
}

Introduction to Bedrock Agents

Mon, 19 Jan 2026 00:00:00 +0000

In previous posts, I discussed how to build a simple agent using Gemini that runs in the CLI using MCP protocol to provides tools. AWS Bedrock has the same concept of an agent but it differs slightly compared to the previously discussed manual approach.

AWS Bedrock is a model-as-a-service platform whereby you could create generative AI applications by invoking foundational models offered on the platform through API calls. There is no need to host or train models manually as it’s a fully managed service. Bedrock Agents allow you to build custom agents that leverages the foundational models offered by the same platform to create agentic workflows that can also integrate with existing AWS services such as Lambda and RDS.

As an example, assuming we are building a HR assistant agent that can query and update an employee’s holidays. This example is based on the materials from AWS Generative AI and AI Agents with Amazon Bedrock.

Firstly, we need to import the dependencies and create the bedrock clients using boto3:

import json
import time
import zipfile
from io import BytesIO
import uuid
import pprint
import boto3

sts_client = boto3.client('sts')
iam_client = boto3.client('iam')
lambda_client = boto3.client('lambda')
bedrock_agent_client = boto3.client('bedrock-agent')
bedrock_agent_runtime_client = boto3.client('bedrock-agent-runtime')

session = boto3.session.Session()
region = session.region_name
account_id = sts_client.get_caller_identity()["Account"]

Next, we define the foundation models to use for the agent:

  inference_profile = "us.amazon.nova-micro-v1:0"
  foundation_model = inference_profile[3:]

Bedrock agents don’t use MCP protocol to invoke tools. Instead, it uses lambda functions which we will define shortly. We need to create a lambda function that will have the corresponding code to retrieve and update employees’ holidays. We also need to store this information. To keep the example simple, we create a sqlite3 database which will be uploaded with the lambda code. The python snippet below generates some random employees and their vacation times:

# creating employee database to be used by lambda function
import sqlite3
import random
from datetime import date, timedelta

# Connect to the SQLite database (creates a new one if it doesn't exist)
conn = sqlite3.connect('employee_database.db')
c = conn.cursor()

# Create the employees table
c.execute('''CREATE TABLE IF NOT EXISTS employees
                (employee_id INTEGER PRIMARY KEY AUTOINCREMENT, employee_name TEXT, employee_job_title TEXT, employee_start_date TEXT, employee_employment_status TEXT)''')

# Create the vacations table
c.execute('''CREATE TABLE IF NOT EXISTS vacations
                (employee_id INTEGER, year INTEGER, employee_total_vacation_days INTEGER, employee_vacation_days_taken INTEGER, employee_vacation_days_available INTEGER, FOREIGN KEY(employee_id) REFERENCES employees(employee_id))''')

# Create the planned_vacations table
c.execute('''CREATE TABLE IF NOT EXISTS planned_vacations
                (employee_id INTEGER, vacation_start_date TEXT, vacation_end_date TEXT, vacation_days_taken INTEGER, FOREIGN KEY(employee_id) REFERENCES employees(employee_id))''')

# Generate some random data for 10 employees
employee_names = ['John Doe', 'Jane Smith', 'Bob Johnson', 'Alice Williams', 'Tom Brown', 'Emily Davis', 'Michael Wilson', 'Sarah Taylor', 'David Anderson', 'Jessica Thompson']
job_titles = ['Manager', 'Developer', 'Designer', 'Analyst', 'Accountant', 'Sales Representative']
employment_statuses = ['Active', 'Inactive']

for i in range(10):
    name = employee_names[i]
    job_title = random.choice(job_titles)
    start_date = date(2015 + random.randint(0, 7), random.randint(1, 12), random.randint(1, 28)).strftime('%Y−%m−%d')
    employment_status = random.choice(employment_statuses)
    c.execute("INSERT INTO employees (employee_name, employee_job_title, employee_start_date, employee_employment_status) VALUES (?, ?, ?, ?)", (name, job_title, start_date, employment_status))
    employee_id = c.lastrowid

    # Generate vacation data for the current employee
    for year in range(date.today().year, date.today().year - 3, -1):
        total_vacation_days = random.randint(10, 30)
        days_taken = random.randint(0, total_vacation_days)
        days_available = total_vacation_days - days_taken
        c.execute("INSERT INTO vacations (employee_id, year, employee_total_vacation_days, employee_vacation_days_taken, employee_vacation_days_available) VALUES (?, ?, ?, ?, ?)", (employee_id, year, total_vacation_days, days_taken, days_available))

        # Generate some planned vacations for the current employee and year
        num_planned_vacations = random.randint(0, 3)
        for _ in range(num_planned_vacations):
            start_date = date(year, random.randint(1, 12), random.randint(1, 28)).strftime('%Y−%m−%d')
            end_date = (date(int(start_date[:4]), int(start_date[5:7]), int(start_date[8:])) + timedelta(days=random.randint(1, 14))).strftime('%Y−%m−%d')
            days_taken = (date(int(end_date[:4]), int(end_date[5:7]), int(end_date[8:])) - date(int(start_date[:4]), int(start_date[5:7]), int(start_date[8:])))
            c.execute("INSERT INTO planned_vacations (employee_id, vacation_start_date, vacation_end_date, vacation_days_taken) VALUES (?, ?, ?, ?)", (employee_id, start_date, end_date, days_taken.days))

# Commit the changes and close the connection
conn.commit()
conn.close()

The lambda function defines two functions get_available_vacations_days and reserve_vacation_time which will be added to the tool definition later:

import os
import json
import stat
import shutil
import sqlite3
from datetime import datetime


shutil.copy('employee_database.db', '/tmp/employee_database.db')
os.chmod('/tmp/employee_database.db', stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH | stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH)


def get_available_vacations_days(employee_id):
    conn = sqlite3.connect('/tmp/employee_database.db')
    c = conn.cursor()

    if employee_id:
        c.execute("""
            SELECT employee_vacation_days_available
            FROM vacations
            WHERE employee_id = ?
            ORDER BY year DESC
            LIMIT 1
        """, (employee_id,))

        available_vacation_days = c.fetchone()

        if available_vacation_days:
            available_vacation_days = available_vacation_days[0]
            conn.close()
            return available_vacation_days
        else:
            conn.close()
            return f"No vacation data found for employed_id {employee_id}"
    else:
        conn.close()
        raise Exception("No employee id provided")
    

def reserve_vacation_time(employee_id, start_date, end_date):
    conn = sqlite3.connect("/tmp/employee_database.db")
    c = conn.cursor()

    if not employee_id or not start_date or not end_date:
        conn.close()
        raise Exception("Missing required parameters")
    
    # Calculate vacation days
    start = datetime.strptime(start_date, '%Y-%m-%d').date()
    end = datetime.strptime(end_date, '%Y-%m-%d').date()
    vacation_days = (end - start).days + 1

     # Insert into planned_vacations
    c.execute("""
        INSERT INTO planned_vacations (employee_id, vacation_start_date, vacation_end_date, vacation_days_taken)
        VALUES (?, ?, ?, ?)
    """, (employee_id, start_date, end_date, vacation_days))

    # Update available vacation days
    c.execute("""
        UPDATE vacations 
        SET employee_vacation_days_available = employee_vacation_days_available - ?,
            employee_vacation_days_taken = employee_vacation_days_taken + ?
        WHERE employee_id = ? AND year = (SELECT MAX(year) FROM vacations WHERE employee_id = ?)
    """, (vacation_days, vacation_days, employee_id, employee_id))
    
    conn.commit()
    conn.close()
    
    return f"Reserved {vacation_days} vacation days from {start_date} to {end_date} for employee {employee_id}"


def lambda_handler(event, context):
    print(event)
    print(context)

    try:
        parameters = event.get("parameters", [])
        function_name = event.get("function")

        # Parse parameters
        params_dict = {}
        for param in parameters:
            params_dict[param.get("name")] = param.get("value")

        # Route to appropriate function
        if function_name == "get_available_vacation_days":
            employee_id = int(params_dict.get("employee_id"))
            result = get_available_vacations_days(employee_id)
        elif function_name == "reserve_vacation_time":
            employee_id = int(params_dict.get("employee_id"))
            start_date = params_dict.get("start_date")
            end_date = params_dict.get("end_date")
            result = reserve_vacation_time(employee_id, start_date, end_date)
        else:
            raise Exception(f"Unknown function: {function_name}")
        
        # return Bedrock expected format
        return {
            "response": {
                "actionGroup": event.get("actionGroup"),
                "function": event.get("function"),
                "functionResponse": {
                    "responseBody": {
                        "TEXT": {
                            "body": json.dumps({"result": result})
                        }
                    }
                }
            }
        }
    except Exception as e:
        return {
            "response": {
                "actionGroup": event.get("actionGroup"),
                "function": event.get("function"),
                "functionResponse": {
                    "responseBody": {
                        "TEXT": {
                            "body": json.dumps({"error": str(e)})
                        }
                    }
                }
            }
        }

After creating the lambda function above, we can start to create the agent. Note that we need to define an IAM role for the agent:

agent_name = "hr-assistant-function-def"
agent_description = "Agent for providing HR assistance to manage vacation time"
agent_instruction = "You are an HR agent, helping employees understand HR policies and manage vacation time"
suffix = f"{region}-{account_id}"
agent_name = "hr-assistant-function-def"
agent_bedrock_allow_policy_name = f"{agent_name}-ba-{suffix}"
agent_role_name = f'AmazonBedrockExecutionRoleForAgents_{agent_name}'


bedrock_agent_bedrock_allow_policy_statement = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AmazonBedrockAgentBedrockFoundationModelPolicy",
            "Effect": "Allow",
            "Action": "bedrock:InvokeModel",
            "Resource": [
                f"arn:aws:bedrock:*::foundation-model/{foundation_model}",
                f"arn:aws:bedrock:*:*:inference-profile/{inference_profile}"
            ]
        },
        {
            "Sid": "AmazonBedrockAgentBedrockGetInferenceProfile",
            "Effect": "Allow",
            "Action":  [
                "bedrock:GetInferenceProfile",
                "bedrock:ListInferenceProfiles",
                "bedrock:UseInferenceProfile"
            ],
            "Resource": [
                f"arn:aws:bedrock:*:*:inference-profile/{inference_profile}"
            ]
        }
    ]
}

bedrock_policy_json = json.dumps(bedrock_agent_bedrock_allow_policy_statement)

agent_bedrock_policy = iam_client.create_policy(
    PolicyName=agent_bedrock_allow_policy_name,
    PolicyDocument=bedrock_policy_json
)

# Create IAM Role for the agent and attach IAM policies
assume_role_policy_document = {
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {
            "Service": "bedrock.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
    }]
}

assume_role_policy_document_json = json.dumps(assume_role_policy_document)
agent_role = iam_client.create_role(
    RoleName=agent_role_name,
    AssumeRolePolicyDocument=assume_role_policy_document_json
)

# Pause to make sure role is created
time.sleep(10)

iam_client.attach_role_policy(
    RoleName=agent_role_name,
    PolicyArn=agent_bedrock_policy['Policy']['Arn']
)

response = bedrock_agent_client.create_agent(
    agentName=agent_name,
    agentResourceRoleArn=agent_role['Role']['Arn'],
    description=agent_description,
    idleSessionTTLInSeconds=1800,
    foundationModel=inference_profile,
    instruction=agent_instruction,
)
agent_id = response['agent']['agentId']

Next, we create an action group to define a set of actions that the agent can perform on behalf of the user. In this example, we define the action group using function details as specified in Define function details:

agent_functions = [
    {
        'name': 'get_available_vacations_days',
        'description': 'get the number of vacations available for a certain employee',
        'parameters': {
            "employee_id": {
                "description": "the id of the employee to get the available vacations",
                "required": True,
                "type": "integer"
            }
        }
    },
    {
        'name': 'reserve_vacation_time',
        'description': 'reserve vacation time for a specific employee - you need all parameters to reserve vacation time',
        'parameters': {
            "employee_id": {
                "description": "the id of the employee for which time off will be reserved",
                "required": True,
                "type": "integer"
            },
            "start_date": {
                "description": "the start date for the vacation time",
                "required": True,
                "type": "string"
            },
            "end_date": {
                "description": "the end date for the vacation time",
                "required": True,
                "type": "string"
            }
        }
    },
]

agent_action_group_response = bedrock_agent_client.create_agent_action_group(
    agentId=agent_id,
    agentVersion='DRAFT',
    actionGroupExecutor={
        'lambda': lambda_function['FunctionArn']
    },
    actionGroupName=agent_action_group_name,
    functionSchema={
        'functions': agent_functions
    },
    description=agent_action_group_description
)

The agent will determine from the user’s conversation which action within an action group it needs to invoke. It will obtain all the required parameters and sends it to a Lambda function or returns control in response to an agent invocation. From the example above, we associate the lambda function created previously with the function schema.

Next, we need to add a Resource Policy to the Lambda function to allow the Bedrock Agent to invoke the lambda directly:

response = lambda_client.add_permission(
    FunctionName=lambda_function_name,
    StatementId='allow_bedrock',
    Action='lambda:InvokeFunction',
    Principal='bedrock.amazonaws.com',
    SourceArn=f"arn:aws:bedrock:{region}:{account_id}:agent/{agent_id}",
)

Finally, we create a draft version of the agent with an alias for testing:

response = bedrock_agent_client.prepare_agent(
    agentId=agent_id
)

agent_id = response['agentId']

response = bedrock_agent_client.create_agent_alias(
    agentAliasName='test-alias-1',
    agentId=agent_id
)

agent_alias_id = response["agentAlias"]["agentAliasId"]

To invoke the agent, we call invoke_agent on the bedrock agent runtime client:

## create a random id for session initiator id
session_id:str = str(uuid.uuid1())
enable_trace:bool = True
end_session:bool = False

# invoke the agent API
agentResponse = bedrock_agent_runtime_client.invoke_agent(
    inputText="How much vacation does the employee with employee_id set to 2 have available?",
    agentId=agent_id,
    agentAliasId=agent_alias_id, 
    sessionId=session_id,
    enableTrace=enable_trace, 
    endSession= end_session
)


event_stream = agentResponse['completion']
try:
    for event in event_stream:
        print(event)
        if 'chunk' in event:
            data = event['chunk']['bytes']
            print(f"Final answer ->\n{data.decode('utf8')}")
            agent_answer = data.decode('utf8')
            end_event_received = True
        elif 'trace' in event:
            logger.info(json.dumps(event['trace'], indent=2))
        else:
            raise Exception("unexpected event.", event)
except Exception as e:
    raise Exception("unexpected event.", e)

From above, we send a query to the agent to enquire how much holiday time employee number 2 has. The agent will forward the query to the foundational model which will parse the user query and invoke the matching lambda function in its tools definitions.

The following is an example output of the event object from the lambda function that was invoked from above:

{'messageVersion': '1.0', 'function': 'get_available_vacations_days', 'parameters': [{'name': 'employee_id', 'type': 'integer', 'value': '2'}], 'sessionId': '331e8192-f7c9-11f0-9152-cbe55b511572', 'agent': {'name': 'hr-assistant-function-def', 'version': '1', 'id': 'HOJVVJ4OFP', 'alias': 'SNXM4Q0LRN'}, 'actionGroup': 'VacationsActionGroup', 'sessionAttributes': {}, 'promptSessionAttributes': {}, 'inputText': 'How much vacation does the employee with employee_id set to 2 have available?'}

We can make another query to the agent to book 3 days of holidays for a specific employee as a test:

agentResponse = bedrock_agent_runtime_client.invoke_agent(
    inputText="Great. please reserve time off for the employee with employee_id set to 2 from 2026-01-24 to 2026-01-26",
    agentId=agent_id,
    agentAliasId=agent_alias_id, 
    sessionId=session_id,
    enableTrace=enable_trace, 
    endSession= end_session
)

logger.info(pprint.pprint(agentResponse))

event_stream = agentResponse['completion']
try:
    for event in event_stream:        
        if 'chunk' in event:
            data = event['chunk']['bytes']
            print(f"Final answer ->\n{data.decode('utf8')}")
            agent_answer = data.decode('utf8')
            end_event_received = True
            # End event indicates that the request finished successfully
        elif 'trace' in event:
            logger.info(json.dumps(event['trace'], indent=2))
        else:
            raise Exception("unexpected event.", event)
except Exception as e:
    raise Exception("unexpected event.", e)

The screenshot of the response indicated that the agent has booked the days off.

We can test that the agent has completed the task successfully by querying the remaining holidays for the same employee id again:

agentResponse = bedrock_agent_runtime_client.invoke_agent(
    inputText="How much vacation does the employee with employee_id set to 2 have available?",
    agentId=agent_id,
    agentAliasId=agent_alias_id, 
    sessionId=session_id,
    enableTrace=enable_trace, 
    endSession= end_session
)

logger.info(pprint.pprint(agentResponse))

event_stream = agentResponse['completion']
try:
    for event in event_stream:        
        if 'chunk' in event:
            data = event['chunk']['bytes']
            print(f"Final answer ->\n{data.decode('utf8')}")
            agent_answer = data.decode('utf8')
            end_event_received = True
        elif 'trace' in event:
            logger.info(json.dumps(event['trace'], indent=2))
        else:
            raise Exception("unexpected event.", event)
except Exception as e:
    raise Exception("unexpected event.", e)

The outputs above should show a reduction in the employee’s holidays entitlement from original 22 days to 19 days.

From the perspective of a developer, the following are advantages for building on Bedrock Agents:

Catalogue of foundational models to use
Can version and test agents individually
Use of Lambdas as tools for function calls
Able to associate IAM roles and policies for both agents and tools
Able to integrate with other AWS services such as IAM
Serverless approach means infrastructure is managed for you
Use of available frameworks such as LangChain and Kiro to speed up development

A working example of the agent can be found at this github repo

Upgrading Ubuntu

Mon, 05 Jan 2026 00:00:00 +0000

In previous attempts to update Ubuntu, I always back up and format the hard drive before reinstalling the new version of Ubuntu, known as a clean install. When trying to update Ubuntu from 20.04 to 22.04, I decided to perform an in place update instead using the update-manager-core provided by Ubuntu.

The update-manager-core is used by the desktop GUI Update Manager to manage package sources and release upgrade paths. It also contains the do-release-upgrade utility to perform version upgrades.

Firstly, we need to install update-manager-core:

sudo apt update
sudo apt upgrade

sudo apt install update-manager-core

To start the version upgrade, we invoke the do-release-upgrade utility:

  sudo do-release-upgrade

In my use case, the above failed with insufficient space in /boot which is where all the previous linux kernel versions are kept. To create sufficient space, I need to delete older kernel versions that are no longer in use. As a precaution, I kept at least 2 of the most recent kernel versions:

sudo dpkg -l | grep linux-image

sudo apt purge <linux kernel name>

sudo dpkg -l | grep linux-headers

sudo apt purge <linux header>

sudo apt autoremove --purge

Then I restarted the upgrade process again:

  sudo do-release-upgrade

Note that you will need to follow the on screen instructions by responding to the CLI. The upgrade tool will automatically walk through the upgrade process by asking the user to respond to certain changes such as upgrading services and removing old system packages.

Once completed, the system will prompt you to restart the system. Press Y to complete the process.

To confirm upgrade was successful:

lsb_release -a # checks version of ubuntu installed

uname -mrs # checks kernel version

Testing FastAPI with pytest and moto

Thu, 25 Dec 2025 00:00:00 +0000

In the previous series on building a FastAPI application, we integrated OAuth through Cognito into the application. To test the API together with Cognito, we need to be able to stub out the external Cognito API calls using the moto library.

Firstly, we install the test dependencies via uv using the dev flag, which means they will not be installed during the docker build with the --no-dev flag:

uv add --dev pytest pytest-cov pytest-mock "moto[all]"

The first approach is to work out how to mock the AWS Cognito API calls using moto library. As per the documentation, I created fake AWS credentials as a fixture and pass it into a separate fixture which uses the mock_aws context manager to create an initial UserPool and registered user for our tests:

@pytest.fixture(scope="session")
def aws_credentials():
    """Mocked AWS Credentials for moto."""
    os.environ["AWS_ACCESS_KEY_ID"] = "testing"
    os.environ["AWS_SECRET_ACCESS_KEY"] = "testing"
    os.environ["AWS_SECURITY_TOKEN"] = "testing"
    os.environ["AWS_SESSION_TOKEN"] = "testing"
    os.environ["AWS_DEFAULT_REGION"] = "us-west-1"
    os.environ["AWS_REGION"] = "us-west-1"


@pytest.fixture(scope="session")
def mock_cognito_client(aws_credentials):
    with mock_aws():
        cognito_client = boto3.client("cognito-idp", region_name="us-west-1")
        user_pool_id = cognito_client.create_user_pool(PoolName="TestUserPool")["UserPool"]["Id"]
        app_client = cognito_client.create_user_pool_client(
            UserPoolId=user_pool_id,
            ClientName="TestAppClient"
        )

        username = "test_username"
        password = "SecurePassword1234#$%"  # Password must meet security policies.
        email = "test_mail@test.com"

        cognito_client.sign_up(
            ClientId=app_client["UserPoolClient"]["ClientId"],
            Username=username,
            Password=password,
            UserAttributes=[
                {"Name": "email", "Value": email},
            ],
        )
        
        cognito_client.admin_confirm_sign_up(UserPoolId=user_pool_id, Username=username)

        yield AWSCognito(client=cognito_client, region="us-west-1", client_id=app_client["UserPoolClient"]["ClientId"], client_secret="SECRET", user_pool_id=user_pool_id)

The above creates a mock cognito idp client and uses it to create a user pool, user pool client and registers a test user into the user pool. We yield an instance of AWSCognito which is a wrapper around the cognito API. Any reference to this fixture will run in the mock_aws context block.

Next, we create a separate SQLModel Session for the test database. I’m running a separate postgresql database for the tests which will use separate credentials. The official tutorial suggests using in-memory sqlite3 database for the tests but I prefer the tests to run under the same conditions as the production database. There are 2 issues to overcome.

Firstly, for creating the test database schema dynamically, we need to use SQLModel.metadata.create_all function. We need to import SQLModel before the database models else it will not run the migrations.

Secondly, we also need to be able to get the database credentials dynamically either through exported environment variables or through the .env.test environment file. As per the dotenv library documentation, we merge both os.environ and dotenv_values into a single dict to construct the psql connection string. This would allow the tests to pick up the environment variables when run locally or via CI/CD pipelines. Finally, we yield the Session object:

@pytest.fixture(name="session", scope="session")
def session_fixture():
    config = {
        **os.environ,
        **dotenv_values(".env.test"),
    }

    postgresql_url = f"postgresql://{config.get('RDS_USERNAME')}:{config.get('RDS_PASSWORD')}@{config.get('RDS_HOSTNAME')}:{config.get('RDS_PORT')}/{config.get('RDS_DB_NAME')}"
    
    engine = create_engine(postgresql_url, connect_args={})
    
    SQLModel.metadata.create_all(engine)

    with Session(engine) as session:
        yield session

Next, we create a corresponding registered user in our test database, using the previous session fixture as a dependency:

@pytest.fixture(name="user", scope="session")
def user_fixture(session):
    db_user = User(
        username="test_username",
        email="test_mail@test.com",
        password=get_password_hash("SecurePassword1234#$%")
    )
    session.add(db_user)
    session.commit()
    session.refresh(db_user)

FastAPI provides a TestClient object which is used to interact with the API in the tests. This client object is a wrapper around the FastAPI application object. We yield this client in the client fixture. Since the application uses a database session as a dependency in its routes, we need to replace it with the session fixture we created earlier. We can use dependency_overrides to replace it with the session fixture. We also replace the cognito client dependency with the mock client fixture created earlier. The client fixture is as follows:

@pytest.fixture(name="client", scope="session")
def client_fixture(session, user, mock_cognito_client):
    # Overrides the database dependency to use the test session
    def get_session_override():
        return session
    
    # Overrides the cognito client dependency to use the test client
    def get_aws_cognito_override():
        return mock_cognito_client

    app = create_app()
    app.dependency_overrides[get_session] = get_session_override
    app.dependency_overrides[get_aws_cognito] = get_aws_cognito_override

    client = TestClient(app)
    yield client
    app.dependency_overrides.clear()

    # clear data from test database
    for model in [RandomItem, User]:
        stmt = delete(model)
        session.exec(stmt)
        session.commit()

We yield the client from the fixture. Once the tests using the fixture is completed, it performs teardown by calling app.dependency_overrides.clear(). We also clear up the test database by deleting any existing records for all the models.

Since the API routes are protected with an OAuth dependency, we need to be able to generate a token to pass it in our tests. We create a separate fixture to generate a test token which we can use in our tests that require authentication:

@pytest.fixture()
def token(user, mock_cognito_client, mock_token, client, monkeypatch):
    monkeypatch.setenv("AWS_REGION", mock_cognito_client.region)
    monkeypatch.setenv("AWS_USER_POOL_ID", mock_cognito_client.user_pool_id)
    monkeypatch.setenv("AWS_COGNITO_APP_CLIENT_ID", mock_cognito_client.client_id)
    monkeypatch.setenv("AWS_COGNITO_APP_CLIENT_SECRET", mock_cognito_client.client_secret)

    monkeypatch.setattr(AWSCognito, "decode_token", mock_token)

    resp = client.post("/users/login", data={"username": "test_username", "password": "SecurePassword1234#$%"})
    assert resp.status_code == 200
    token = resp.json()['access_token']
    assert token is not None

    return token

The token fixture uses some of the fixtures we create previously. It’s not possible to export an environment variable using os.environ in the fixtures as each test runs in a separate execution thread. We use pytest monkeypatch to set the environment. In this example, we are setting some of the environment variables which are required by the AWS Cognito class from the values extracted from the mock cognito client created in the earlier fixture.

One of the dependencies get_current_user_cognito receives the access token after the Cognito authentication and decodes it by fetching the JWKS from Cognito. In our previous post, we created a Lambda trigger to the UserPool which adds the custom user scopes during the Pre Token Generation. We stub the decode_token function in the cognito client to return a mock token response which contains those custom scopes.

Finally, we use the test client fixture to call the login route to obtain a token from the moto service, which will return the mock token when decode_token is called.

Using the above fixtures and setup, I was able to test some of the API routes:

def test_get_randoms_not_authenticated(client):
    response = client.get("/randoms")
    assert response.status_code == 401
    assert response.json() == {'detail': 'Not authenticated'}


def test_get_randoms(client, token):
    response = client.get("/randoms", headers={"Authorization": f"Bearer {token}"})
    assert response.status_code == 200
    assert response.json() == []

The functional tests for the user routes use a similar approach. For example, to test user signup:

def test_users_signup(client):
    resp = client.post("/users/signup", json={"username": "test", "email": "test@example.com", "password": "SecurePassword1234#$%"})
    assert resp.status_code == 201
    assert resp.json()["message"] == "User created successfully"
    assert "sub" in resp.json().keys()
    sub = resp.json()["sub"]

    resp = client.get(f"/users/{sub}")
    assert resp.status_code == 200
    user = resp.json()
    assert user["sub"] == sub
    assert user["username"] == "test"
    assert user["email"] == "test@example.com"

In order to test for exceptions thrown by the Cognito client, we use the mocker library to return specific exceptions before the actual API call. For example, to test an API response from an exception thrown by Cognito for a registered user that already exists, we could use mocker to patch the user_signup method to return an exception:

def test_users_signup_user_exists(mocker, client, mock_cognito_client):
    mocker.patch.object(mock_cognito_client, "user_signup", side_effect=ClientError(error_response={"Error": {"Code": "UsernameExistsException"}}, operation_name="user signup"))
    
    resp = client.post("/users/signup", json={"username": "test", "email": "test@example.com", "password": "SecurePassword1234#$%"})
    
    assert resp.status_code == 409
    assert resp.json() == {"detail": "Account with email exists"}

Using this approach, I was able to test both the API and Cognito service.

Below is the complete conftest.py file as detailed above.

The full source code can be found at https://github.com/cheeyeo/FastAPI-application-example/tree/testing

Securing FastAPI with OAuth and custom user scopes using AWS Cognito

Fri, 19 Dec 2025 00:00:00 +0000

In a previous post, I showed an example of integrating FastAPI with Cognito as an OAuth provider. Another advanced usage is to introduce scopes into the OAuth flow to refine the authorization of the API.

Scopes are an additional field within the access token that can be used to restrict access to API resources. The default scope returned by Cognito is aws.cognito.signin.user.admin me which allows the user to administer their own Cognito profile such as updating their username. Custom scopes are created by the developer to provide authorization to certain parts of the API, meaning certain FastAPI paths could have a OAuth2 scope declared as a security dependency via the Security function.

For example, the route below defines a Security dependeny with a custom me scope:

async def get_current_active_user(current_user: Annotated[User, Security(get_current_user_cognito, scopes=["me"])]):
    if current_user.disabled:
        raise HTTPException(status_code=400, detail="Inactive user")

    return current_user

Scopes are inherited in a tree-like hierarchy as explained in FastAPI OAuth Scopes Dependency. For example, using the previous function, if we were to create another Security dependency using it as an input, then the new security dependency will inherit the scopes as well as its own scopes:

async def get_current_active_user(current_user: Annotated[User, Security(get_current_user_cognito, scopes=["me"])]):
    if current_user.disabled:
        raise HTTPException(status_code=400, detail="Inactive user")

    return current_user

CurrentActiveUserRandoms = Annotated[User, Security(get_current_active_user, scopes=["randoms"])]

CurrentActiveUser = Annotated[User, Depends(get_current_active_user)]

@router.get("/users/me", response_model=UserPublic, tags=["Authentication"])
async def read_users_me(current_user: CurrentActiveUser):
    return current_user


@router.get(
    "/randoms/", response_model=list[RandomItemPublic], tags=["Random Items Management"]
)
async def read_randoms(
    session: SessionDep,
    user: CurrentActiveUserRandoms,
    offset: int = 0,
    limit: Annotated[int, Query(le=100)] = 100,
):
    randoms = session.exec(
        select(RandomItem)
        .where(RandomItem.user_id == user.id)
        .offset(offset)
        .limit(limit)
    ).all()
    return randoms

The path /users/me declared a dependency of CurrentActiveUser, which has a dependency on CurrentActiveUser, which has a dependency on get_current_active_user, which has a Security scope of me.

The path /randoms has a dependecy on CurrentActiveUserRandoms which has a dependency on get_current_active_user which has declared a scope of randoms but it has also inherited the security scope of me from get_current_active_user, which makes it a combined scope of [me, randoms]

To add custom scopes to an access token issued by Cognito, the recommended approach is to create a Resource server to define the custom scopes and a custom domain with TLS enabled. The application would need to call the Token Endpoint via the custom domain at <custom domain>/oauth/endpoint to retrieve the access token with the custom scopes. Usage of the Cognito API via cognito-idp boto3 client will not allow retrieval of the custom scopes.

Another approach is to create a Lambda trigger which would allow you to add the custom scopes into the access token before its returned from Cognito. This lambda function is known as a PreToken generation Lambda.

The lambda code for our PreToken generation lambda is as follows:

def lambda_handler(event, context):
    event['response'] = {
        "claimsAndScopeOverrideDetails": {
            "idTokenGeneration": {},  
            "accessTokenGeneration": {
                "scopesToAdd": ["me", "randoms"]  
            }
        }
    }

    return event

According to Lambda Triggers Pre token generation, we add to the event object an additional key of response with a claimsAndScopeOverrideDetails object where we define the additional scopes. For this simple example, we are defining them manually but in real world usage, we probably want to parse the event object to retrieve details on the cognito user and use that information to retrieve or obtain the required scopes dynamically.

Next, we link the lambda trigger to the user pool by going into Extensions > Lambda Triggers and selecting the Lambda function:

The OAuth2PasswordBearer flow has been updated to also include the list of acceptable scopes for the API:

  reusable_oauth2 = OAuth2PasswordBearer(tokenUrl="/users/login", scopes={"me": "Information about user", "randoms": "Random numbers API"})

The get_current_user_cognito dependency has a new parameter security_scopes which is of type SecurityScopes. It collates all the scopes declared in paths using the dependency hierarchy we discussed earlier. These scopes are acccessed using security_scopes.scopes. We perform a check in the function to see if the scope in path exists in the scopes returned in the access token payload. If it doesn’t exist, we turn a 401 permissions denied error:

async def get_current_user_cognito(security_scopes: SecurityScopes, cognito: CognitoDep, token: TokenDep):
    if security_scopes.scopes:
        authenticate_value = f"Bearer scope={security_scopes.scope_str}"
    else:
        authenticate_value = "Bearer"

    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": authenticate_value},
    )

    try:
        payload = cognito.decode_token(token)
        username = payload.get("username")
        if username is None:
            raise credentials_exception

        scope: str = payload.get("scope", "")
        token_scopes = scope.split(" ")
        token_data = TokenData(scopes=token_scopes, username=username)
    except InvalidTokenError:
        raise credentials_exception

    user = get_user(username)
    if user is None:
        raise credentials_exception

    for scope in security_scopes.scopes:
        if scope not in token_data.scopes:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="Not enough permissions",
                headers={"WWW-Authenticate": authenticate_value}
            )
    return user

Once all the above is setup, when we authenticate with Cognito, we should be able to see our list of custom scopes in the returned access token payload after decoding:

{
    'sub': '56c28244-1011-70bb-ba53-b6465b1a3b8e', 
    'iss': 'https://cognito-idp.eu-west-2.amazonaws.com/XXXXXXX', 
    'client_id': '7DDDDDDD', 
    'origin_jti': 'ec585efe-8fb9-481d-b9f8-c14d085c4107', 
    'event_id': '6b652188-3ca1-4a06-8326-aa004b969b8b', 
    'token_use': 'access', 
    'scope': 'aws.cognito.signin.user.admin me randoms', 
    'auth_time': 1766156060, 
    'exp': 1766159660, 
    'iat': 1766156061, 
    'jti': '810298d3-e0ec-403d-a447-a38016daf2bf', 
    'username': 'chee'
}

Note that under scope, the Lambda trigger has appended our custom scopes to the access token.

If we remove a custom scope from the Lambda, the authorization should fail for the path the scope is linked to. For example, if we remove me scope from the Lambda trigger and redeploy it, when we try to access /users/me it will fail with a 401 unauthorized error

Full source code can be viewed at the following Github Repository

Securing FastAPI with OAuth using AWS Cognito

Fri, 12 Dec 2025 00:00:00 +0000

In the original tutorial for securing a FastAPI application, the approach was to create the auth tokens from within the application itself. FastAPI provides built-in OAuth features such as OAuth2PasswordBearer to support password flow OAuth authentication.

There are different types of OAuth flows but the Authorization code grant is mostly used for web applications. It involves a user logging in with his username and password to a backend service in exchange for authentication tokens. These tokens are in the form of JWT ( Json Web Tokens ).

Using AWS Cognito, we can create a user pool to handle and manage user authentication and authorization.

An AWS Cognito user pool is a user directory for web and mobile applications. It provides both authentication and authorization. From the perspective of your application, the Cognito user pool is an OpenID Connect Identity Provider.

To create a User Pool, we navigate to the Cognito page in the console and click on create User Pool. For testing purposes, we only enable the following flows:

ALLOW_USER_PASSWORD_AUTH
ALLOW_ADMIN_USER_PASSWORD_AUTH
ALLOW_REFRESH_TOKEN_AUTH

We also need the following information about the user pool for the API calls later:

User pool ID ( User pool main page )
Client ID ( Application client main page )
Client Secret ( Application client main page )
AWS Region ( region the user pool created in )

Note that to allow for user signup, we need to enable Self-service signup under the Sign-up option of the user pool, else the Cognito API requests via the SDK will fail with An error occurred (NotAuthorizedException) when calling the SignUp operation: SignUp is not permitted for this user pool

We create a custom user router for the user authentication routes. One of the first routes would be for user registration:

class UserSignup(BaseModel):
    username: str = Field(max_length=50)
    email: EmailStr
    password: str


@router.post("/users/signup", tags=["Authentication"])
async def create_users(
    user: UserSignup,
    session: SessionDep,
    cognito: AWSCognito = Depends(get_aws_cognito),
):
    resp = AuthService.user_signup(user, cognito)
    db_user = User(
        username=user.username,
        email=user.email,
        password=get_password_hash(user.password),
    )
    session.add(db_user)
    session.commit()
    session.refresh(db_user)

    return resp

UsersSignup is a pydantic model that accepts and validates user inputs during the signup process. This is passed to the route /users/signup as a dependency. SessionDep is a dependency which yields a SQLModel session client and the AWSCognito is a dependency which is passed to the Cognito service class, which invokes the user create API call via the boto3 SDK.

Once the Cognito signup is successful, we create an instance of the user model using the same UserSignup pydantic model and saves the record into the database. Syncing between the remote cognito user pool and the database will be a subject for future posts.

The AuthService service class wraps the user registration:

class AuthService:
    @staticmethod
    def user_signup(user: UserSignup, cognito: AWSCognito):
        try:
            response = cognito.user_signup(user)
        except ClientError as e:
            if e.response["Error"]["Code"] == "UsernameExistsException":
                raise HTTPException(status_code=409, detail="account with email exists")
            else:
                raise HTTPException(status_code=500, detail="Internal server error")
        else:
            if response["ResponseMetadata"]["HTTPStatusCode"] == 200:
                content = {
                    "message": "User created successfully",
                    "sub": response["UserSub"],
                }
                return JSONResponse(content=content, status_code=201)

AWSCognito is a class that calls the Cognito API. Below shows the user signup function:

class AWSCognito:
    def __init__(self):
        self.client = boto3.client("cognito-idp", region_name=AWS_REGION)

    def user_signup(self, user: UserSignup):
        secret_hash = base64.b64encode(
            hmac.new(
                bytes(AWS_COGNITO_APP_CLIENT_SECRET, "utf-8"),
                bytes(user.username + AWS_COGNITO_APP_CLIENT_ID, "utf-8"),
                digestmod=hashlib.sha256,
            ).digest()
        ).decode()

        response = self.client.sign_up(
            ClientId=AWS_COGNITO_APP_CLIENT_ID,
            SecretHash=secret_hash,
            Username=user.username,
            Password=user.password,
            UserAttributes=[
                {"Name": "name", "Value": user.username},
                {"Name": "email", "Value": user.email},
            ],
        )

        return response

We call the sign_up method of the Cognito client and pass in the user attributes from the API signup route. Next, we also create a secret hash of the username and pass it with the request. The secret hash adds an additional layer of verification that the call originates from the given cognito user pool.

Once successful, we should see the user added under Users in the User pool. Cognito will send a 6 digit confirmation code via the user email. The user would need to call the confirm signup cognito endpoint, passing in the confirmation code to activate his account. Below is a snippet of the function calls:

class UserVerify(BaseModel):
    username: str
    confirmation_code: str


class AWSCognito:
    def __init__(self):
        self.client = boto3.client("cognito-idp", region_name=AWS_REGION)

    def verify_account(self, data: UserVerify):
        secret_hash = base64.b64encode(
            hmac.new(
                bytes(AWS_COGNITO_APP_CLIENT_SECRET, "utf-8"),
                bytes(data.username + AWS_COGNITO_APP_CLIENT_ID, "utf-8"),
                digestmod=hashlib.sha256,
            ).digest()
        ).decode()

        response = self.client.confirm_sign_up(
            ClientId=AWS_COGNITO_APP_CLIENT_ID,
            Username=data.username,
            ConfirmationCode=data.confirmation_code,
            SecretHash=secret_hash,
        )

        return response

@router.post("/users/verify", tags=["Authentication"])
async def verify(data: UserVerify, cognito: AWSCognito = Depends(get_aws_cognito)):
    return AuthService.verify_account(data, cognito)

Below is a screenshot of a registered user in Cognito after successful registration and confirmation:

Authentication and authorization

Within FastAPI, we use the OAuth2PasswordBearer flow which exchanges a username and password for a bearer token. Using the default Swagger UI, this option generates an Authorize link at the top left of the UI, which displays a form to get the user credentials. This calls the route "/users/login" which calls the Cognito API InitiateAuth method.

Below is the sample code for setting up the routes and FastAPI Dependencies:

class UserSignin(BaseModel):
    username: str
    password: str


@router.post("/users/login", tags=["Authentication"])
async def login(
    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
    cognito: AWSCognito = Depends(get_aws_cognito),
) -> Token:
    resp = AuthService.user_signin(
        UserSignin(username=form_data.username, password=form_data.password), cognito
    )
    content = json.loads(resp.body.decode("utf-8"))
    return Token(access_token=content.get("AccessToken"), token_type="bearer")


class AuthService:
    @staticmethod
    def user_signin(user: UserSignin, cognito: AWSCognito):
        try:
            response = cognito.user_signin(user)
        except ClientError as e:
            if e.response["Error"]["Code"] == "UserNotFoundException":
                raise HTTPException(status_code=404, detail="user does not exist")
            elif e.response["Error"]["Code"] == "UserNotConfirmedException":
                raise HTTPException(status_code=403, detail="verify your account")
            elif e.response["Error"]["Code"] == "NotAuthorizedException":
                raise HTTPException(
                    status_code=401, detail="incorrect username or password"
                )
            else:
                raise HTTPException(status_code=500, detail="Internal server error")
        else:
            content = {
                "message": "User signed in successfully",
                "AccessToken": response["AuthenticationResult"]["AccessToken"],
                "RefreshToken": response["AuthenticationResult"]["RefreshToken"],
            }

            return JSONResponse(content, status_code=200)


class AWSCognito:
    def __init__(self):
        self.client = boto3.client("cognito-idp", region_name=AWS_REGION)

        def user_signin(self, data: UserSignin):
            secret_hash = base64.b64encode(
                hmac.new(
                    bytes(AWS_COGNITO_APP_CLIENT_SECRET, "utf-8"),
                    bytes(data.username + AWS_COGNITO_APP_CLIENT_ID, "utf-8"),
                    digestmod=hashlib.sha256,
                ).digest()
            ).decode()

            response = self.client.initiate_auth(
                ClientId=AWS_COGNITO_APP_CLIENT_ID,
                AuthFlow="USER_PASSWORD_AUTH",
                AuthParameters={
                    "USERNAME": data.username,
                    "PASSWORD": data.password,
                    "SECRET_HASH": secret_hash,
                },
            )

        return response

Note that the route takes a dependency of OAuth2PasswordRequestForm which retrieves the username and password from the Swagger UI form mentioned before. This is passed to the UserSignin pydantic model which passes it to the boto3 SDK in cognito.user_signin. THe service returns both the access and refresh tokens as a json response.

If the login is successful, Cognito returns 3 tokens in the format of JWT ( Json Web Tokens ):

ID token, which contains claims about the user identity such as username and email.
Access token, which contains claims about the user, user groups and scopes.
Refresh token, which is used to obtain a new set of ID and access tokens.

The access token is used for API authorization through the use of scopes. This would require setting up a resource server in Cognito which will be shown in a future post.

In terms of authorization, we create a depdency of CurrentActiveUser which uses the previously obtained access token and retrives the username from the payload. We check if the user exists in the database and if so, we return the user record which is set as the current active user in the session. If not, we return a 404 exception:

reusable_oauth2 = OAuth2PasswordBearer(tokenUrl="/users/login")
TokenDep = Annotated[str, Depends(reusable_oauth2)]
CognitoDep = Annotated[AWSCognito, Depends(get_aws_cognito)]

class Token(BaseModel):
    access_token: str
    token_type: str

def get_user(username: str):
    for session in get_session():
        user = session.exec(select(User).where(User.username == username)).first()
        if not user:
            raise HTTPException(status_code=404, detail="User not found")
        return user


class AWSCognito:
    def __init__(self):
        self.client = boto3.client("cognito-idp", region_name=AWS_REGION)

    def decode_token(self, token: str):
        jwks = self.get_jwks()
        unverified_header = jwt.get_unverified_header(token)
        rsa_key = {}

        for key in jwks["keys"]:
            if key["kid"] == unverified_header["kid"]:
                rsa_key = {
                    "kty": key["kty"],
                    "kid": key["kid"],
                    "use": key["use"],
                    "n": key["n"],
                    "e": key["e"],
                }

        if not rsa_key:
            raise Exception("Unable to find appropriate key")

        try:
            payload = jwt.decode(
                token,
                rsa_key,
                algorithms=["RS256"],
                audience=AWS_COGNITO_APP_CLIENT_ID,
                options={"verify_aud": True},
            )

            return payload
        except JWTError:
            raise JWTError


async def get_current_user_cognito(cognito: CognitoDep, token: TokenDep):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )

    try:
        payload = cognito.decode_token(token)
        username = payload.get("username")
        if username is None:
            raise credentials_exception
    except InvalidTokenError:
        raise credentials_exception

    user = get_user(username)
    if user is None:
        raise credentials_exception

    return user


CurrentUser = Annotated[User, Depends(get_current_user_cognito)]

async def get_current_active_user(current_user: CurrentUser):
    if current_user.disabled:
        raise HTTPException(status_code=400, detail="Inactive user")

    return current_user


CurrentActiveUser = Annotated[User, Depends(get_current_active_user)]

The OAuth dependency TokenDep is passed to the get_current_user_cognito function as a dependency. The CurrentUser constant is defined as a dependency of get_current_user_cognito using typing annotations, which declares it returns a type of User which is defined as a database model. This is returned via the get_user function. Whenever we use CurrentActiveUser in a route path, it will call TokenDep and if authorized, passes the Token model to get_current_user_cognito. We perform the following checks on the token:

Verifying the JWT as shown in the guide AWS Cognito Verifying JWT
Checks that the username in the token belongs to an actual API user

The example below shows the above dependency being used in a route that returns information about the current user:

@router.get("/users/me", response_model=UserPublic, tags=["Authentication"])
async def read_users_me(current_user: CurrentActiveUser):
    return current_user

Below is a screenshot of the same route in Swagger UI:

The code can be reviewed at the following Github Repository

Follow up

There are still other subjects which have not been explored in this post:

How to cache Cognito tokens locally to avoid calling API
How to keep database user in sync with the tokens
How to define scopes to further refine API access for each user