This article is based on a public repository I created. You can check the full project and follow here: MongoIntegrationAPI

Ever since I started using C# and writing my first lines of code, I was trained to apply the Clean Architecture pattern. Following DDD principles, I focused on the Domain layer, keeping it separated from Infrastructure and completely unaware that entities could represent a database table.

When I got my first MongoDB project, I had several problems. The MongoDB driver expects some specific methods to search and insert data, instances are built differently, and all of this made my first experience a traumatic one.

It turns out that stepping outside my comfort zone gives me motivation and energy to study and understand things. I started building Proofs of Concept (POCs), trying the connection between C# .NET and MongoDB in different scenarios. Working on these projects, I started to feel something was wrong again, I missed the Generic Repository Pattern and all the ease of dependency injection.

I also noticed another point about MongoDB: because it is a document-oriented database, it structures its “tables” differently. We can make a simple analogy where Tables are Collections and Rows are Documents. A document looks a lot like JSON, but it’s not. Actually, it’s BSON, a binary version.

The difference is that BSON is designed for storage efficiency. It stores metadata such as length and type, because of that it can be parsed and analyzed much more quickly by machines than JSON text. BSON supports basic types such as strings, bools, and numbers, and also some extra types such as dates, binaries, and exclusive identifiers like ObjectIds.

Book:

{
  "_id": { "$oid": "69bc53b77b02eb421c958688" },
  "title": "Dune"
}

In software, we deal with data that is frequently accessed together. In situations like this, we can create an Embedded Document. Embedding is basically placing one document, or an array of documents, inside a field of another parent document.

There are a lot of embedded data patterns such as the Subset Pattern, Extended Reference Pattern, and Computed Pattern. All of them fit different scenarios.

The same book, “Dune”, but now as an Embedded Document:

{
  "_id": { "$oid": "69bc53b77b02eb421c958688" },
  "title": "Dune",
  "publisherId": { "$oid": "69bc53957b02eb421c958687" },
  "authors": [
    {
      "name": "Frank Herbert",
      "bibliography": "[...]"
    }
  ],
  "categories": [
    {
      "name": "SciFi",
      "description": "Science fiction exploring the future and technology."
    },
    {
      "name": "Adventure",
      "description": "Stories focused on journeys, challenges, and discoveries."
    }
  ]
}

In C#, our classes require specific annotations which, although functional, introduce coupling with the Infrastructure layer. This reduces portability and violates the separation of concerns proposed by Clean Architecture.

Let’s talk more about how we learn to build systems by checking the TreeView of the project.

3 folders, no separation between domain and storage

C:\...\MongoIntegrationAPI\
├───Controllers\            <-- Depend directly on the concrete repository classes
├───Models\                 <-- Entities decorated with [BsonId], [BsonRepresentation], [BsonElement]
├───Repositories\           <-- Use IMongoCollection<> directly — the MongoDB driver leaks in here
├───MongoContext.cs         <-- Exposes IMongoCollection<T> to the whole application
└───MongoSettings.cs        <-- Connection settings

Taking a closer look, focusing on a small entity shown in the BSON, the Book. This Book class is a main entity which has its own attributes. For the examples, we'll use a simplified version.

Let’s see how our Book is translated into C#:

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

public class Book
{
    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; } = string.Empty;

    [BsonElement("title")]
    public string Title { get; set; } = string.Empty;

    [BsonElement("publisherId")] 
    [BsonRepresentation(BsonType.ObjectId)]
    public string PublisherId { get; set; } = string.Empty;

    [BsonElement("authors")]
    public List<AuthorInBook> Authors { get; set; } = new();

    [BsonElement("categories")]
    public List<Category> Categories { get; set; } = new();
}

public class AuthorInBook
{
    [BsonElement("name")]
    public string Name { get; set; } = string.Empty;

    [BsonElement("bibliography")]
    public string Bibliography { get; set; } = string.Empty;
}

