# beanieodm/beanie architecture

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

- Interactive diagram: https://gitdiagram.com/beanieodm/beanie
- Repository: https://github.com/beanieodm/beanie

## Overview

Beanie is an asynchronous Python ODM for MongoDB using Pydantic models. Users initialize model classes against a database, then insert, find, update, and delete collection documents; the same API supports aggregation, links, views, union documents, bulk writes, lifecycle actions, and migrations. The graph separates model setup, query operations, persistence features, and model/field support. Relationships among unsampled modules are omitted unless the README or SOURCE INDEX supports them.

Main entry points: [`beanie/odm/documents.py`](https://github.com/beanieodm/beanie/blob/main/beanie/odm/documents.py) (Documents), [`beanie/odm/utils/init.py`](https://github.com/beanieodm/beanie/blob/main/beanie/odm/utils/init.py) (Initialize models), [`beanie/odm/queries/find.py`](https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/find.py) (Find queries), [`beanie/odm/queries/update.py`](https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/update.py) (Update queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Model setup"]
  node_init["Initialize models<br/>[init.py]"]
  node_settings["Model settings"]
end

subgraph group_queries["Query operations"]
  node_findapi["Find interface<br/>[find.py]"]
  node_findquery["Find queries<br/>[find.py]"]
  node_updatequery["Update queries<br/>[update.py]"]
  node_aggregation["Aggregation queries<br/>[aggregation.py]"]
  node_deletequery["Delete queries<br/>[delete.py]"]
  node_operators["Query operators"]
end

subgraph group_persistence["Persistence features"]
  node_actions["Lifecycle actions<br/>[actions.py]"]
  node_bulk["Bulk writes<br/>[bulk.py]"]
  node_cache["Query cache<br/>[cache.py]"]
  node_migration["Data migrations<br/>[migrate.py]"]
end

subgraph group_modeling["Model support"]
  node_document["Documents<br/>[documents.py]"]
  node_fields["Fields and links<br/>[fields.py]"]
  node_views["Database views<br/>[views.py]"]
  node_union["Union documents<br/>[union_doc.py]"]
  node_parse["Document parsing<br/>[parsing.py]"]
  node_encode["BSON encoding<br/>[encoder.py]"]
end

node_user(("Application developer"))
node_database[("MongoDB")]

node_user -->|"initializes"| node_init
node_init -->|"inspects database"| node_database
node_init -->|"initializes classes"| node_document
node_init -->|"initializes views"| node_views
node_init -->|"initializes unions"| node_union
node_init -->|"configures models"| node_settings
node_user -->|"creates documents"| node_document
node_document -->|"inserts and deletes"| node_database
node_document -->|"runs actions"| node_actions
node_document -->|"accepts bulk writer"| node_bulk
node_document -->|"implements queries"| node_findapi
node_findapi -->|"creates find queries"| node_findquery
node_findquery -->|"reads documents"| node_database
node_findquery -->|"reads and writes cache"| node_cache
node_findquery -->|"creates aggregation"| node_aggregation
node_findquery -->|"creates delete query"| node_deletequery
node_user -->|"requests updates"| node_updatequery
node_updatequery -->|"updates documents"| node_database
node_updatequery -->|"queues operations"| node_bulk
node_updatequery -->|"builds expressions"| node_operators
node_fields -->|"fetches linked documents"| node_document
node_findquery -.->|"parses results"| node_parse
node_updatequery -->|"encodes updates"| node_encode
node_bulk -->|"commits batch"| node_database
node_views -.->|"uses aggregation"| node_aggregation
node_union -->|"provides find interface"| node_findapi
node_user -->|"runs migrations"| node_migration

click node_init "https://github.com/beanieodm/beanie/blob/main/beanie/odm/utils/init.py"
click node_settings "https://github.com/beanieodm/beanie/tree/main/beanie/odm/settings"
click node_document "https://github.com/beanieodm/beanie/blob/main/beanie/odm/documents.py"
click node_fields "https://github.com/beanieodm/beanie/blob/main/beanie/odm/fields.py"
click node_views "https://github.com/beanieodm/beanie/blob/main/beanie/odm/views.py"
click node_union "https://github.com/beanieodm/beanie/blob/main/beanie/odm/union_doc.py"
click node_findapi "https://github.com/beanieodm/beanie/blob/main/beanie/odm/interfaces/find.py"
click node_findquery "https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/find.py"
click node_updatequery "https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/update.py"
click node_aggregation "https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/aggregation.py"
click node_deletequery "https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/delete.py"
click node_operators "https://github.com/beanieodm/beanie/tree/main/beanie/odm/operators"
click node_actions "https://github.com/beanieodm/beanie/blob/main/beanie/odm/actions.py"
click node_bulk "https://github.com/beanieodm/beanie/blob/main/beanie/odm/bulk.py"
click node_cache "https://github.com/beanieodm/beanie/blob/main/beanie/odm/cache.py"
click node_migration "https://github.com/beanieodm/beanie/blob/main/beanie/executors/migrate.py"
click node_parse "https://github.com/beanieodm/beanie/blob/main/beanie/odm/utils/parsing.py"
click node_encode "https://github.com/beanieodm/beanie/blob/main/beanie/odm/utils/encoder.py"

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_init,node_settings toneBlue
class node_findapi,node_findquery,node_updatequery,node_aggregation,node_deletequery,node_operators,node_database toneAmber
class node_actions,node_bulk,node_cache,node_migration toneMint
class node_document,node_fields,node_views,node_union,node_parse,node_encode toneRose
class node_user toneIndigo
```

## Components

### Model setup

- [Initialize models](https://github.com/beanieodm/beanie/blob/main/beanie/odm/utils/init.py): `beanie/odm/utils/init.py`
- [Model settings](https://github.com/beanieodm/beanie/tree/main/beanie/odm/settings): `beanie/odm/settings`

### Query operations

- [Find interface](https://github.com/beanieodm/beanie/blob/main/beanie/odm/interfaces/find.py): `beanie/odm/interfaces/find.py`
- [Find queries](https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/find.py): `beanie/odm/queries/find.py`
- [Update queries](https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/update.py): `beanie/odm/queries/update.py`
- [Aggregation queries](https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/aggregation.py): `beanie/odm/queries/aggregation.py`
- [Delete queries](https://github.com/beanieodm/beanie/blob/main/beanie/odm/queries/delete.py): `beanie/odm/queries/delete.py`
- [Query operators](https://github.com/beanieodm/beanie/tree/main/beanie/odm/operators): `beanie/odm/operators`

### Persistence features

- [Lifecycle actions](https://github.com/beanieodm/beanie/blob/main/beanie/odm/actions.py): `beanie/odm/actions.py`
- [Bulk writes](https://github.com/beanieodm/beanie/blob/main/beanie/odm/bulk.py): `beanie/odm/bulk.py`
- [Query cache](https://github.com/beanieodm/beanie/blob/main/beanie/odm/cache.py): `beanie/odm/cache.py`
- [Data migrations](https://github.com/beanieodm/beanie/blob/main/beanie/executors/migrate.py): `beanie/executors/migrate.py`

### Model support

- [Documents](https://github.com/beanieodm/beanie/blob/main/beanie/odm/documents.py): `beanie/odm/documents.py`
- [Fields and links](https://github.com/beanieodm/beanie/blob/main/beanie/odm/fields.py): `beanie/odm/fields.py`
- [Database views](https://github.com/beanieodm/beanie/blob/main/beanie/odm/views.py): `beanie/odm/views.py`
- [Union documents](https://github.com/beanieodm/beanie/blob/main/beanie/odm/union_doc.py): `beanie/odm/union_doc.py`
- [Document parsing](https://github.com/beanieodm/beanie/blob/main/beanie/odm/utils/parsing.py): `beanie/odm/utils/parsing.py`
- [BSON encoding](https://github.com/beanieodm/beanie/blob/main/beanie/odm/utils/encoder.py): `beanie/odm/utils/encoder.py`

### Other components

- **Application developer**
- **MongoDB**

## Connections

- Application developer → Initialize models: initializes
- Initialize models → MongoDB: inspects database (evidence: `beanie/odm/utils/init.py`)
- Initialize models → Documents: initializes classes (evidence: `beanie/odm/utils/init.py`)
- Initialize models → Database views: initializes views (evidence: `beanie/odm/utils/init.py`)
- Initialize models → Union documents: initializes unions (evidence: `beanie/odm/utils/init.py`)
- Initialize models → Model settings: configures models (evidence: `beanie/odm/utils/init.py`)
- Application developer → Documents: creates documents
- Documents → MongoDB: inserts and deletes
- Documents → Lifecycle actions: runs actions (evidence: `beanie/odm/documents.py`)
- Documents → Bulk writes: accepts bulk writer (evidence: `beanie/odm/documents.py`)
- Documents → Find interface: implements queries (evidence: `beanie/odm/documents.py`)
- Find interface → Find queries: creates find queries (evidence: `beanie/odm/interfaces/find.py`)
- Find queries → MongoDB: reads documents
- Find queries → Query cache: reads and writes cache (evidence: `beanie/odm/queries/find.py`)
- Find queries → Aggregation queries: creates aggregation (evidence: `beanie/odm/queries/find.py`)
- Find queries → Delete queries: creates delete query (evidence: `beanie/odm/queries/find.py`)
- Application developer → Update queries: requests updates
- Update queries → MongoDB: updates documents (evidence: `beanie/odm/queries/update.py`)
- Update queries → Bulk writes: queues operations (evidence: `beanie/odm/queries/update.py`)
- Update queries → Query operators: builds expressions (evidence: `beanie/odm/queries/update.py`)
- Fields and links → Documents: fetches linked documents (evidence: `beanie/odm/fields.py`)
- Find queries → Document parsing: parses results (evidence: `beanie/odm/queries/find.py`)
- Update queries → BSON encoding: encodes updates (evidence: `beanie/odm/queries/update.py`)
- Bulk writes → MongoDB: commits batch (evidence: `beanie/odm/bulk.py`)
- Database views → Aggregation queries: uses aggregation
- Union documents → Find interface: provides find interface (evidence: `beanie/odm/union_doc.py`)
- Application developer → Data migrations: runs migrations
