@intentsolutionsio/nosql-data-modeler 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "nosql-data-modeler",
+  "version": "1.0.0",
+  "description": "Database plugin for nosql-data-modeler",
+  "author": {
+    "name": "Claude Code Plugins",
+    "email": "[email protected]"
+  },
+  "repository": "https://github.com/jeremylongshore/claude-code-plugins",
+  "license": "MIT",
+  "keywords": [
+    "database",
+    "backend",
+    "data",
+    "agent-skills"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Jeremy Longshore & Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Nosql Data Modeler Plugin
+
+Database plugin for nosql-data-modeler
+
+## Installation
+
+```bash
+/plugin install nosql-data-modeler@claude-code-plugins-plus
+```
+
+## Usage
+
+```bash
+/nosql-data-modeler
+```
+
+## Features
+
+- Database best practices
+- Multi-database support
+- Production-ready implementations
+- Comprehensive documentation
+
+## Requirements
+
+- Database access
+- Appropriate permissions
+
+## Files
+
+- `commands/nosql-data-modeler.md` or `agents/nosql-data-modeler-agent.md` - Main plugin logic
+
+## License
+
+MIT

package/agents/nosql-agent.md

@@ -0,0 +1,36 @@
+---
+name: nosql-agent
+description: Design NoSQL data models
+---
+# NoSQL Data Modeler
+
+Design efficient NoSQL data models for document and key-value databases.
+
+## NoSQL Modeling Principles
+
+1. **Embed vs Reference**: Denormalization for performance
+2. **Access Patterns**: Design for queries, not normalization
+3. **Sharding Keys**: Distribute data evenly
+4. **Indexes**: Support query patterns
+
+## MongoDB Example
+
+```javascript
+// User document with embedded posts (1-to-few)
+{
+  _id: ObjectId("..."),
+  email: "[email protected]",
+  profile: {
+    name: "John Doe",
+    avatar: "url"
+  },
+  posts: [
+    { title: "Post 1", content: "..." },
+    { title: "Post 2", content: "..." }
+  ]
+}
+```
+
+## When to Activate
+
+Design NoSQL schemas for MongoDB, DynamoDB, Cassandra, etc.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@intentsolutionsio/nosql-data-modeler",
+  "version": "1.0.0",
+  "description": "Database plugin for nosql-data-modeler",
+  "keywords": [
+    "database",
+    "backend",
+    "data",
+    "agent-skills",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/database/nosql-data-modeler"
+  },
+  "homepage": "https://tonsofskills.com/plugins/nosql-data-modeler",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Claude Code Plugins",
+    "email": "[email protected]"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install nosql-data-modeler\\\\n  or /plugin install nosql-data-modeler@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}