public class Category
{
    [BsonElement("name")]
    public string Name { get; set; } = string.Empty;

    [BsonElement("description")]
    public string Description { get; set; } = string.Empty;
}

Adding it to the context:

using MongoDB.Driver;

public class MongoContext
{
    private readonly IMongoDatabase _database;

    public MongoContext(MongoSettings settings)
    {
        var client = new MongoClient(settings.ConnectionString);
        _database = client.GetDatabase(settings.DatabaseName);
    }

    public IMongoCollection<Book> Books =>
        _database.GetCollection<Book>("books");
}

Being used in the Repository:

using MongoDB.Driver;

public class BookRepository
{
    private readonly IMongoCollection<Book> _collection;

    public BookRepository(MongoContext context)
    {
        _collection = context.Books; 
    }

    public async Task<List<Book>> GetAllAsync()
    {
        return await _collection.Find(_ => true).ToListAsync();
    }

    public async Task<Book?> GetByIdAsync(string id)
    {
        return await _collection.Find(x => x.Id == id).FirstOrDefaultAsync();
    }

    public async Task CreateAsync(Book book)
    {
        await _collection.InsertOneAsync(book);
    }
}

Analyzing the code, it’s possible to identify what is described as “infrastructure infection”. Some layers of this project are infected by the MongoDB driver. Entities and the repository import it, and the controller/service layer depends on these classes.

Although the implementation is simple and functional at first glance with our Book model, it introduces some unnecessary coupling that will make the system harder to evolve.

The entity now depends on MongoDB attributes such as ObjectId, which means that business rules become tied to persistence details, reducing Domain independence and making changes in drivers or storage impact parts of the system that, in theory, should be stable.

The repository, in turn, fails to fully fulfill its role as an abstraction. Instead of isolating data access, it only wraps direct calls to the MongoDB driver, making the code tightly coupled to the driver’s API.

private readonly IMongoCollection<Book> _collection;

The Repository is not just using the database anymore. The MongoDB driver is shaping everything and forcing the Book class to satisfy the driver.

It limits the flexibility of the entire application. This coupling directly impacts testability, since the driver's dependency on interfaces makes creating mocks more complex and, in many cases, leads to an overreliance on integration tests.

Can you imagine what could happen if the developer received a task to switch databases or export all entities to a library? It would not be a refactor, it would be a rewrite.

This type of approach, even being common in introductory examples, puts the database as one of the central elements of our software while the Domain starts to play a secondary role.

All of this goes against Clean Architecture principles, which propose exactly the opposite: a system driven by behavior and business rules, with infrastructure being only an external detail.

A Way Out: Translation Layer and Atomic Operations

To guarantee everyone can understand how the proposed isolation works and materializes in practice, it’s essential to understand the project organization.

The folder structure is not just a style choice, but a direct representation of our architectural decisions, establishing clear boundaries between business rules and persistence details:

C:\...\MongoIntegrationAPI\
├───Domain\
│   ├───Entities\           <-- Pure POCOs (Author.cs, Book.cs)
│   ├───Enums\
│   └───Interfaces\         <-- Contracts (IBookRepository.cs)
├───Infrastructure\
│   ├───DataModels\         <-- BSON-decorated models (BookDataModel.cs)
│   ├───Repositories\       <-- Implementations and mappings
│   ├───Daos\               <-- MongoDB-specific operations
│   └───MongoDbSetup.cs     <-- Configuration
└───Controllers\            <-- Application entry point

Inside Infrastructure, we’re going to have three types of classes:

• Specific repositories such as BookRepository to receive Domain entities, transform them into DataModels, and move them to database actions.
• A Generic Repository to provide easier access and reusable CRUD methods, receiving DataModels as parameters and never knowing about the Domain.
• Specific DAOs such as BookDao, a precision tool for MongoDB atomic operations.

Inside the Domain directory lies the core of our system, composed exclusively of essential business elements. The entities are defined as simple objects without any dependency on external libraries, while interfaces guarantee clear contracts about what the system needs to do.

