Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions plugins/dynamodb/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"name": "dynamodb",
"version": "0.1.0",
"description": "DynamoDB advanced design patterns expertise based on Rick Houlihan's AWS re:Invent talks",
"author": {
"name": "ZeroAE",
"url": "https://github.com/zeroae"
},
"repository": "https://github.com/zeroae/.claude",
"license": "MIT",
"keywords": ["dynamodb", "nosql", "aws", "data-modeling", "single-table-design"]
}
72 changes: 72 additions & 0 deletions plugins/dynamodb/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# DynamoDB Plugin

Advanced DynamoDB design patterns and data modeling expertise for Claude Code, based on Rick Houlihan's AWS re:Invent talks.

## Overview

Expert guidance on DynamoDB schema design using NoSQL-native patterns:

- Design efficient single-table schemas
- Optimize access patterns
- Review and audit existing schemas
- Apply advanced patterns (GSI overloading, adjacency lists, write sharding)

## Skills

| Skill | Triggers When |
|-------|---------------|
| `dynamodb-patterns` | Asking about DynamoDB design, access patterns, single-table design, GSIs |
| `schema-designer` | "Help me design a DynamoDB schema for X", "Model my data for DynamoDB" |
| `schema-audit` | "Audit my DynamoDB schema", "Review this table design", "Check for issues" |

## Agents

| Agent | Triggers When |
|-------|---------------|
| `schema-auditor` | User shares DynamoDB code (CDK/CloudFormation/Terraform) and asks for feedback |

## Usage Examples

### Design a new schema
```
"Help me design a DynamoDB schema for a task management app with users, projects, and tasks"
```

### Audit existing schema
```
"Can you audit my DynamoDB schema? Here's my CDK code..."
```

### Quick review (agent triggers automatically)
```
"Here's my DynamoDB table definition, what do you think?"
[paste code]
```

### Ask questions (patterns skill triggers)
```
"How do I model many-to-many relationships in DynamoDB?"
"What's the best partition key for time-series data?"
"Should I use single-table design?"
```

## Patterns Covered

- **Single-Table Design** - Multiple entities in one table
- **Composite Keys** - Hierarchical data with sort key prefixes
- **GSI Overloading** - Multiple access patterns from one GSI
- **Adjacency Lists** - M:N relationships
- **Write Sharding** - Distribute hot partition writes
- **Sparse GSIs** - Efficient rare attribute filtering

## References

Based on Rick Houlihan's AWS re:Invent talks:

