# mongodb/laravel-mongodb architecture

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

- Interactive diagram: https://gitdiagram.com/mongodb/laravel-mongodb
- Repository: https://github.com/mongodb/laravel-mongodb

## Overview

##### Project Type and Purpose
- This is an open-source PHP library/package that plugs into a Laravel application to extend the Eloquent ORM and query builder, enabling full MongoDB support.
- It is not a stand-alone app but a set of Laravel ServiceProviders, model and query classes, schema builders, drivers for cache/queue/session, and integrations (Scout, validation, bus).

##### Main Components
a. Laravel Application (Host)
- Service Container / IoC
- Facades (DB, Cache, Queue, Session, Validator, Scout, Bus)
b. This Package (mongodb/laravel-mongodb)
- Service Providers
– MongoDBServiceProvider
– MongoDBBusServiceProvider
– ValidationServiceProvider
- Connection Layer
– Connection (wraps PHP MongoDB driver)
– Manager (handles multiple connections, read preferences, TLS)
- Query & Eloquent Extensions
– Query\Builder, AggregationBuilder, Grammar, Processor
– Eloquent\Model, DocumentModel, Builder, Casts, Relations (embeds, morphs, etc.)
– Schema\Builder, Blueprint, Grammar (for migrations)
- Subsystem Drivers
– Cache: MongoStore, MongoLock
– Queue: MongoConnector, MongoQueue, MongoJob
– Session: MongoDbSessionHandler
– Scout: ScoutEngine (search integration)
– Validator: DatabasePresenceVerifier
– Bus: MongoBatchRepository
c. External Service
- MongoDB Server / Atlas cluster (reads, writes, transactions, search)

##### Relationships and Data Flow
- On boot, Laravel App registers package’s ServiceProviders into the IoC container.
- Facades (DB, Cache, Queue, Session, Validator, Scout, Bus) resolve to package classes.
- Queries issued via Eloquent or Query Builder flow through the package’s Builder → Grammar/Processor → Connection → PHP MongoDB driver → MongoDB Server.
- Subsystems (cache, queue, session) call their respective drivers in the package, which in turn issue MongoDB commands.
- Scout full-text/Atlas Search requests go through ScoutEngine → Query/AggregationBuilder → MongoDB Atlas Search.
- Validation DatabasePresenceVerifier uses connection to verify record existence.
- Bus dispatch and batching use MongoBatchRepository for job storage and retrieval.

##### Architectural Patterns and Principles
- Inversion of Control & Dependency Injection: ServiceProviders bind interfaces to MongoDB-specific implementations.
- Adapter/Decorator: Extends Laravel’s native classes (Eloquent\Model, Query\Builder) without altering their APIs.
- Single Responsibility: Separate packages for cache, queue, session, validation, scout, bus.
- Layered Architecture:
- Presentation/API Layer (Laravel Facades/Models)
- Domain/Data Access Layer (Query & Eloquent Extensions)
- Infrastructure Layer (Connection, PHP Driver, MongoDB Server)