This layer represents the application’s behavior and must stay isolated from any technical detail.

In this model, there is no indication of how the data will be persisted in the database. The focus is exclusively on representing the business.

// Domain layer
public class Book
{
   public string Id { get; set; } = string.Empty;
   public string Title { get; set; } = string.Empty;
   public string PublisherId { get; set; } = string.Empty;
   public List<AuthorInBook> Authors { get; set; } = new();
   public List<Category> Categories { get; set; } = new();
}

public class AuthorInBook
{
    public string Id { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
}

You can notice that our Book entity carries embedded information from our Author, just like the BSON shown earlier, but now it’s not a database decision anymore, it comes from business rules.

The Book entity is loaded, validated, and persisted together with categories and authors, so we create it this way in the Domain.

The difference now is that business operations made us design the entity with these attributes, and MongoDB just respects this with embedding patterns.

If you would keep this shape even with another database, it’s a Domain choice. Otherwise, the database is still in charge.

On the other hand, the Infrastructure folder focuses on all persistence decisions. This is where DataModels live, responsible for handling specific MongoDB features.

The concrete repositories make the bridge between Domain and Database. This organization ensures the complexity stays contained, preventing it from “leaking” into the rest of the system:

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoIntegrationAPI.Infrastructure.Attributes;

namespace MongoIntegrationAPI.Infrastructure.DataModels
{
    // Infrastructure layer: storage decisions
    [CollectionName("books")]
    public class BookDataModel
    {
        [BsonId]
        [BsonRepresentation(BsonType.ObjectId)]
        public string? Id { get; set; }

        public string Title { get; set; } = string.Empty;

        [BsonRepresentation(BsonType.ObjectId)]
        public string PublisherId { get; set; } = string.Empty;

        // The database stores nested objects to optimize reads
        public List<AuthorEmbeddedModel> Authors { get; set; } = new();

        public List<CategoryEmbeddedModel> Categories { get; set; } = new();
    }
}

DataModel is where we isolate all persistence-related decisions, such as the use of ObjectId and embedding structures. This allows us to optimize persistence without affecting the Domain.

Reading our DataModel, it’s possible to notice [CollectionName("books")]. It’s not from MongoDB, it’s from our architecture to make it easier to use our Generic Repository pattern.

We’ll use MongoDB, but how can we use just one class to control the commands here?

Let’s start by looking into how these classes work together, beginning with the new attribute in the DataModel.

The interface:

namespace MongoIntegrationAPI.Infrastructure.Repositories
{
    public interface IGenericRepository<TDocument> where TDocument : class
    {
        Task AddAsync(TDocument document);
        Task<TDocument?> GetByIdAsync(string id);
        Task<IEnumerable<TDocument>> GetAllAsync();
        Task ReplaceAsync(string id, TDocument document);
        Task DeleteAsync(string id);
    }
}

The implementation:

using MongoDB.Bson;
using MongoDB.Driver;
using MongoIntegrationAPI.Infrastructure.Attributes;
using System.Reflection;

namespace MongoIntegrationAPI.Infrastructure.Repositories
{
    public class GenericRepository<TDocument> : IGenericRepository<TDocument> where TDocument : class
    {
        private readonly IMongoCollection<TDocument> _collection;

        public GenericRepository(IMongoDatabase database)
        {
            var collectionName = typeof(TDocument)
                .GetCustomAttribute<CollectionNameAttribute>()?.Name
                ?? typeof(TDocument).Name;

            _collection = database.GetCollection<TDocument>(collectionName);
        }

        public async Task AddAsync(TDocument document)
        {
            await _collection.InsertOneAsync(document);
        }

        public async Task<IEnumerable<TDocument>> GetAllAsync()
        {
            return await _collection.Find(Builders<TDocument>.Filter.Empty).ToListAsync();
        }

