# automattic/mongoose architecture

> Architecture diagram of the GitHub repository automattic/mongoose, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/automattic/mongoose
- Repository: https://github.com/automattic/mongoose

## Overview

Mongoose is a MongoDB object-modeling library. The documented workflow is to define a schema, create a model, construct or query documents, and persist or retrieve them through a connection. Its runtime also covers casting, validation, population, aggregation, and change streams. The map includes these major capabilities; several are represented by their implementation paths because their source was not sampled. Edges are limited to README statements and relationships visible in the supplied source excerpts or index.

Main entry points: [`lib/model.js`](https://github.com/automattic/mongoose/blob/master/lib/model.js) (Models), [`lib/query.js`](https://github.com/automattic/mongoose/blob/master/lib/query.js) (Queries), [`lib/index.js`](https://github.com/automattic/mongoose/blob/master/lib/index.js) (Mongoose API), [`lib/schema.js`](https://github.com/automattic/mongoose/blob/master/lib/schema.js) (Schema Definition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Modeling"]
  node_api["Mongoose API<br/>[index.js]"]
  node_schema["Schema Definition<br/>[schema.js]"]
  node_schema_types["Schema Types<br/>[array.js]"]
  node_model["Models<br/>[model.js]"]
  node_document["Documents<br/>[document.js]"]
  node_validation["Validation<br/>[validation.js]"]
end

subgraph group_operations["Data Operations"]
  node_query["Queries<br/>[query.js]"]
  node_populate["Population"]
  node_aggregate["Aggregation<br/>[aggregate.js]"]
  node_query_cursor["Query Cursors<br/>[queryCursor.js]"]
  node_change_stream["Change Streams<br/>[changeStream.js]"]
end

subgraph group_persistence["Persistence"]
  node_connection["Connections<br/>[connection.js]"]
  node_native_driver["MongoDB Driver<br/>[connection.js]"]
end

subgraph group_runtime["Runtime Support"]
  node_casting["Value Casting<br/>[cast.js]"]
  node_array_methods["Array Tracking<br/>[index.js]"]
  node_errors["Error Types<br/>[index.js]"]
end

node_user(("Application Developer"))
node_mongodb[("MongoDB")]

node_user -->|"uses"| node_api
node_api -->|"defines"| node_schema
node_api -->|"creates"| node_model
node_schema -.->|"configures"| node_schema_types
node_schema -->|"shapes"| node_model
node_model -->|"creates"| node_document
node_document -->|"validates"| node_validation
node_model -->|"queries"| node_query
node_query -->|"casts with"| node_casting
node_query -->|"creates"| node_query_cursor
node_query_cursor -.->|"prepares"| node_populate
node_query_cursor -->|"uses helpers"| node_query
node_model -.->|"uses"| node_connection
node_connection -->|"delegates to"| node_native_driver
node_native_driver -.->|"accesses"| node_mongodb
node_document -->|"tracks changes"| node_array_methods
node_query -->|"raises"| node_errors
node_aggregate -.->|"runs pipelines"| node_mongodb
node_change_stream -.->|"watches changes"| node_mongodb

click node_api "https://github.com/automattic/mongoose/blob/master/lib/index.js"
click node_schema "https://github.com/automattic/mongoose/blob/master/lib/schema.js"
click node_schema_types "https://github.com/automattic/mongoose/blob/master/lib/schema/array.js"
click node_model "https://github.com/automattic/mongoose/blob/master/lib/model.js"
click node_document "https://github.com/automattic/mongoose/blob/master/lib/document.js"
click node_validation "https://github.com/automattic/mongoose/blob/master/lib/error/validation.js"
click node_query "https://github.com/automattic/mongoose/blob/master/lib/query.js"
click node_populate "https://github.com/automattic/mongoose/blob/master/lib/helpers/populate/createPopulateQueryFilter.js"
click node_aggregate "https://github.com/automattic/mongoose/blob/master/lib/aggregate.js"
click node_query_cursor "https://github.com/automattic/mongoose/blob/master/lib/cursor/queryCursor.js"
click node_change_stream "https://github.com/automattic/mongoose/blob/master/lib/cursor/changeStream.js"
click node_connection "https://github.com/automattic/mongoose/blob/master/lib/connection.js"
click node_native_driver "https://github.com/automattic/mongoose/blob/master/lib/drivers/node-mongodb-native/connection.js"
click node_casting "https://github.com/automattic/mongoose/blob/master/lib/cast.js"
click node_array_methods "https://github.com/automattic/mongoose/blob/master/lib/types/array/methods/index.js"
click node_errors "https://github.com/automattic/mongoose/blob/master/lib/error/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_schema,node_schema_types,node_model,node_document,node_validation toneBlue
class node_query,node_populate,node_aggregate,node_query_cursor,node_change_stream,node_mongodb toneAmber
class node_connection,node_native_driver toneMint
class node_casting,node_array_methods,node_errors toneRose
class node_user toneIndigo
```

## Components

### Modeling

- [Mongoose API](https://github.com/automattic/mongoose/blob/master/lib/index.js): `lib/index.js`
- [Schema Definition](https://github.com/automattic/mongoose/blob/master/lib/schema.js): `lib/schema.js`
- [Schema Types](https://github.com/automattic/mongoose/blob/master/lib/schema/array.js): `lib/schema/array.js`
- [Models](https://github.com/automattic/mongoose/blob/master/lib/model.js): `lib/model.js`
- [Documents](https://github.com/automattic/mongoose/blob/master/lib/document.js): `lib/document.js`
- [Validation](https://github.com/automattic/mongoose/blob/master/lib/error/validation.js): `lib/error/validation.js`

### Data Operations

- [Queries](https://github.com/automattic/mongoose/blob/master/lib/query.js): `lib/query.js`
- [Population](https://github.com/automattic/mongoose/blob/master/lib/helpers/populate/createPopulateQueryFilter.js): `lib/helpers/populate/createPopulateQueryFilter.js`
- [Aggregation](https://github.com/automattic/mongoose/blob/master/lib/aggregate.js): `lib/aggregate.js`
- [Query Cursors](https://github.com/automattic/mongoose/blob/master/lib/cursor/queryCursor.js): `lib/cursor/queryCursor.js`
- [Change Streams](https://github.com/automattic/mongoose/blob/master/lib/cursor/changeStream.js): `lib/cursor/changeStream.js`

### Persistence

- [Connections](https://github.com/automattic/mongoose/blob/master/lib/connection.js): `lib/connection.js`
- [MongoDB Driver](https://github.com/automattic/mongoose/blob/master/lib/drivers/node-mongodb-native/connection.js): `lib/drivers/node-mongodb-native/connection.js`

### Runtime Support

- [Value Casting](https://github.com/automattic/mongoose/blob/master/lib/cast.js): `lib/cast.js`
- [Array Tracking](https://github.com/automattic/mongoose/blob/master/lib/types/array/methods/index.js): `lib/types/array/methods/index.js`
- [Error Types](https://github.com/automattic/mongoose/blob/master/lib/error/index.js): `lib/error/index.js`

### Other components

- **Application Developer**
- **MongoDB**

## Connections

- Application Developer → Mongoose API: uses (evidence: `README.md`)
- Mongoose API → Schema Definition: defines (evidence: `README.md`)
- Mongoose API → Models: creates (evidence: `README.md`)
- Schema Definition → Schema Types: configures
- Schema Definition → Models: shapes (evidence: `README.md`)
- Models → Documents: creates (evidence: `README.md`)
- Documents → Validation: validates (evidence: `lib/document.js`)
- Models → Queries: queries (evidence: `README.md`)
- Queries → Value Casting: casts with (evidence: `lib/query.js`)
- Queries → Query Cursors: creates (evidence: `lib/query.js`)
- Query Cursors → Population: prepares
- Query Cursors → Queries: uses helpers (evidence: `lib/cursor/queryCursor.js`)
- Models → Connections: uses
- Connections → MongoDB Driver: delegates to (evidence: `lib/drivers/node-mongodb-native/connection.js`)
- MongoDB Driver → MongoDB: accesses
- Documents → Array Tracking: tracks changes (evidence: `lib/types/array/methods/index.js`)
- Queries → Error Types: raises (evidence: `lib/query.js`)
- Aggregation → MongoDB: runs pipelines
- Change Streams → MongoDB: watches changes
