---
name: storage-mongodb
description: "MongoDB-specific code design reference for the Code Design Agent. Load only when the architecture or repository indicates MongoDB. Covers document modeling, collection boundaries, indexing, repository design, and consistency tradeoffs."
---

This skill provides MongoDB-specific guidance for code-level design.

**Announce at start:** "I'm using the storage-mongodb skill to apply MongoDB-specific code design conventions."

## When To Load

Load this skill only when one or more of the following is true:
- The architecture explicitly names MongoDB
- The repository uses MongoDB drivers, collection names, or BSON models
- The architecture favors document-oriented aggregates and embedded data

Do not load this skill for relational-first designs.

## Purpose

Translate document-oriented architecture into MongoDB-aware code design: collection boundaries, document shapes, indexing, repository contracts, and BSON mapping conventions.

## MongoDB Design Rules

1. Model around access patterns, not normalized relational forms
2. Embed data when it is read together and bounded in size; reference when lifecycle or cardinality differs
3. Make collection-level indexes explicit in the code design doc
4. Use multi-document transactions only when the architecture truly requires cross-document atomicity
5. Keep document versioning and migration strategy explicit when schemas evolve

## Collection Guidance

- Define one repository owner per collection or aggregate root
- Document shard keys or partitioning assumptions if scale requires them
- Call out whether a collection is append-heavy, read-heavy, or mutation-heavy

## Model Guidance

- Separate domain models from persistence models when BSON layout differs from business shape
- Document `_id`, BSON tags, embedded documents, and optional fields clearly
- Make arrays, nested objects, and denormalized snapshots explicit

## Query Guidance

- Design repository methods around concrete queries from the architecture
- Call out aggregation pipelines, secondary indexes, and sort patterns explicitly
- Document pagination style and consistency expectations

## Operational Safeguards

- Note write concern and read concern expectations when relevant
- Note TTL indexes, retention strategy, and document growth risks
- Surface risks of unbounded arrays and large document rewrites

## Output Constraint

This skill is reference-only. It does not create files by itself. Apply its guidance inside `docs/code-design/{date}-{feature}.md` only.