        public async Task<TDocument?> GetByIdAsync(string id)
        {
            var filter = Builders<TDocument>.Filter.Eq("_id", new ObjectId(id));
            return await _collection.Find(filter).FirstOrDefaultAsync();
        }

        public async Task ReplaceAsync(string id, TDocument document)
        {
            var filter = Builders<TDocument>.Filter.Eq("_id", new ObjectId(id));
            await _collection.ReplaceOneAsync(filter, document);
        }

        public async Task DeleteAsync(string id)
        {
            var filter = Builders<TDocument>.Filter.Eq("_id", new ObjectId(id));
            await _collection.DeleteOneAsync(filter);
        }
    }
}

The constructor of our Repository asks for an IMongoDatabase to get the Collection found by the collectionName, which is the result of our CollectionNameAttribute on the DataModel.

namespace MongoIntegrationAPI.Infrastructure.Attributes
{
    [AttributeUsage(AttributeTargets.Class, Inherited = false)]
    public class CollectionNameAttribute : Attribute
    {
        public string Name { get; }

        public CollectionNameAttribute(string name)
        {
            Name = name;
        }
    }
}

The main point of this architecture is the role of the specific repository as a translator whenever the Domain and DataModel shapes diverge, which is almost always the case in real systems.

It’s no longer a passive intermediary. It explicitly converts the data between the two models and calls the generic version to make updates:

// Infrastructure
public async Task AddAsync(Book book)
{
   var dataModel = new BookDataModel
   {
       Title = book.Title,
       PublisherId = book.PublisherId,
       Authors = book.Authors
           .Select(a => new AuthorEmbeddedModel
           {
               Id = a.Id,
               Name = a.Name
           })
           .ToList()
   };

   await _genericRepository.AddAsync(dataModel);

   // We adopt the native ObjectId pragmatically,
   // reflecting it back into the Domain after creation
   book.Id = dataModel.Id!;
}

This section works as a barrier against the corruption of responsibilities, acting as an anti-corruption layer.

Database changes stop here in these repositories, allowing us to maintain the stability of our business rules while the Generic Repository only receives DataModel objects.

These repositories work well for translating documents. Now let’s analyze performance scenarios in MongoDB.

Loading a massive embedded document into memory just to add a single field into an array is a waste of resources. This is the point where we need a new layer responsible for leveraging specific MongoDB features.

The new layer is going to be the Data Access Object (DAO).

Think of it like a hospital. The Repository is the reception desk. You go there to find a patient, schedule an appointment, or retrieve a record.

The DAO is the specialist who walks into the archives room, knows exactly which folder to pull, and updates a single page without taking the whole file off the shelf.

// Infrastructure layer: BookDao.cs (atomic performance)
public async Task<bool> AddAuthorToBookAtomicAsync(string bookId, AuthorEmbeddedModel author)
{
    var filter = Builders<BookDataModel>.Filter.Eq(b => b.Id, bookId);

    var update = Builders<BookDataModel>.Update.Push(b => b.Authors, author);

    var result = await _collection.UpdateOneAsync(filter, update);

    return result.MatchedCount > 0;
}

In document database design, there exists a fundamental rule:

“Data that's accessed together should be stored together.”

Embeddings help us follow this rule and create denormalization that is very useful for reads, but can make updates very costly.

By coupling this logic into the DAO, we solve this problem.

Instead of loading the entire Book into the application, changing it with C#, and rewriting the whole document, we use the $push operator to alter only the necessary fragment directly in the database.

The Repository orchestrates the business flow, but only the DAO knows the syntax and atomic operations of the MongoDB driver.

The final result is an architecture where Embedding becomes a clear storage decision and the DAO becomes a precision tool to manipulate data.

In the project, it becomes evident that the BookRepository exposes a clear method to add an Author, while internally using the DAO to submit the surgical update of the BSON document.

With this, we can reach the best of both worlds: a behavior-focused Domain supported by an Infrastructure layer capable of extracting all the performance MongoDB can offer, without either side needing to know the other’s technical details.