##### Essential Elements
- Components inside the package with clear labels (Connection, Query Builder, Eloquent Models, Schema Builder, Cache Driver, Queue Driver, Session Handler, Scout Engine, Validator, Bus Repository)
- ServiceProviders → bind interfaces in Service Container
- DB/Caching/Queue/Session/Scout/Validator/Bus Facades → respective package classes
- Package classes → MongoDB Server
- Version compatibility and configuration files (composer.json, config defaults).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Laravel Core
    subgraph "Laravel App"
        SC["Service Container / IoC"]:::laravel
        FacDB["Facade DB"]:::laravel
        FacCache["Facade Cache"]:::laravel
        FacQueue["Facade Queue"]:::laravel
        FacSession["Facade Session"]:::laravel
        FacValidator["Facade Validator"]:::laravel
        FacScout["Facade Scout"]:::laravel
        FacBus["Facade Bus"]:::laravel
    end

    %% Package Components
    subgraph "mongodb/laravel-mongodb"
        direction TB
        subgraph "Service Providers" 
            MSP["MongoDBServiceProvider"]:::package
            MBSP["MongoDBBusServiceProvider"]:::package
            VSP["ValidationServiceProvider"]:::package
        end
        subgraph "Connection Layer"
            Conn["Connection"]:::package
            Manager["Manager"]:::package
        end
        subgraph "Query & Eloquent Extensions"
            QB["Query Builder"]:::package
            AB["Aggregation Builder"]:::package
            QG["Query Grammar"]:::package
            QP["Query Processor"]:::package
            EM["Eloquent Base Model"]:::package
            DM["DocumentModel"]:::package
            EB["Eloquent Builder"]:::package
            subgraph "Casts"
                BU["BinaryUuid Cast"]:::package
                OID["ObjectId Cast"]:::package
            end
            Relations["Relations"]:::package
        end
        subgraph "Schema"
            SB["Schema Builder"]:::package
            BP["Schema Blueprint"]:::package
            SG["Schema Grammar"]:::package
        end
        subgraph "Subsystem Drivers"
            MS["MongoStore (Cache)"]:::package
            ML["MongoLock (Cache)"]:::package
            QC["MongoConnector"]:::package
            MQ["MongoQueue"]:::package
            MJ["MongoJob"]:::package
            SH["MongoDbSessionHandler"]:::package
            SE["ScoutEngine"]:::package
            VP["DatabasePresenceVerifier"]:::package
            BB["MongoBatchRepository"]:::package
        end
    end

    %% External Service
    MongoDB["MongoDB Server / Atlas"]:::external

    %% Relationships
    %% Service Providers
    MSP -->|binds into| SC
    MBSP -->|binds into| SC
    VSP -->|binds into| SC

    %% Facades to package
    FacDB -->|"executeQuery()"| QB
    FacCache -->|"cacheRead()/cacheWrite()"| MS
    FacCache -->|"cacheLock()"| ML
    FacQueue -->|"dispatchJob()"| QC
    FacSession -->|"sessionRead()/sessionWrite()"| SH
    FacValidator -->|"verify()"| VP
    FacScout -->|"search()"| SE
    FacBus -->|"dispatchBatch()"| BB

    %% Query flow
    QB -->|"toGrammar()"| QG
    QG -->|"toProcessor()"| QP
    QP -->|"toConnection()"| Conn
    AB -->|"toConnection()"| Conn
    EM -->|"toConnection()"| Conn
    DM -->|"toConnection()"| Conn
    EB -->|"toConnection()"| Conn
    BU -->|"cast()"| Conn
    OID -->|"cast()"| Conn
    Relations -->|"relationQuery()"| Conn

    %% Schema
    SB -->|"schemaOp()"| SG
    SG -->|"toConnection()"| Conn
    BP -->|"blueprint()"| SG

    %% Subsystem drivers to MongoDB
    Conn -->|"driverCall()"| MongoDB
    MS -->|"cacheCmd()"| MongoDB
    ML -->|"lockCmd()"| MongoDB
    QC -->|"queueCmd()"| MongoDB
    MQ -->|"queueProcess()"| MongoDB
    MJ -->|"jobOps()"| MongoDB
    SH -->|"sessionCmd()"| MongoDB
    SE -->|"searchQuery()"| MongoDB
    VP -->|"presenceCheck()"| MongoDB
    BB -->|"batchOps()"| MongoDB

    %% Click Events
    click MSP "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/MongoDBServiceProvider.php"
    click MBSP "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/MongoDBBusServiceProvider.php"
    click VSP "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Validation/ValidationServiceProvider.php"
    click Conn "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Connection.php"
    click QB "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Query/Builder.php"
    click AB "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Query/AggregationBuilder.php"
    click QG "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Query/Grammar.php"
    click QP "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Query/Processor.php"
    click EM "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Eloquent/Model.php"
    click DM "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Eloquent/DocumentModel.php"
    click EB "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Eloquent/Builder.php"
    click BU "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Eloquent/Casts/BinaryUuid.php"
    click OID "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Eloquent/Casts/ObjectId.php"
    click Relations "https://github.com/mongodb/laravel-mongodb/tree/5.x/src/Relations"
    click SB "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Schema/Builder.php"
    click BP "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Schema/Blueprint.php"
    click SG "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Schema/Grammar.php"
    click MS "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Cache/MongoStore.php"
    click ML "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Cache/MongoLock.php"
    click QC "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Queue/MongoConnector.php"
    click MQ "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Queue/MongoQueue.php"
    click MJ "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Queue/MongoJob.php"
    click SH "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Session/MongoDbSessionHandler.php"
    click SE "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Scout/ScoutEngine.php"
    click VP "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Validation/DatabasePresenceVerifier.php"
    click BB "https://github.com/mongodb/laravel-mongodb/blob/5.x/src/Bus/MongoBatchRepository.php"

    %% Styles
    classDef laravel fill:#add8e6,stroke:#333,stroke-width:1px
    classDef package fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
```
