Using UIGraph with AWS DynamoDB: auto-generate your NoSQL schema diagrams

AWS DynamoDB is one of the most widely used databases in production systems and one of the least documented. Not because engineers don't want to document it — but because the tooling for visualizing DynamoDB schemas is, frankly, terrible.

With relational databases, you have years of mature ER diagram tooling. With DynamoDB, you have... a JSON document describing your table, and the vague memory of what the access patterns were when you designed it.

UIGraph's DynamoDB import changes this. You point it at your DynamoDB table definitions, and it generates an interactive schema diagram inside your service Map — automatically kept in sync with your actual table structure via the CLI. Here's how to use it.

The DynamoDB documentation problem

DynamoDB's schema design is fundamentally different from relational databases. There's no schema enforcement at the database level. The structure is defined by the access patterns you design for, not by the tables and foreign keys that a traditional schema diagram shows.

This means two things for documentation:

• You need to document both the table structure (partition key, sort key, GSIs, LSIs) AND the access patterns that the application uses. One without the other is only half the story.

• In single-table design — which is the DynamoDB best practice — multiple entity types live in a single table. A naive schema diagram that just shows "Table: getorbis-prod" tells you nothing useful.

UIGraph's DynamoDB support handles both: it renders the table structure and attributes in an interactive diagram, and you can annotate it with Map Points that explain the access patterns and link to the service code that queries the table.

Setting up the DynamoDB import

UIGraph reads DynamoDB table definitions from a JSON file. The format matches the AWS DynamoDB DescribeTable API response structure, which means you can generate it directly from the AWS CLI:

# Export your table definition from AWS
aws dynamodb describe-table \
  --table-name getorbis-prod \
  --query "Table" \
  --output json > dynamo-schema.json

Alternatively, write the definition file manually for new tables before they're deployed. This is actually the better practice — defining the table structure as a documentation artifact before creating the table forces you to think through access patterns upfront.

The schema definition format

Here's a full DynamoDB table definition for the getorbis.io platform — a single-table design that stores users, subscriptions, and events:

{
  "TableName": "getorbis-prod",
  "KeySchema": [
    { "AttributeName": "PK", "KeyType": "HASH" },
    { "AttributeName": "SK", "KeyType": "RANGE" }

],

  "AttributeDefinitions": [
    { "AttributeName": "PK", "AttributeType": "S" },
    { "AttributeName": "SK", "AttributeType": "S" },
    { "AttributeName": "GSI1PK", "AttributeType": "S" },
    { "AttributeName": "GSI1SK", "AttributeType": "S" },
    { "AttributeName": "GSI2PK", "AttributeType": "S" }

],

  "GlobalSecondaryIndexes": [
    {
      "IndexName": "GSI1",
      "KeySchema": [
        { "AttributeName": "GSI1PK", "KeyType": "HASH" },
        { "AttributeName": "GSI1SK", "KeyType": "RANGE" }

],

      "Projection": { "ProjectionType": "ALL" }
    },
    {
      "IndexName": "GSI2",
      "KeySchema": [
        { "AttributeName": "GSI2PK", "KeyType": "HASH" }

],

      "Projection": { "ProjectionType": "KEYS_ONLY" }
    }

],

  "BillingMode": "PAY_PER_REQUEST",
  "Tags": [
    { "Key": "Environment", "Value": "production" },
    { "Key": "Team", "Value": "platform" }

]

}

Configuring .uigraph.yaml for DynamoDB

databases:
  - name: getorbis-prod DynamoDB
    dbType: DynamoDB
    schemaPath: ./dynamo-schema.json

Run uigraph sync and UIGraph parses the table definition and renders an interactive diagram showing the partition key, sort key, GSIs, and attribute definitions.

Documenting single-table design properly

Single-table design is where DynamoDB diagrams get interesting. A single table like getorbis-prod might contain UserProfile items (PK: USER#<userId>, SK: PROFILE), Subscription items (PK: USER#<userId>, SK: SUB#<subId>), and Event items (PK: USER#<userId>, SK: EVENT#<timestamp>).

The table diagram shows the key structure. The entity patterns live on top of it. In UIGraph, you can add a Frame with an entity-access-pattern table (a screenshot or a manually created diagram showing which entity types use which key patterns) and link it to the DynamoDB diagram via a Map Point.

The result is two connected layers of documentation: the raw table structure (from the JSON import, always in sync) and the entity design layer (a frame you maintain that shows the key patterns).

Keeping the diagram in sync with production

The CI pattern for DynamoDB is slightly different from SQL. Your table definition doesn't live in a schema.sql file — it lives either in your Infrastructure as Code (Terraform, CloudFormation, CDK) or as an exported AWS CLI definition.

The recommended approach: add a CI step that exports the table definition from AWS before running uigraph sync:

name: UIGraph Sync
on:
  push:
    branches: [main]
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Export DynamoDB schema
        run: |
          aws dynamodb describe-table \
            --table-name getorbis-prod \
            --query "Table" \
            --output json > dynamo-schema.json
        env:
          AWS_DEFAULT_REGION: us-east-1
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      - name: Install UIGraph CLI
        run: npm install -g @uigraph/cli
      - name: Sync to UIGraph
        run: uigraph sync
        env:
          UIGRAPH_TOKEN: ${{ secrets.UIGRAPH_TOKEN }}

If you're using CDK or Terraform, export the table definition from your IaC code instead of querying AWS directly — this way the diagram stays in sync with your infrastructure definition rather than production state, which is more useful during development.

Multiple DynamoDB tables

For teams with multiple DynamoDB tables, list them all in the databases config:

databases:
  - name: getorbis-prod (main table)
    dbType: DynamoDB
    schemaPath: ./schemas/dynamo-main.json
  - name: getorbis-sessions
    dbType: DynamoDB
    schemaPath: ./schemas/dynamo-sessions.json
  - name: getorbis-audit-log
    dbType: DynamoDB
    schemaPath: ./schemas/dynamo-audit.json

Each generates its own interactive diagram. You can cross-link them via Map Points in UIGraph — so the main table diagram has a Point that links to the sessions table diagram, representing the relationship between user sessions and the main user record.