# mongodb/mongo-efcore-provider architecture

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

- Interactive diagram: https://gitdiagram.com/mongodb/mongo-efcore-provider
- Repository: https://github.com/mongodb/mongo-efcore-provider

## Overview

##### Project Type & Overall Purpose
- This is a provider/library project for EF Core. It extends Entity Framework Core (currently version 8 on .NET 8+) to support MongoDB.

##### Main Components to Highlight
a. Client Application
- User’s application that creates a DbContext (e.g., PlanetDbContext in the README).
- How a developer calls the provider’s extension method (UseMongoDB) and later invokes operations like EnsureCreated, SaveChanges, and queries.

b. Provider’s Core Modules (Located in the src directory):
- Design & Infrastructure:
- The Design folder (with services like MongoDesignTimeServices) shows how the provider hooks into the EF Core design-time infrastructure.
- Infrastructure folder includes classes like MongoModelValidator, MongoOptionsExtension, and MongoDbContextOptionsBuilder which help configure EF Core behavior for MongoDB.
- Query Processing & Translation:
- In the Query folder, you have classes that handle translating LINQ expressions into MongoDB queries (e.g., in Expressions, Factories, and Visitors subfolders).
- Expression visitors (e.g., MongoEFToLinqTranslatingExpressionVisitor, MongoQueryableMethodTranslatingExpressionVisitor) indicate that LINQ queries are rewritten into a form that MongoDB can process.
- Diagnostics & Logging:
- The Diagnostics folder includes components for logging query events, bulk write operations, and transaction activities. This helps in debugging and performance tracking.
- Change Tracking & Value Generation:
- The ChangeTracking and ValueGeneration segments manage how EF Core tracks changes to entities and assigns keys (including ObjectIds or Guids) before persisting documents to MongoDB.
- Serialization & Value Conversion:
- Under the Serializers and Storage/ValueConversion directories, the provider defines how to map CLR types to BSON elements and handle custom conversions.
- Extensions:
- The Extensions folder provides extension methods that likely integrate the provider with EF Core’s fluent API. Methods like UseMongoDB() are implemented here.

c. Storage and Connectivity:
- The Storage folder includes components such as the MongoClientWrapper, MongoDatabaseCreator, and MongoTransactionManager that encapsulate direct interactions with the MongoDB C# Driver.
- This layer translates EF Core’s operations into MongoDB CRUD commands over an established MongoDB connection (using a MongoClient, database, and transaction capabilities).

d. Testing & Continuous Integration Components:
- The tests folder portrays both functional tests and unit tests for the provider. These guarantee that mappings, query translations, and transactions work as expected.
- The evergreen folder and other configuration files (e.g., global.json, nuget.config, sbom.json) represent build, deployment, and CI/CD configurations.

##### Relationships and Interactions
- Query path: from the application issuing a LINQ query, flowing into the Query Processing modules, where expression visitors and factories translate it into a MongoDB-specific query, and finally into the Storage Layer which uses the MongoDB driver.
- A two-way interaction between Logging/Diagnostics components and the core modules, indicating monitoring and event emission.
- Integration point between EF Core’s model, the provider’s metadata conventions (like those in Metadata/Conventions), and MongoDB’s BSON representations.

##### Architectural Patterns and Design Principles
- The provider employs the Extension Method pattern (for fluent API integration to configure DbContext) and a layered/micro-modular structure with clearly separated concerns (e.g., query translation, diagnostics, storage).
- Design patterns such as Dependency Injection (for the design time services and options extensions) and possibly the Adapter pattern (wrapping standard MongoDB API calls in classes such as MongoClientWrapper).

##### Final Touches
- That every major directory (src, evergreen, tests, apidocs) is represented in either the functional blocks or supporting/infrastructure elements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Side"
        CA["DbContext & Entities (PlanetDbContext, Planet)"]:::client
    end

    %% Provider Core Modules
    subgraph "EF Core Provider Core Modules"
        %% Configuration Layer
        subgraph "Configuration Layer"
            ext["Extensions (UseMongoDB, etc.)"]:::ext
            ds["Design Services"]:::design
            ins["Infrastructure Services"]:::design
        end
        %% Query & Data Processing Layer
        subgraph "Query & Data Processing"
            qp["Query Processing & Translation"]:::query
            ct["Change Tracking"]:::changetracking
            vg["Value Generation"]:::changetracking
            ser["Serialization"]:::ser
            conv["Value Conversion"]:::ser
        end
        diag["Diagnostics & Logging"]:::diag
    end

    %% Storage & Connectivity Layer
    subgraph "Storage & Connectivity"
        storage["MongoDB Driver Adapter (ClientWrapper, DatabaseCreator, TransactionManager)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        mdb["MongoDB Database Server"]:::external
    end

    %% Testing & CI
    subgraph "Testing & CI"
        tst["Testing (Functional & Unit Tests)"]:::testing
        cicd["CI/CD (Evergreen)"]:::testing
    end

    %% Connections
    CA -->|"calls"| ext
    ext -->|"configures"| ds
    ext -->|"configures"| ins
    ext -->|"triggers"| qp
    ds -->|"validates"| ct
    ds -->|"generates"| vg
    ds -->|"maps"| ser
    ds -->|"converts"| conv
    qp -->|"translates"| storage
    diag --- ds
    diag --- ins
    diag --- qp
    diag --- storage
    storage -->|"executesCRUD"| mdb
    tst -->|"tests"| ext
    tst -->|"tests"| qp
    tst -->|"tests"| storage

    %% Click Events
    click CA "https://github.com/mongodb/mongo-efcore-provider/tree/main/tests/MongoDB.EntityFrameworkCore.FunctionalTests/Entities/Guides"
    click ds "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Design"
    click ins "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Infrastructure"
    click qp "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Query"
    click diag "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Diagnostics"
    click ct "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/ChangeTracking"
    click vg "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/ValueGeneration"
    click ser "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Serializers"
    click conv "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Storage/ValueConversion"
    click ext "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Extensions"
    click storage "https://github.com/mongodb/mongo-efcore-provider/tree/main/src/MongoDB.EntityFrameworkCore/Storage"
    click tst "https://github.com/mongodb/mongo-efcore-provider/tree/main/tests"
    click cicd "https://github.com/mongodb/mongo-efcore-provider/tree/main/evergreen"

    %% Styles
    classDef client fill:#AEC6CF,stroke:#000,stroke-width:1px;
    classDef design fill:#FDFD96,stroke:#000,stroke-width:1px;
    classDef query fill:#77DD77,stroke:#000,stroke-width:1px;
    classDef diag fill:#FF6961,stroke:#000,stroke-width:1px;
    classDef changetracking fill:#FFD1DC,stroke:#000,stroke-width:1px;
    classDef ser fill:#CBA0F7,stroke:#000,stroke-width:1px;
    classDef ext fill:#FFB347,stroke:#000,stroke-width:1px;
    classDef storage fill:#F49AC2,stroke:#000,stroke-width:1px;
    classDef testing fill:#CB99C9,stroke:#000,stroke-width:1px;
    classDef external fill:#CFCFC4,stroke:#000,stroke-width:1px;
```
