# zookzook/elixir-mongodb-driver architecture

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

- Interactive diagram: https://gitdiagram.com/zookzook/elixir-mongodb-driver
- Repository: https://github.com/zookzook/elixir-mongodb-driver

## Overview

##### Project type and purpose
- This is a library–an Elixir driver for MongoDB. Its purpose is to provide a complete MongoDB client implementation in Elixir, including connection pooling, BSON encoding/decoding, change streams, GridFS, transactions, migrations, bulk writes, telemetry, and various MongoDB commands.

##### File structure
- Top-level: configuration (`config/*.exs`), CI workflows, examples, an “insights” Phoenix app, the driver source under `lib/` (split into `bson/`, `mongo/`, `mongo_db_connection/`, `session/`, `tasks/`, utilities), tests under `test/`, Mix project files.
- “examples” demonstrate usage patterns (change streams, CRUD, AWS X.509).
- “insights” is a Phoenix-based monitoring UI leveraging the driver.
- Core driver modules implement key features:
- `lib/bson/*` – BSON codec, types, encoder/decoder protocols
- `lib/mongo/*` – the public API (Mongo module), command modules, topology, events, bulk writes, GridFS, migration, change streams, session management
- `lib/mongo_db_connection/*` – integration with DBConnection for pooling
- `lib/session/*` – server-side session and transaction wrappers
- `lib/tasks/mongo.ex` – Mix tasks for migrations

##### README for additional insights
- Confirms features: versions supported, pooling via DBConnection, streaming cursors, GridFS, change streams, transactions, telemetry, migrations, compression, auth mechanisms, plug-ins, and example usages.
- Mentions Telemetry events, Mix.Tasks.Mongo for migrations, external dependencies (DBConnection, Telemetry, optional `:ezstd`, Phoenix in insights).

##### Main components
a. Client application layer
- User code (can be plain Elixir app, Ecto adapter, Phoenix “insights” web UI, or example scripts)
b. Public API layer (Mongo module suite)
- `Mongo` façade
- `Mongo.Repo` convenience wrapper
- `Mongo.Collection` macros
c. Core driver internals
- Connection management & pooling
– DBConnection Behaviour
– `Mongo.MongoDBConnection` adapter
– TCP/SSL socket under the hood
- BSON subsystem
– `BSON.Encoder`, `BSON.Decoder`, types, utilities
- Topology & server monitoring
– Replica set discovery, `Topology`, `Monitor`
- Command execution
– CRUD commands, aggregation, change streams, bulk writes, GridFS, transactions
- Session & transaction manager
– `Mongo.Session`, session pooling, transaction boundaries
- Migration engine
– Mix tasks (`Mix.Tasks.Mongo*`), `Mongo.Migration` lock/unlock, scripts under `priv/mongo/migrations`
- Telemetry & logging
– Telemetry events `[:mongodb_driver, :execution]`, optional Logger via `Mongo.EventHandler`
d. External systems and dependencies
- MongoDB deployment (single node, replica set, sharded cluster)
- Optional compressors (`:zlib`, `:zstd` via `:ezstd`)
- Optional Phoenix app (insights) for monitoring
- DBConnection and Telemetry hex packages

##### Relationships and data flows
- The Client calls the `Mongo` API → API builds BSON document via `BSON.Encoder` → passes to DBConnection adapter → opens/borrows a connection from the pool → encodes request onto TCP/SSL → sent to MongoDB → receives wire protocol response → `BSON.Decoder` decodes → returns results to client.
- Session/Transaction: client wraps calls in `Mongo.transaction/3`, driver attaches session metadata, commits/aborts via session module.
- Change streams and GridFS: special long-lived cursors managed by event handlers/streaming modules.
- Migration: at startup or via Mix task, migration scripts run through `Mongo.Migration`, use the same connection subsystem.
- Telemetry: each command emits execution duration event.

