Architecture

MongoDB is split into two server binaries that share most of their code: mongod (the data-bearing process) and mongos (the sharding router). Both binaries link against the bulk of src/mongo/ and configure themselves at startup according to which role they play. The shell (jstestshell) is a JavaScript host built on SpiderMonkey that links against the same core libraries.

High-level component view

graph TD
    subgraph Clients["Clients & drivers"]
        Driver[Driver / mongosh / jstestshell]
    end

    subgraph Router["mongos (sharding router)"]
        SEPRouter[Service entry point<br/>src/mongo/s/service_entry_point_router_role.cpp]
        TxnRouter[Transaction router<br/>src/mongo/s/transaction_router.cpp]
        ARS[Async requests sender<br/>src/mongo/s/async_requests_sender.cpp]
        ConfigCache[Catalog cache<br/>routing table]
    end

    subgraph Shard["mongod (data node)"]
        Transport[Transport layer<br/>src/mongo/transport]
        SEPShard[Service entry point<br/>src/mongo/db/service_entry_point_shard_role.cpp]
        Commands[Commands<br/>src/mongo/db/commands]
        Query[Query engine<br/>src/mongo/db/query and db/exec]
        Repl[Replication coordinator<br/>src/mongo/db/repl]
        Storage[Storage interface<br/>src/mongo/db/storage]
        WT[WiredTiger<br/>src/third_party/wiredtiger]
    end

    Driver -->|wire protocol| Transport
    Driver -->|wire protocol| SEPRouter
    SEPRouter --> TxnRouter
    TxnRouter --> ARS
    ARS -->|target shards| Transport

    Transport --> SEPShard
    SEPShard --> Commands
    Commands --> Query
    Commands --> Repl
    Query --> Storage
    Repl --> Storage
    Storage --> WT

A driver speaks the MongoDB wire protocol over TCP/TLS (or, increasingly, gRPC — see src/mongo/transport/grpc/). The transport layer dispatches each OP_MSG to the service entry point for the binary's role:

• On mongod, service_entry_point_shard_role.cpp parses the command, runs auth and validation, and dispatches to the registered Command implementation under src/mongo/db/commands/.
• On mongos, service_entry_point_router_role.cpp does the same, but commands typically translate into multi-shard fan-out via the AsyncRequestsSender and the TransactionRouter.

Cluster topology

A typical deployment looks like:

graph LR
    Client -->|reads/writes| Mongos1[mongos]
    Client -->|reads/writes| Mongos2[mongos]

    Mongos1 -.config metadata.-> CSRS[Config Server<br/>replica set]
    Mongos2 -.config metadata.-> CSRS

    Mongos1 --> ShardA[Shard A<br/>replica set]
    Mongos1 --> ShardB[Shard B<br/>replica set]
    Mongos2 --> ShardA
    Mongos2 --> ShardB

    subgraph ShardA[Shard A replica set]
        PrimaryA[Primary]
        Sec1A[Secondary]
        Sec2A[Secondary]
        PrimaryA --> Sec1A
        PrimaryA --> Sec2A
    end

Within a shard, a replica set elects one primary that accepts writes; secondaries apply the oplog asynchronously. The config server replica set (CSRS) stores the cluster's routing table — the mapping of chunks of each sharded collection to shards — and is consulted by mongos instances.

Inside mongod: request lifecycle

sequenceDiagram
    autonumber
    participant Client
    participant Transport as transport/asio
    participant SEP as ServiceEntryPoint
    participant Cmd as Command
    participant Shard as ShardRole / locking
    participant Storage as Storage / WiredTiger
    participant OpObserver as OpObserver
    participant Repl as Replication

    Client->>Transport: OP_MSG (wire protocol)
    Transport->>SEP: handleRequest(OperationContext)
    SEP->>SEP: parse, auth, ApiParameters, OperationSession
    SEP->>Cmd: Command::run()
    Cmd->>Shard: acquireCollection / acquireDatabase
    Shard->>Storage: WriteUnitOfWork begin
    Cmd->>Storage: read or write via RecordStore / IndexAccessMethod
    Storage-->>Cmd: data
    Cmd->>OpObserver: onWrite (durable writes)
    OpObserver->>Repl: append oplog entry
    Cmd->>Storage: WriteUnitOfWork commit
    Cmd-->>SEP: BSONObj reply
    SEP-->>Transport: serialize OP_MSG reply
    Transport-->>Client: response

Key files for this flow:

• src/mongo/transport/asio/ — the ASIO-based async transport.
• src/mongo/db/service_entry_point_shard_role.cpp — top-level command dispatch on mongod.
• src/mongo/db/commands.cpp and src/mongo/db/commands/ — the Command registry and most command implementations.
• src/mongo/db/shard_role/ — modern acquireCollection/acquireCollectionMaybeLockFree API for accessing collections with the right locking and shard versioning.
• src/mongo/db/op_observer/ — the hook that writes oplog entries and fires triggers (e.g. for change streams).
• src/mongo/db/repl/ — the replication coordinator, oplog applier, and election logic.
• src/mongo/db/storage/ — the storage engine abstraction (record stores, sorted data interfaces, durability, recovery).

Major subsystems

Subsystem	Where	Wiki page
Replication	src/mongo/db/repl/	Replication
Sharding (data side)	src/mongo/db/s/	Sharding
Sharding router	src/mongo/s/	mongos
Query engine	src/mongo/db/query/, src/mongo/db/exec/	Query engine
Aggregation pipeline	src/mongo/db/pipeline/	Aggregation pipeline
Transactions	src/mongo/db/transaction/	Transactions
Change streams	src/mongo/db/pipeline/, docs/change_streams.md	Change streams
Index builds	src/mongo/db/index_builds/	Index builds
Time-series collections	src/mongo/db/timeseries/	Time-series
Authentication / authz	src/mongo/db/auth/, src/mongo/crypto/	Auth
Storage engine	src/mongo/db/storage/, src/third_party/wiredtiger/	Storage
Network transport	src/mongo/transport/	Transport
Async executors / pools	src/mongo/executor/, src/mongo/util/concurrency/	Executors
BSON	src/mongo/bson/	BSON
IDL (interface definition)	src/mongo/idl/, buildscripts/idl/	IDL
Structured logging	src/mongo/logv2/, docs/logging.md	logv2
Fail points	src/mongo/util/fail_point.h	Fail points

See Applications for the binaries themselves and Features for the cross-cutting capabilities.

Build system

MongoDB is built with Bazel. The top-level MODULE.bazel/WORKSPACE.bazel and the per-directory BUILD.bazel files describe the build graph. Tests are run via resmoke.py (see buildscripts/resmoke.py and src/mongo/resmoke/), which understands suite definitions in buildscripts/resmokeconfig/. See Getting started for the typical commands, and Tooling for a deeper dive into the build and lint pipeline.

Modules

The codebase is in the middle of a long-running modules effort that assigns every file to a module declared in modules_poc/modules.yaml and marks API visibility (PUBLIC, PRIVATE, FILE_PRIVATE, etc.) using attributes from src/mongo/util/modules.h. The modules_poc/ tooling validates that no file uses another module's PRIVATE API. The full design is described in docs/modularity.md.