Skip to content


Code Genie projects include an infinitely scalable Serverless Database using AWS DynamoDB. A Table is created for each Entity defined in your App Definition, along with code to make querying and updating data easy for the REST API, Cognito Triggers, and other services.

Project Structure

  • Directorypackages
    • Directoryapi
      • Directorycontrollers
        • user.ts
        • widget.ts
      • Directorymodels
        • User.ts
        • Widget.ts
      • utils dynamodb.ts
    • Directorycdk # see the Cloud Infrastructure guide for more details
      • Directorylib
        • Directoryconstructs
          • Directorytables
            • WidgetTable.ts one table per entity
            • UserTable.ts
          • BaseTable.ts

Entity Models and Controllers

DynamoDB Toolbox Models and Controllers are created for each Entity defined in your App Definition.

The following information from the Entity is used to construct the DynamoDB Toolbox Table and Entity:

  • – An environment variable named WIDGET_TABLE must be set to the name of the DynamoDB Table (autogenerated by CDK).
  • Table.partitionKey and Table.sortKey – Defined in x-codeGenie.dynamodb.partitionKey and x-codeGenie.dynamodb.sortKey.
  • Table.indexes – Defined in x-codeGenie.dynamodb.globalSecondaryIndexes.
  • ‐ The Entity name.
  • Entity.attributes – Entity properties and their types (converted to a DynamoDB equivalent).

The controller includes CRUD methods that are primarily used by the REST API, as well as some Cognito Triggers. The methods include:

  • list* – Returns a list of records
  • get* – Returns a single record
  • create* – Creates a record with a unique ID.
  • update* – Updates a record (if it exists) and returns the record with the new data.
  • delete* – Deletes a record (if it exists).

User Controller

The User Controller includes the additional following methods:


Helper methods


This dynamodb client is used by the Models described above.

When no AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY environment variables exist, it’s assumed we’re trying to run in local development mode and attempts to use the _dev profile defined in ~/.aws/credentials.

dynamoCreateItem({ entity, attributes })

DynamoDB doesn’t have a create method, and you must rely on the put method which doesn’t care if the item already exists and will overwrite any existing value. DynamoDB Toolbox also doesn’t provide a create convenience method. To ensure we don’t accidentally overwrite an existing item, this method uses the put method with a condition that the item doesn’t already exist (causing DynamoDB to throw an error if it does).

scanAll({ entity, scanOptions, maxPages = Infinity, maxItems = Infinity, filter })

Performs an exhaustive scan of a DynamoDB table. Can be limited by a defined maximum number of pages (maxPages) or until a maximum number of items (maxItems) have been found that match the filter (optional).

This method is especially helpful