package/skills/modeling-nosql-data/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: modeling-nosql-data
+description: |
+  Build use when you need to work with NoSQL data modeling.
+  This skill provides NoSQL database design with comprehensive guidance and automation.
+  Trigger with phrases like "model NoSQL data", "design document structure",
+  or "optimize NoSQL schema".
+
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(psql:*), Bash(mysql:*), Bash(mongosh:*)
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [database, modeling-nosql]
+---
+# NoSQL Data Modeler
+
+## Overview
+
+Design data models for NoSQL databases including MongoDB (document), DynamoDB (key-value/wide-column), Redis (key-value), and Cassandra (wide-column). Unlike relational modeling where normalization drives design, NoSQL modeling starts from access patterns and query requirements, then shapes the data to serve those patterns efficiently.
+
+## Prerequisites
+
+- `mongosh`, `aws dynamodb` CLI, `redis-cli`, or `cqlsh` installed depending on target database
+- Documented list of application access patterns (read/write queries the application performs)
+- Expected data volumes (document count, average document size, growth rate)
+- Read/write ratio and latency requirements for each access pattern
+- Understanding of consistency requirements (strong vs. eventual consistency)
+
+## Instructions
+
+1. Catalog all application access patterns as a table with columns: pattern name, query description, frequency (queries/sec), latency requirement, and data fields accessed. This drives every modeling decision.
+
+2. For MongoDB document modeling, apply the embedding vs. referencing decision framework:
+   - **Embed** when: data is always accessed together, child data has no independent lifecycle, cardinality is bounded (1:few), and updates are infrequent.
+   - **Reference** when: data has independent access patterns, cardinality is unbounded (1:many/many:many), child documents are large, or data is shared across parents.
+
+3. Design document schemas that match query patterns. If the application needs "all orders for a customer with line items," embed line items inside the order document. If the application needs "all products across all orders," use references to a products collection.
+
+4. For DynamoDB, design the partition key and sort key to support the primary access pattern with a single-table design. Use composite sort keys (e.g., `ORDER#2024-01-15#12345`) for hierarchical data. Plan GSIs (Global Secondary Indexes) for secondary access patterns, keeping total GSI count under 5.
+
+5. Evaluate denormalization trade-offs: duplicating data across documents reduces read latency but increases write complexity and storage. Denormalize data that changes rarely (user names, product categories) but reference data that changes frequently (prices, inventory counts).
+
+6. Handle one-to-many relationships by choosing between embedding (small arrays), child referencing (parent stores child IDs), or parent referencing (child stores parent ID). For unbounded one-to-many, always use parent referencing to avoid document size limits (16MB in MongoDB).
+
+7. Model many-to-many relationships using an array of references in each document or a dedicated junction collection. For DynamoDB, use adjacency list patterns with inverted GSIs.
+
+8. Plan for schema evolution by using schema versioning fields (`schemaVersion: 2`), writing migration scripts that update documents in batches, and ensuring application code handles both old and new document shapes during rollout.
+
+9. Validate the model against access patterns by running sample queries with `explain()` in MongoDB or examining consumed capacity units in DynamoDB. Verify that primary access patterns require only single-partition reads.
+
+10. Document the final data model with sample documents, index definitions, and the access pattern mapping that justifies each modeling decision.
+
+## Output
+
+- **Data model diagrams** showing document/collection structure, embedded vs. referenced relationships
+- **Sample documents** in JSON format for each collection/table with realistic data
+- **Index definitions** including compound indexes, partial indexes, and TTL indexes
+- **Access pattern mapping** table linking each query to its supporting collection and index
+- **Migration scripts** for evolving schemas from existing relational models to NoSQL
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|---------|
+| Document exceeds 16MB size limit (MongoDB) | Unbounded array growth from embedding too many child documents | Switch from embedding to referencing; use the bucket pattern to chunk large arrays into fixed-size sub-documents |
+| Hot partition in DynamoDB | Partition key with low cardinality causes uneven distribution | Add a random suffix or use a composite key; distribute writes across partitions with write sharding |
+| High read latency on referenced documents | Too many round trips to resolve references (N+1 query problem) | Denormalize frequently accessed reference data; use `$lookup` aggregation for server-side joins; batch reference resolution |
+| Inconsistent denormalized data | Write to source succeeds but denormalized copies not updated | Implement change streams (MongoDB) or DynamoDB Streams to propagate updates; use transactional writes where supported |
+| Query requires full collection scan | Missing index on query filter fields | Create compound indexes matching query predicates and sort order; use `explain()` to verify index usage |
+
+## Examples
+
+**E-commerce product catalog in MongoDB**: Products embed variant arrays (size, color, price) since variants are always accessed with the product. Reviews reference the product by ID since reviews are accessed independently and grow unboundedly. A compound index on `{category: 1, price: 1}` supports filtered browsing.
+
+**Social media feed in DynamoDB single-table design**: Partition key is `USER#userId`, sort key is `POST#timestamp` for user timeline queries. A GSI with partition key `HASHTAG#tag` and sort key `timestamp` supports hashtag feeds. User profile data uses sort key `PROFILE` on the same partition.
+
+**IoT sensor data in Cassandra**: Partition key is `sensor_id`, clustering column is `timestamp DESC`. Each partition holds one sensor's readings, ordered by time. TTL of 90 days automatically expires old readings. Materialized views support queries by location and sensor type.
+
+## Resources
+
+- MongoDB data modeling patterns: https://www.mongodb.com/docs/manual/data-modeling/
+- DynamoDB single-table design: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-modeling-nosql.html
+- Cassandra data modeling guide: https://cassandra.apache.org/doc/latest/cassandra/data_modeling/
+- Redis data structures: https://redis.io/docs/data-types/
+- NoSQL design patterns catalog: https://www.mongodb.com/docs/manual/applications/data-models/

