gs-dynamodb-onetable_skill

Overview

This skill is a practical guide for implementing DynamoDB single-table design using the OneTable ORM together with the Repository pattern. It explains how to map domain entities to a single-table schema, implement repository classes in the Infrastructure layer, and keep business rules inside domain entities. The guide focuses on predictable key patterns, schema evolution, observability, and Clean Architecture rules.

How this skill works

The guide defines a OneTable schema with primary and GSI indexes and shows mapping rules for pk/sk and GSI keys (user partition, entity sort, hierarchical and time-based patterns). It provides a Domain entity that owns persistence conversion (toPersistence/fromPersistence) and a Repository implementation that uses the OneTable Model to upsert, get, find, batchWrite, and remove items. Repositories throw errors, log timings, and translate persistence records into domain entities.

When to use it

• Implementing Repository classes in the Infrastructure layer for Clean Architecture
• Designing a DynamoDB single-table schema with OneTable ORM
• Mapping domain entities to persistence (toPersistence/fromPersistence)
• Querying by partition, GSI, hierarchical or time-based patterns
• Implementing paginated list endpoints with cursor-based pagination

Best practices

• Keep business rules in Entities or Use Cases; repositories only handle persistence
• Use ULID for IDs to ensure time-sortable keys
• Entity owns persistence format and handles defaulting/missing fields in fromPersistence
• Throw exceptions from repositories; let application layer handle errors
• Log operation timing and context for observability (start, duration, success/failure)

Example use cases

• Save a Category entity via repository.save(entity) which upserts the single-table record
• Find a user’s categories using pk = USER#${userId} and sk begins with the entity prefix
• Fetch an entity by id using a GSI where gsi1pk = FEATURE#${id}
• Implement soft-delete by creating an archived entity in the domain and saving it
• Batch import many domain entities with Model.batchWrite using entities’ toPersistence()