1. Introduction 🌱

Understanding how MongoDB works under the hood— its storage engine, query planner, replication protocol, and concurrency model — transforms how you design schemas, write queries, and diagnose production issues.

This tutorial explores MongoDB's internal architecture: from how a single document is stored on disk, to how a cluster coordinates replication and sharding across many nodes.

2. MongoDB Architecture 🏛️

At a high level, MongoDB's architecture separates concerns into distinct layers, each responsible for a specific part of data handling.

3. Storage Engine 🗄️

The storage engine is the component responsible for how data is actually written to and read from disk. It is pluggable, though WiredTiger has been the default since MongoDB 3.2.

4. WiredTiger 🌳

WiredTiger uses a LSM-like or B-Tree based structure with multi-version concurrency control (MVCC), allowing readers and writers to operate without blocking each other in most cases.

5. BSON Internals 📦

BSON (Binary JSON) is MongoDB's native document format — a binary-encoded serialization that supports richer types than plain JSON, such as Date, ObjectId, and Int64.

6. Document Storage 📄

Within WiredTiger, documents are stored in collections, which are internally organized as B-Trees keyed by _id or a synthetic record identifier.

7. Collection Storage 🗂️

Each collection maps to its own WiredTiger table internally, alongside separate tables for each of its indexes.

const stats = await db.collection('orders').stats();
console.log('Storage size:', stats.storageSize);
console.log('Total index size:', stats.totalIndexSize);
console.log('Average doc size:', stats.avgObjSize);

8. Index Internals 📇

MongoDB indexes are implemented as B-Trees, mapping indexed field values to the location of the corresponding document.

9. Query Execution Engine ⚙️

When a query runs, MongoDB's execution engine processes it through a tree of execution stages, each responsible for a specific operation like scanning, filtering, or sorting.

const plan = await db.collection('orders')
  .find({ status: 'pending' })
  .sort({ createdAt: -1 })
  .explain('executionStats');

console.log(plan.executionStats.executionStages.stage); // e.g. "SORT" -> "IXSCAN" -> "FETCH"

10. Query Planner 🧭

Before execution, the query planner evaluates multiple candidate index strategies (called plans), runs a brief competition between them, and caches the winner.

11. Aggregation Engine 🧮

The aggregation framework compiles a pipeline into an internal execution plan, and where possible, pushes early stages down to use available indexes.

const plan = await db.collection('orders').aggregate([
  { $match: { status: 'completed' } },
  { $group: { _id: '$customerId', total: { $sum: '$amount' } } },
]).explain();

console.log(JSON.stringify(plan.stages, null, 2));

12. Replication Internals 🔁

A replica set maintains multiple copies of the same data, with one primary node accepting writes and secondary nodes replicating changes asynchronously.

13. Oplog 📜

The oplog (operations log) is a special capped collection recording every write operation in an idempotent form, enabling both replication and change streams.

// Simplified representation of an oplog entry
{
  ts: Timestamp(1690000000, 1),
  op: 'u',           // update operation
  ns: 'shopDB.orders',
  o: { $set: { status: 'shipped' } },
  o2: { _id: ObjectId('...') },
}

14. Sharding Internals 🧩

Sharding distributes data horizontally across multiple shards (each typically a replica set), coordinated by mongos routers and config servers.

15. Chunk Management 🧱

Within a sharded collection, data is divided into chunks — contiguous ranges of shard key values — which the balancer redistributes across shards to keep load even.

const chunks = await db.getSiblingDB('config').chunks
  .find({ ns: 'shopDB.orders' })
  .toArray();

console.log('Total chunks:', chunks.length);

16. Memory Management 🧠

WiredTiger maintains an internal cache (by default around 50% of available RAM minus 1GB) holding frequently accessed pages of data and index B-Trees.

// mongod.conf
storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 4

17. Journaling 📓

The journal is a write-ahead log that records operations before they're applied to the in-memory cache, ensuring durability across unexpected crashes between checkpoints.

18. Locking Mechanism 🔒

MongoDB uses a multi-granularity lockingsystem — global, database, collection, and (within WiredTiger) document-level — to balance concurrency with consistency.

19. Concurrency Control 🔀

WiredTiger's MVCC model allows multiple transactions to operate on independent snapshots of data, avoiding traditional reader-writer contention.

// The driver automatically retries transient write conflicts
// when retryWrites=true is set in the connection string (default since MongoDB 4.2 drivers)

20. Transactions Internals 🔐

Multi-document transactions build on the same MVCC snapshot mechanism, coordinating across the oplog to ensure atomicity across multiple operations and even multiple shards.

21. Change Streams Internals 📡

Change streams are implemented as a filtered, resumable view over the oplog, exposed through a change-stream-specific aggregation stage internally.

const changeStream = collection.watch();

changeStream.on('change', (change) => {
  console.log('Resume token:', change._id);
});

// Resuming from a specific point after a disconnect
const resumedStream = collection.watch([], { resumeAfter: savedResumeToken });

22. Performance Internals ⚡

23. Best Practices ✅

24. Common Misconceptions 🚫

25. Frequently Asked Questions ❓

26. Summary 📝