package/skills/modeling-nosql-data/assets/README.md

@@ -0,0 +1,7 @@
+# Assets
+
+Bundled resources for nosql-data-modeler skill
+
+- [ ] schema_templates/: Templates for common NoSQL schemas (e.g., user profile, product catalog).
+- [ ] sample_data/: Sample data files corresponding to the schema templates.
+- [ ] diagrams/: Visual diagrams illustrating different NoSQL data modeling patterns.

package/skills/modeling-nosql-data/references/README.md

@@ -0,0 +1,4 @@
+# References
+
+Bundled resources for nosql-data-modeler skill
+

package/skills/modeling-nosql-data/scripts/README.md

@@ -0,0 +1,7 @@
+# Scripts
+
+Bundled resources for nosql-data-modeler skill
+
+- [x] validate_schema.py: Validates a NoSQL schema against best practices and common errors.
+- [x] generate_sample_data.py: Generates sample data based on the defined schema for testing purposes.
+- [x] migrate_schema.py: Migrates a schema from one NoSQL database type to another (e.g., MongoDB to DynamoDB).

package/skills/modeling-nosql-data/scripts/generate_sample_data.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""
+Generates sample data based on defined schema for testing purposes.
+
+This script creates realistic sample data documents based on a NoSQL schema,
+useful for testing queries, indexes, and application logic.
+"""
+
+import argparse
+import json
+import random
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, List, Any, Union
+from uuid import uuid4
+
+
+class SampleDataGenerator:
+    """Generates sample data based on schema."""
+
+    def __init__(self, schema: Dict[str, Any]):
+        """
+        Initialize generator.
+
+        Args:
+            schema: Schema definition dictionary
+        """
+        self.schema = schema
+        self.generated_data = []
+
+    @staticmethod
+    def generate_value(field_def: Dict[str, Any]) -> Any:
+        """
+        Generate a sample value for a field.
+
+        Args:
+            field_def: Field definition with type and constraints
+
+        Returns:
+            Generated value
+        """
+        field_type = field_def.get("type", "string")
+
+        if field_type == "string":
+            if "enum" in field_def:
+                return random.choice(field_def["enum"])
+            elif "format" in field_def:
+                format_type = field_def["format"]
+                if format_type == "email":
+                    return f"user{random.randint(1, 1000)}@example.com"
+                elif format_type == "uuid":
+                    return str(uuid4())
+                elif format_type == "url":
+                    return f"https://example.com/{random.randint(1, 100)}"
+            else:
+                return f"Sample {field_def.get('description', 'value')}"
+
+        elif field_type == "number":
+            min_val = field_def.get("minimum", 0)
+            max_val = field_def.get("maximum", 1000)
+            return random.uniform(min_val, max_val)
+
+        elif field_type == "integer":
+            min_val = field_def.get("minimum", 0)
+            max_val = field_def.get("maximum", 100)
+            return random.randint(min_val, max_val)
+
+        elif field_type == "boolean":
+            return random.choice([True, False])
+
+        elif field_type == "date":
+            days_ago = random.randint(0, 365)
+            return (datetime.now() - timedelta(days=days_ago)).isoformat()
+
+        elif field_type == "array":
+            min_items = field_def.get("minItems", 1)
+            max_items = field_def.get("maxItems", 5)
+            count = random.randint(min_items, max_items)
+
+            if "items" in field_def:
+                return [
+                    SampleDataGenerator.generate_value(field_def["items"])
+                    for _ in range(count)
+                ]
+            else:
+                return [f"item{i}" for i in range(count)]
+
+        elif field_type == "object":
+            obj = {}
+            if "properties" in field_def:
+                for prop_name, prop_def in field_def["properties"].items():
+                    obj[prop_name] = SampleDataGenerator.generate_value(prop_def)
+            return obj
+
+        else:
+            return None
+
+    def generate_document(self) -> Dict[str, Any]:
+        """
+        Generate a complete sample document.
+
+        Returns:
+            Sample document dictionary
+        """
+        document = {}
+
+        # Handle top-level properties
+        if "properties" in self.schema:
+            for field_name, field_def in self.schema["properties"].items():
+                required = field_name in self.schema.get("required", [])
+
+                if required or random.random() > 0.3:  # 70% chance for optional fields
+                    document[field_name] = self.generate_value(field_def)
+
+        # Handle root-level type definitions
+        for field_name, field_def in self.schema.items():
+            if field_name.startswith("$") or field_name in ["type", "properties", "required"]:
+                continue
+
+            if isinstance(field_def, dict) and "type" in field_def:
+                document[field_name] = self.generate_value(field_def)
+
+        return document
+
+    def generate_documents(self, count: int) -> List[Dict[str, Any]]:
+        """
+        Generate multiple sample documents.
+
+        Args:
+            count: Number of documents to generate
+
+        Returns:
+            List of sample documents
+        """
+        self.generated_data = [self.generate_document() for _ in range(count)]
+        return self.generated_data
+
+    def export_json(self, filepath: str) -> bool:
+        """
+        Export generated data as JSON.
+
+        Args:
+            filepath: Path to export to
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            with open(filepath, 'w') as f:
+                json.dump(self.generated_data, f, indent=2)
+            return True
+        except Exception as e:
+            print(f"Error exporting JSON: {e}", file=sys.stderr)
+            return False
+
+    def export_jsonl(self, filepath: str) -> bool:
+        """
+        Export generated data as JSONL (JSON Lines).
+
+        Args:
+            filepath: Path to export to
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            with open(filepath, 'w') as f:
+                for doc in self.generated_data:
+                    f.write(json.dumps(doc) + '\n')
+            return True
+        except Exception as e:
+            print(f"Error exporting JSONL: {e}", file=sys.stderr)
+            return False
+
+    def export_csv(self, filepath: str) -> bool:
+        """
+        Export flattened sample data as CSV.
+
+        Args:
+            filepath: Path to export to
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            import csv
+
+            if not self.generated_data:
+                return False
+
+            # Flatten documents and collect all keys
+            flattened = []
+            all_keys = set()
+
+            for doc in self.generated_data:
+                flat = self._flatten_dict(doc)
+                flattened.append(flat)
+                all_keys.update(flat.keys())
+
+            all_keys = sorted(list(all_keys))
+
+            with open(filepath, 'w', newline='') as f:
+                writer = csv.DictWriter(f, fieldnames=all_keys)
+                writer.writeheader()
+                writer.writerows(flattened)
+
+            return True
+        except Exception as e:
+            print(f"Error exporting CSV: {e}", file=sys.stderr)
+            return False
+
+    def _flatten_dict(self, d: Dict, parent_key: str = '', sep: str = '.') -> Dict:
+        """
+        Flatten nested dictionary.
+
+        Args:
+            d: Dictionary to flatten
+            parent_key: Parent key for nesting
+            sep: Separator for nested keys
+
+        Returns:
+            Flattened dictionary
+        """
+        items = []
+
+        for k, v in d.items():
+            new_key = f"{parent_key}{sep}{k}" if parent_key else k
+
+            if isinstance(v, dict):
+                items.extend(self._flatten_dict(v, new_key, sep=sep).items())
+            elif isinstance(v, list):
+                items.append((new_key, json.dumps(v)))
+            else:
+                items.append((new_key, v))
+
+        return dict(items)
+
+
+def load_schema(filepath: str) -> Dict[str, Any]:
+    """
+    Load schema from JSON file.
+
+    Args:
+        filepath: Path to schema file
+
+    Returns:
+        Schema dictionary
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        json.JSONDecodeError: If file is not valid JSON
+    """
+    try:
+        with open(filepath, 'r') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print(f"Error: Schema file not found: {filepath}", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON in schema: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    """Main entry point for sample data generation."""
+    parser = argparse.ArgumentParser(
+        description="Generate sample data based on NoSQL schema",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Generate 10 documents as JSON
+  %(prog)s --schema user-schema.json --count 10
+
+  # Generate 100 documents as JSONL
+  %(prog)s --schema order-schema.json --count 100 --format jsonl
+
+  # Export as CSV for spreadsheet analysis
+  %(prog)s --schema product-schema.json --count 50 --format csv --output products.csv
+
+  # Print to stdout
+  %(prog)s --schema schema.json --count 5 --print
+        """
+    )
+
+    parser.add_argument(
+        "--schema",
+        required=True,
+        help="Path to JSON schema file"
+    )
+    parser.add_argument(
+        "--count",
+        type=int,
+        default=10,
+        help="Number of sample documents to generate (default: 10)"
+    )
+    parser.add_argument(
+        "--format",
+        default="json",
+        choices=["json", "jsonl", "csv"],
+        help="Output format"
+    )
+    parser.add_argument(
+        "--output",
+        help="Output file path"
+    )
+    parser.add_argument(
+        "--print",
+        action="store_true",
+        help="Print generated data to stdout"
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        help="Random seed for reproducible data"
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print detailed output"
+    )
+
+    args = parser.parse_args()
+
+    # Set random seed if provided
+    if args.seed:
+        random.seed(args.seed)
+
+    try:
+        # Load schema
+        if args.verbose:
+            print(f"Loading schema from {args.schema}...", file=sys.stderr)
+
+        schema = load_schema(args.schema)
+
+        # Generate data
+        if args.verbose:
+            print(f"Generating {args.count} sample documents...", file=sys.stderr)
+
+        generator = SampleDataGenerator(schema)
+        generator.generate_documents(args.count)
+
+        # Print to stdout if requested
+        if args.print:
+            if args.format == "jsonl":
+                for doc in generator.generated_data:
+                    print(json.dumps(doc))
+            else:
+                print(json.dumps(generator.generated_data, indent=2))
+
+        # Export to file
+        if args.output:
+            if args.verbose:
+                print(f"Exporting to {args.output}...", file=sys.stderr)
+
+            if args.format == "csv":
+                success = generator.export_csv(args.output)
+            elif args.format == "jsonl":
+                success = generator.export_jsonl(args.output)
+            else:  # json
+                success = generator.export_json(args.output)
+
+            if success:
+                if args.verbose:
+                    print(f"✓ Generated {args.count} documents", file=sys.stderr)
+                    print(f"✓ Saved to {args.output}", file=sys.stderr)
+                sys.exit(0)
+            else:
+                sys.exit(1)
+        elif not args.print:
+            # If no output file and not printing, export to default location
+            default_file = f"sample_data.{args.format}"
+            if args.format == "csv":
+                generator.export_csv(default_file)
+            elif args.format == "jsonl":
+                generator.export_jsonl(default_file)
+            else:
+                generator.export_json(default_file)
+
+            if args.verbose:
+                print(f"✓ Data saved to {default_file}", file=sys.stderr)
+
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()