# ferretdb/ferretdb architecture

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

- Interactive diagram: https://gitdiagram.com/ferretdb/ferretdb
- Repository: https://github.com/ferretdb/ferretdb

## Overview

FerretDB is a MongoDB wire-protocol proxy that translates client operations into PostgreSQL-backed document database work. The principal path is MongoDB client → connection/listener and middleware dispatch → command handling → DocumentDB/PostgreSQL, with results returned over the client connection. Separate HTTP Data API and MCP interfaces also feed the shared middleware. The README documents compatibility with MongoDB drivers and PostgreSQL with the DocumentDB extension. Some wiring is taken from that documentation and the sampled handler/API code; unsampled setup details are not inferred.

Main entry points: [`internal/handler/handler.go`](https://github.com/ferretdb/ferretdb/blob/main/internal/handler/handler.go) (Command handler), [`internal/util/setup/setup.go`](https://github.com/ferretdb/ferretdb/blob/main/internal/util/setup/setup.go) (Runtime setup), [`internal/handler/middleware/dispatcher.go`](https://github.com/ferretdb/ferretdb/blob/main/internal/handler/middleware/dispatcher.go) (Middleware dispatcher), [`internal/documentdb/pool.go`](https://github.com/ferretdb/ferretdb/blob/main/internal/documentdb/pool.go) (DocumentDB pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Client protocols"]
  node_wire_listener["Wire listener<br/>[listener.go]"]
  node_dispatcher["Middleware dispatcher<br/>[dispatcher.go]"]
  node_dataapi_server["Data API server<br/>[server.go]"]
  node_mcp_server["MCP server<br/>[server.go]"]
  node_proxy_handler["Proxy handler<br/>[proxy.go]"]
end

subgraph group_execution["Query execution"]
  node_command_handler["Command handler<br/>[handler.go]"]
  node_command_messages["MongoDB commands<br/>[commands.go]"]
  node_session_registry[("Session registry<br/>[registry.go]")]
end

subgraph group_storage["Document storage"]
  node_docdb_pool["DocumentDB pool<br/>[pool.go]"]
  node_docdb_api["DocumentDB API<br/>[documentdb_api.go]"]
end

subgraph group_operations["Operations"]
  node_setup["Runtime setup<br/>[setup.go]"]
  node_telemetry["Telemetry<br/>[telemetry.go]"]
  node_metrics["Metrics state<br/>[provider.go]"]
end

node_mongo_client(("MongoDB client"))
node_postgres[("PostgreSQL + DocumentDB")]
node_dataapi_client(("Data API client"))
node_mcp_client(("MCP client"))
node_proxy_client(("Proxy client"))

node_mongo_client -->|"sends MongoDB protocol"| node_wire_listener
node_wire_listener -->|"dispatches requests"| node_dispatcher
node_dispatcher -->|"routes commands"| node_command_handler
node_command_handler -->|"handles commands"| node_command_messages
node_command_handler -->|"executes database work"| node_docdb_pool
node_command_handler -->|"manages sessions"| node_session_registry
node_docdb_pool -->|"uses document API"| node_docdb_api
node_docdb_pool -->|"sends SQL"| node_postgres
node_dataapi_client -->|"sends HTTP requests"| node_dataapi_server
node_dataapi_server -->|"submits commands"| node_dispatcher
node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -->|"submits commands"| node_dispatcher
node_proxy_client -.->|"sends requests"| node_proxy_handler
node_setup -->|"configures runtime"| node_command_handler
node_setup -->|"configures listener"| node_wire_listener
node_setup -->|"configures API"| node_dataapi_server
node_setup -->|"configures MCP"| node_mcp_server
node_command_handler -->|"exposes metrics"| node_metrics
node_setup -->|"configures telemetry"| node_telemetry

click node_wire_listener "https://github.com/ferretdb/ferretdb/blob/main/internal/clientconn/listener.go"
click node_dispatcher "https://github.com/ferretdb/ferretdb/blob/main/internal/handler/middleware/dispatcher.go"
click node_command_handler "https://github.com/ferretdb/ferretdb/blob/main/internal/handler/handler.go"
click node_command_messages "https://github.com/ferretdb/ferretdb/blob/main/internal/handler/commands.go"
click node_session_registry "https://github.com/ferretdb/ferretdb/blob/main/internal/handler/session/registry.go"
click node_docdb_pool "https://github.com/ferretdb/ferretdb/blob/main/internal/documentdb/pool.go"
click node_docdb_api "https://github.com/ferretdb/ferretdb/blob/main/internal/documentdb/documentdb_api/documentdb_api.go"
click node_dataapi_server "https://github.com/ferretdb/ferretdb/blob/main/internal/dataapi/server/server.go"
click node_mcp_server "https://github.com/ferretdb/ferretdb/blob/main/internal/mcp/server.go"
click node_proxy_handler "https://github.com/ferretdb/ferretdb/blob/main/internal/handlers/proxy/proxy.go"
click node_setup "https://github.com/ferretdb/ferretdb/blob/main/internal/util/setup/setup.go"
click node_telemetry "https://github.com/ferretdb/ferretdb/blob/main/internal/util/telemetry/telemetry.go"
click node_metrics "https://github.com/ferretdb/ferretdb/blob/main/internal/util/state/provider.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_wire_listener,node_dispatcher,node_dataapi_server,node_mcp_server,node_proxy_handler,node_mongo_client,node_dataapi_client,node_mcp_client,node_proxy_client toneBlue
class node_command_handler,node_command_messages,node_session_registry,node_postgres toneAmber
class node_docdb_pool,node_docdb_api toneMint
class node_setup,node_telemetry,node_metrics toneRose
```

## Components

### Client protocols

- [Wire listener](https://github.com/ferretdb/ferretdb/blob/main/internal/clientconn/listener.go): `internal/clientconn/listener.go`
- [Middleware dispatcher](https://github.com/ferretdb/ferretdb/blob/main/internal/handler/middleware/dispatcher.go): `internal/handler/middleware/dispatcher.go`
- [Data API server](https://github.com/ferretdb/ferretdb/blob/main/internal/dataapi/server/server.go): `internal/dataapi/server/server.go`
- [MCP server](https://github.com/ferretdb/ferretdb/blob/main/internal/mcp/server.go): `internal/mcp/server.go`
- [Proxy handler](https://github.com/ferretdb/ferretdb/blob/main/internal/handlers/proxy/proxy.go): `internal/handlers/proxy/proxy.go`

### Query execution

- [Command handler](https://github.com/ferretdb/ferretdb/blob/main/internal/handler/handler.go): `internal/handler/handler.go`
- [MongoDB commands](https://github.com/ferretdb/ferretdb/blob/main/internal/handler/commands.go): `internal/handler/commands.go`
- [Session registry](https://github.com/ferretdb/ferretdb/blob/main/internal/handler/session/registry.go): `internal/handler/session/registry.go`

### Document storage

- [DocumentDB pool](https://github.com/ferretdb/ferretdb/blob/main/internal/documentdb/pool.go): `internal/documentdb/pool.go`
- [DocumentDB API](https://github.com/ferretdb/ferretdb/blob/main/internal/documentdb/documentdb_api/documentdb_api.go): `internal/documentdb/documentdb_api/documentdb_api.go`

### Operations

- [Runtime setup](https://github.com/ferretdb/ferretdb/blob/main/internal/util/setup/setup.go): `internal/util/setup/setup.go`
- [Telemetry](https://github.com/ferretdb/ferretdb/blob/main/internal/util/telemetry/telemetry.go): `internal/util/telemetry/telemetry.go`
- [Metrics state](https://github.com/ferretdb/ferretdb/blob/main/internal/util/state/provider.go): `internal/util/state/provider.go`

### Other components

- **MongoDB client**
- **PostgreSQL + DocumentDB**
- **Data API client**
- **MCP client**
- **Proxy client**

## Connections

- MongoDB client → Wire listener: sends MongoDB protocol
- Wire listener → Middleware dispatcher: dispatches requests
- Middleware dispatcher → Command handler: routes commands
- Command handler → MongoDB commands: handles commands
- Command handler → DocumentDB pool: executes database work
- Command handler → Session registry: manages sessions
- DocumentDB pool → DocumentDB API: uses document API
- DocumentDB pool → PostgreSQL + DocumentDB: sends SQL
- Data API client → Data API server: sends HTTP requests
- Data API server → Middleware dispatcher: submits commands
- MCP client → MCP server: calls tools
- MCP server → Middleware dispatcher: submits commands
- Proxy client → Proxy handler: sends requests
- Runtime setup → Command handler: configures runtime
- Runtime setup → Wire listener: configures listener
- Runtime setup → Data API server: configures API
- Runtime setup → MCP server: configures MCP
- Command handler → Metrics state: exposes metrics
- Runtime setup → Telemetry: configures telemetry