# mongodb/mongo-csharp-driver architecture

> Architecture diagram of the GitHub repository mongodb/mongo-csharp-driver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mongodb/mongo-csharp-driver
- Repository: https://github.com/mongodb/mongo-csharp-driver

## Overview

The repository is the official MongoDB .NET/C# driver. Its documented user workflow creates a client, selects a database and collection, writes typed or untyped documents, then queries and materializes results. The map also preserves the BSON model/serialization layer, aggregation and LINQ translation, and optional AWS authentication and client-side encryption. Several driver internals are unsampled, so those subsystems are represented at their existing source directories; only documented or excerpt-supported relationships are drawn.

Main entry points: [`src/MongoDB.Driver/IMongoCollection.cs`](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/IMongoCollection.cs) (Collection API), [`src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstPipeline.cs`](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstPipeline.cs) (Pipeline AST), [`src/MongoDB.Driver`](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver) (MongoClient), [`src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators`](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators) (Expression Translators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_driver["Driver API"]
  node_client["MongoClient<br/>[MongoDB.Driver]"]
  node_database["Database API<br/>[MongoDB.Driver]"]
  node_collection["Collection API"]
end

subgraph group_bson["BSON Data"]
  node_bsonmodel["BSON Values<br/>[BsonValue.cs]"]
  node_bsondocument["BSON Documents<br/>[BsonDocument.cs]"]
  node_bsonarray["BSON Arrays<br/>[BsonArray.cs]"]
  node_serializer["Serializer Facade<br/>[BsonSerializer.cs]"]
  node_deserialization["Deserialization Context"]
  node_serializerimpl["Serializer Implementations<br/>[Serializers]"]
  node_binaryio["BSON Binary I/O<br/>[IO]"]
end

subgraph group_query["Query Construction"]
  node_filters["Filter Definitions"]
  node_pipelineapi["Pipeline API"]
  node_stagebuilder["Stage Builder"]
  node_linq["LINQ Provider"]
  node_translator["Expression Translators"]
  node_astpipeline["Pipeline AST<br/>[AstPipeline.cs]"]
  node_aststages["AST Stages<br/>[AstStage.cs]"]
  node_optimizer["Pipeline Optimizer"]
end

subgraph group_integrations["Optional Integrations"]
  node_aws["AWS Authentication"]
  node_encryption["Client Encryption"]
  node_cryptcontroller["Crypt Controller"]
end

node_developer(("Application"))
node_mongo[("MongoDB Server")]

node_developer -->|"creates"| node_client
node_client -->|"selects"| node_database
node_database -->|"selects"| node_collection
node_collection -->|"writes documents"| node_mongo
node_collection -->|"queries documents"| node_mongo
node_developer -->|"supplies typed data"| node_collection
node_serializer -->|"configures context"| node_deserialization
node_serializerimpl -->|"deserializes through"| node_deserialization
node_astpipeline -->|"holds stages"| node_aststages
node_astpipeline -->|"renders as"| node_bsonarray
node_stagebuilder -->|"builds stages for"| node_pipelineapi
node_linq -.->|"translates expressions"| node_translator
node_translator -.->|"constructs pipeline"| node_astpipeline
node_optimizer -->|"optimizes pipeline"| node_astpipeline
node_aws -.->|"extends authentication"| node_client
node_encryption -->|"uses controller"| node_cryptcontroller

click node_client "https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver"
click node_database "https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver"
click node_collection "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/IMongoCollection.cs"
click node_bsonmodel "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/ObjectModel/BsonValue.cs"
click node_bsondocument "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/ObjectModel/BsonDocument.cs"
click node_bsonarray "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/ObjectModel/BsonArray.cs"
click node_serializer "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/Serialization/BsonSerializer.cs"
click node_deserialization "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/Serialization/BsonDeserializationContext.cs"
click node_serializerimpl "https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Bson/Serialization/Serializers"
click node_binaryio "https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Bson/IO"
click node_filters "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/FilterDefinition.cs"
click node_pipelineapi "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/PipelineDefinition.cs"
click node_stagebuilder "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs"
click node_linq "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/MongoQueryProvider.cs"
click node_translator "https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators"
click node_astpipeline "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstPipeline.cs"
click node_aststages "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Stages/AstStage.cs"
click node_optimizer "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Optimizers/AstGroupingPipelineOptimizer.cs"
click node_aws "https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver.Authentication.AWS"
click node_encryption "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver.Encryption/ClientEncryption.cs"
click node_cryptcontroller "https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver.Encryption/LibMongoCryptControllerBase.cs"

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_client,node_database,node_collection toneBlue
class node_bsonmodel,node_bsondocument,node_bsonarray,node_serializer,node_deserialization,node_serializerimpl,node_binaryio,node_mongo toneAmber
class node_filters,node_pipelineapi,node_stagebuilder,node_linq,node_translator,node_astpipeline,node_aststages,node_optimizer toneMint
class node_aws,node_encryption,node_cryptcontroller toneRose
class node_developer toneIndigo
```

## Components

### Driver API

- [MongoClient](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver): `src/MongoDB.Driver`
- [Database API](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver): `src/MongoDB.Driver`
- [Collection API](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/IMongoCollection.cs): `src/MongoDB.Driver/IMongoCollection.cs`

### BSON Data

- [BSON Values](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/ObjectModel/BsonValue.cs): `src/MongoDB.Bson/ObjectModel/BsonValue.cs`
- [BSON Documents](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/ObjectModel/BsonDocument.cs): `src/MongoDB.Bson/ObjectModel/BsonDocument.cs`
- [BSON Arrays](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/ObjectModel/BsonArray.cs): `src/MongoDB.Bson/ObjectModel/BsonArray.cs`
- [Serializer Facade](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/Serialization/BsonSerializer.cs): `src/MongoDB.Bson/Serialization/BsonSerializer.cs`
- [Deserialization Context](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Bson/Serialization/BsonDeserializationContext.cs): `src/MongoDB.Bson/Serialization/BsonDeserializationContext.cs`
- [Serializer Implementations](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Bson/Serialization/Serializers): `src/MongoDB.Bson/Serialization/Serializers`
- [BSON Binary I/O](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Bson/IO): `src/MongoDB.Bson/IO`

### Query Construction

- [Filter Definitions](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/FilterDefinition.cs): `src/MongoDB.Driver/FilterDefinition.cs`
- [Pipeline API](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/PipelineDefinition.cs): `src/MongoDB.Driver/PipelineDefinition.cs`
- [Stage Builder](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs): `src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs`
- [LINQ Provider](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/MongoQueryProvider.cs): `src/MongoDB.Driver/Linq/Linq3Implementation/MongoQueryProvider.cs`
- [Expression Translators](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators): `src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators`
- [Pipeline AST](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstPipeline.cs): `src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstPipeline.cs`
- [AST Stages](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Stages/AstStage.cs): `src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Stages/AstStage.cs`
- [Pipeline Optimizer](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Optimizers/AstGroupingPipelineOptimizer.cs): `src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Optimizers/AstGroupingPipelineOptimizer.cs`

### Optional Integrations

- [AWS Authentication](https://github.com/mongodb/mongo-csharp-driver/tree/main/src/MongoDB.Driver.Authentication.AWS): `src/MongoDB.Driver.Authentication.AWS`
- [Client Encryption](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver.Encryption/ClientEncryption.cs): `src/MongoDB.Driver.Encryption/ClientEncryption.cs`
- [Crypt Controller](https://github.com/mongodb/mongo-csharp-driver/blob/main/src/MongoDB.Driver.Encryption/LibMongoCryptControllerBase.cs): `src/MongoDB.Driver.Encryption/LibMongoCryptControllerBase.cs`

### Other components

- **Application**
- **MongoDB Server**

## Connections

- Application → MongoClient: creates
- MongoClient → Database API: selects
- Database API → Collection API: selects (evidence: `src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs`)
- Collection API → MongoDB Server: writes documents
- Collection API → MongoDB Server: queries documents
- Application → Collection API: supplies typed data
- Serializer Facade → Deserialization Context: configures context (evidence: `src/MongoDB.Bson/Serialization/BsonSerializer.cs`)
- Serializer Implementations → Deserialization Context: deserializes through
- Pipeline AST → AST Stages: holds stages (evidence: `src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstPipeline.cs`)
- Pipeline AST → BSON Arrays: renders as (evidence: `src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstPipeline.cs`)
- Stage Builder → Pipeline API: builds stages for (evidence: `src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs`)
- LINQ Provider → Expression Translators: translates expressions (evidence: `src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators/LookupMethodToPipelineTranslator.cs`)
- Expression Translators → Pipeline AST: constructs pipeline (evidence: `src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators/LookupMethodToPipelineTranslator.cs`)
- Pipeline Optimizer → Pipeline AST: optimizes pipeline (evidence: `src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Optimizers/AstGroupingPipelineOptimizer.cs`)
- AWS Authentication → MongoClient: extends authentication (evidence: `src/MongoDB.Driver.Authentication.AWS/ExtensionManagerExtensions.cs`)
- Client Encryption → Crypt Controller: uses controller (evidence: `src/MongoDB.Driver.Encryption/LibMongoCryptControllerBase.cs`)