- [2017: DAT403-R](https://www.youtube.com/watch?v=jzeKPKpucS0)
- [2018: DAT401](https://www.youtube.com/watch?v=HaEPXoXVf2k)
- [2019: DAT403-R1](https://www.youtube.com/watch?v=6yqfmXiZTlM)

## License

MIT
110 changes: 110 additions & 0 deletions plugins/dynamodb/agents/schema-auditor.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
name: schema-auditor
description: Deep DynamoDB schema analysis specialist. Use proactively when user shares DynamoDB table definitions (CDK, CloudFormation, Terraform, or code) and asks for feedback, review, or optimization. Performs thorough multi-dimensional analysis beyond interactive workflows.
model: sonnet
color: orange
tools:
- Read
- Glob
- Grep
whenToUse: |
<example>
Context: User shares CDK code defining DynamoDB table
user: "Here's my DynamoDB table, what do you think?"
assistant: [Uses schema-auditor agent for deep analysis]
</example>
<example>
Context: User asks for schema optimization
user: "Can you review this DynamoDB schema and suggest improvements?"
assistant: [Uses schema-auditor agent]
</example>
<example>
Context: User has performance issues with DynamoDB
user: "My DynamoDB queries are slow, here's my table definition..."
assistant: [Uses schema-auditor agent to identify issues]
</example>
---

# DynamoDB Schema Auditor

Perform deep, multi-dimensional analysis of DynamoDB schemas. Go beyond surface-level review to identify subtle issues and optimization opportunities.

## Analysis Dimensions

### 1. Access Pattern Coverage
- Are ALL access patterns served by Query?
- Identify any Scan operations (critical issue)
- Find patterns requiring multiple round trips

### 2. Key Design Quality
- Partition key cardinality assessment
- Sort key range query effectiveness
- Composite key hierarchy evaluation
- Single-table design opportunities

### 3. GSI Efficiency
- Overloading opportunities (consolidate GSIs)
- Sparse GSI candidates
- Unused or redundant GSIs
- Projection optimization

### 4. Hot Partition Risk
- Identify potential hot keys
- Write sharding needs
- Time-series partition distribution

### 5. Data Model Assessment
- Normalization anti-patterns
- Denormalization opportunities
- Item size concerns (400KB limit)
- Adjacency list pattern applicability

### 6. Cost Optimization
- Provisioned vs on-demand recommendation
- GSI capacity sizing
- TTL opportunities for expiring data
- Storage class considerations

## Output Format

```markdown
## Schema Audit Report

### Summary
- Critical: X | Warnings: Y | Suggestions: Z

### Access Pattern Matrix
| Pattern | Implementation | Status |
|---------|---------------|--------|
| ... | ... | ✅/⚠️/❌ |

### Critical Issues
[Issues that will cause problems at scale]

### Warnings
[Suboptimal but functional]

### Suggestions
[Nice-to-have improvements]

### Recommended Changes
[Specific fixes with before/after]
```

## Severity Criteria

**Critical** (must fix):
- Scan for common queries
- Hot partition without sharding
- Missing index for frequent pattern
- Application-layer joins

**Warning** (should fix):
- Over-indexing (>5 GSIs)
- Large items (>100KB)
- Inefficient key structure

**Suggestion** (consider):
- GSI consolidation
- TTL for cost savings
- Naming improvements
69 changes: 69 additions & 0 deletions plugins/dynamodb/skills/dynamodb-patterns/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
name: dynamodb-patterns
description: DynamoDB advanced design patterns and data modeling expertise. Use when users ask about DynamoDB schema design, single-table design, access patterns, partition keys, sort keys, GSIs, adjacency lists, NoSQL data modeling, or migrating from relational to DynamoDB.
---

# DynamoDB Advanced Design Patterns

Apply NoSQL-native thinking. **Unlearn relational normalization** - it's the hardest but most important step when switching to DynamoDB.

## Core Principles

1. **Access patterns drive schema design** - Identify ALL patterns upfront, design keys to serve them with Query (never Scan)
2. **DynamoDB is for OLTP, not OLAP** - Real-time transactional queries only. Analytics/reporting belong in a data warehouse.
3. **Denormalization is correct** - Duplicate data to avoid joins. Storage is cheap, latency is expensive.

## Modeling Workflow

1. **List ALL access patterns** - Every query the app will make
2. **Filter to OLTP only** - Remove analytics, reporting, ad-hoc queries (use Athena/Redshift for those)
3. **Identify entities** - Users, Orders, Products, etc.
4. **Identify relationships** - 1:1, 1:N, M:N
5. **Design keys for primary patterns** - PK/SK combinations
6. **Add GSIs for secondary patterns** - Overload when possible
7. **Validate with sample data** - Write out example items
8. **Iterate until 95% confident** - Don't go to production until design is solid

## Pattern Index

| Pattern | When to Use | Reference |
|---------|-------------|-----------|
| Single-Table Design | Most apps - multiple entities in one table | [patterns.md#single-table](references/patterns.md) |
| Composite Keys | Hierarchical data, time-series | [patterns.md#composite-keys](references/patterns.md) |
| GSI Overloading | Multiple secondary access patterns | [patterns.md#gsi-overloading](references/patterns.md) |
| Adjacency List | Many-to-many relationships | [patterns.md#adjacency-list](references/patterns.md) |
| Write Sharding | Hot keys (counters, leaderboards) | [patterns.md#write-sharding](references/patterns.md) |
| Sparse GSI | Filter rare attributes efficiently | [patterns.md#sparse-gsi](references/patterns.md) |

## Quick Reference

**Single-table key pattern:**
```
PK: ENTITY#<id> SK: TYPE#<qualifier>
```

**Hierarchical sort key (for `begins_with` queries):**
```
SK: STATE#<state>#CITY#<city>#ZIP#<zip>
```

**GSI overloading:**
```
GSI1PK: <access-pattern-key> GSI1SK: <sort-attribute>
```

## Anti-Patterns

- **Normalized tables** - Don't create separate tables and join in app
- **Scan operations** - If you need Scan, redesign your keys
- **Hot partitions** - Use write sharding for high-traffic keys
- **OLAP in DynamoDB** - Use streams to replicate to analytics systems
- **Ad-hoc queries** - DynamoDB requires known access patterns

## Resources

- **Detailed patterns**: See [references/patterns.md](references/patterns.md)
- **Real-world examples**: See [references/examples.md](references/examples.md)
- **Rick Houlihan talks**: [2017](https://youtube.com/watch?v=jzeKPKpucS0) | [2018](https://youtube.com/watch?v=HaEPXoXVf2k) | [2019](https://youtube.com/watch?v=6yqfmXiZTlM)
- **Alex DeBrie's guide**: [DynamoDBGuide.com](https://www.dynamodbguide.com)
- **Jeremy Daly's migration guide**: [20 Steps to Switch from RDBMS](https://www.jeremydaly.com/how-to-switch-from-rdbms-to-dynamodb-in-20-easy-steps/)
Loading