##### Architectural patterns & design principles
- Behaviour abstraction: DBConnection behaviour for pooling, telemetry hooks, event handlers for logging/monitoring.
- Protocols: Elixir protocols for BSON encoding/decoding and user-defined structs.
- Supervision: OTP supervisors for connection pool, monitor processes, example Phoenix app has its own supervision tree.
- Modular design: separate modules for codecs, connections, commands, sessions, migrations.
- Streaming: use of Elixir Streams and Enumerable protocol for cursors and bulk writes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Application Layer"
        Client["User Code (Elixir App, Ecto, Phoenix Insights, Examples)"]:::frontend
    end

    %% API Layer
    subgraph "Public API Layer"
        PublicAPI["Mongo Facade & Helpers"]:::frontend
    end

    %% Core Internals
    subgraph "Core Driver Internals"
        %% BSON
        subgraph "BSON Subsystem"
            BSONSub["BSON Encoder/Decoder, Types, Utils"]:::core
        end
        %% Connection Pool
        subgraph "Connection Management & Pooling"
            ConnPool["DBConnection Adapter & Pool"]:::core
        end
        %% Topology & Monitoring
        subgraph "Topology & Server Monitoring"
            Topology["Topology, Monitor, Server Description"]:::core
        end
        %% Command Modules
        subgraph "Command Execution Modules"
            Commands["CRUD, Aggregation, Bulk Writes, Change Streams, GridFS"]:::core
        end
        %% Session & Transaction
        subgraph "Session & Transaction Manager"
            SessionMgr["Session Pool & Transaction Wrappers"]:::core
        end
        %% Migration
        subgraph "Migration Engine"
            MigrationEng["Mix Tasks & Migration Scripts"]:::core
        end
        %% Telemetry & Logging
        subgraph "Telemetry & Logging"
            Telemetry["Telemetry Events & EventHandler"]:::core
        end
    end

    %% External Dependencies
    subgraph "External Systems & Dependencies"
        MongoDB["MongoDB Server (Replica Set/Sharded)"]:::external
        DBConnDep["DBConnection Package"]:::external
        TelemetryDep["Telemetry Package"]:::external
        Compressor["Optional Compressors (:zlib, :ezstd)"]:::external
    end

    %% Examples & Insights
    subgraph "Examples & Optional Plugins"
        Examples["Usage Examples"]:::optional
        Insights["Phoenix Insights Monitoring UI"]:::optional
    end

    %% Flows
    Client -->|"Calls API"| PublicAPI
    PublicAPI -->|"Build BSON Document"| BSONSub
    BSONSub -->|"Encoded Document"| ConnPool
    ConnPool -->|"Wire Protocol over TCP/SSL"| MongoDB
    MongoDB -->|"Response bytes"| ConnPool
    ConnPool -->|"Decode BSON"| BSONSub
    BSONSub -->|"Decoded Result"| PublicAPI
    PublicAPI -->|"Returns Result"| Client

    %% Session Flow
    Client -->|"transaction/3"| SessionMgr
    SessionMgr -->|Attach Session Metadata| ConnPool

    %% Command Flow
    PublicAPI -->|"Execute Command"| Commands
    Commands -->|"Use Topology"| Topology
    Commands -->|"Emit Telemetry"| Telemetry
    Telemetry -->|Notify| TelemetryDep

    %% Migration Flow
    MigrationEng -->|"Runs via Mix.Tasks.Mongo"| ConnPool
    MigrationEng -->|"Scripts in"| MigrationEng

    %% Examples & Insights Integration
    Examples -->|"Use Change Streams, CRUD"| PublicAPI
    Insights -->|"Consumes Telemetry"| Telemetry

    %% External Dependencies Links
    ConnPool -.->|deps| DBConnDep
    Telemetry -.->|deps| TelemetryDep
    ConnPool -.->|optional deps| Compressor

    %% Click Events
    click BSONSub "https://github.com/zookzook/elixir-mongodb-driver/tree/master/lib/bson"
    click PublicAPI "https://github.com/zookzook/elixir-mongodb-driver/tree/master/lib/mongo"
    click ConnPool "https://github.com/zookzook/elixir-mongodb-driver/tree/master/lib/mongo_db_connection"
    click SessionMgr "https://github.com/zookzook/elixir-mongodb-driver/tree/master/lib/session"
    click MigrationEng "https://github.com/zookzook/elixir-mongodb-driver/tree/master/priv/mongo/migrations"
    click Examples "https://github.com/zookzook/elixir-mongodb-driver/tree/master/examples"
    click Insights "https://github.com/zookzook/elixir-mongodb-driver/tree/master/insights"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef optional fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
