# pubkey/rxdb architecture

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

- Interactive diagram: https://gitdiagram.com/pubkey/rxdb
- Repository: https://github.com/pubkey/rxdb

## Overview

RxDB is a local-first reactive NoSQL database for JavaScript. An application defines a schema, creates a database and collections, writes documents, and runs queries; the storage abstraction executes persistence while change streams support reactive updates and optional multi-instance coordination. Replication synchronizes local data with external systems through a shared protocol and adapter plugins. The README also documents backup, attachments, state, migrations, and other extensions. Core links use sampled source references; unsampled plugin relationships are shown only where documented.

Main entry points: [`src/rx-collection.ts`](https://github.com/pubkey/rxdb/blob/master/src/rx-collection.ts) (Collections), [`src/rx-storage-helper.ts`](https://github.com/pubkey/rxdb/blob/master/src/rx-storage-helper.ts) (Storage Interface), [`src/rx-query.ts`](https://github.com/pubkey/rxdb/blob/master/src/rx-query.ts) (Reactive Queries), [`src/rx-query-helper.ts`](https://github.com/pubkey/rxdb/blob/master/src/rx-query-helper.ts) (Query Preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Database Core"]
  node_database["Database API<br/>[rx-database.ts]"]
  node_collection["Collections<br/>[rx-collection.ts]"]
  node_document["Documents<br/>[rx-document.ts]"]
  node_schema["Schema Handling"]
  node_events["Change Events<br/>[rx-change-event.ts]"]
end

subgraph group_query["Query and Storage"]
  node_queryapi["Reactive Queries<br/>[rx-query.ts]"]
  node_queryhelper["Query Preparation<br/>[rx-query-helper.ts]"]
  node_planner["Query Planner<br/>[query-planner.ts]"]
  node_indexing["Custom Indexes<br/>[custom-index.ts]"]
  node_storageapi["Storage Interface"]
  node_memory[("Memory Storage")]
  node_localstorage[("LocalStorage")]
  node_multi["Multi-instance Events"]
end

subgraph group_sync["Replication and Sync"]
  node_replication["Replication Protocol<br/>[index.ts]"]
  node_adapters["Sync Adapters"]
end

subgraph group_plugins["Feature Plugins"]
  node_attachments["Attachments"]
  node_backup["Backup<br/>[index.ts]"]
  node_state["Reactive State"]
  node_migration["Schema Migration"]
  node_middleware["Pipeline Middleware<br/>[rx-pipeline.ts]"]
  node_react["React Integration"]
end

node_app(("JavaScript App"))

node_app -->|"uses"| node_database
node_database -.->|"opens"| node_collection
node_collection -->|"validates with"| node_schema
node_collection -.->|"creates"| node_document
node_collection -.->|"queries"| node_queryapi
node_queryapi -->|"prepares"| node_queryhelper
node_queryhelper -->|"plans with"| node_planner
node_planner -->|"reads schema"| node_schema
node_queryhelper -.->|"uses indexes"| node_indexing
node_collection -.->|"persists through"| node_storageapi
node_storageapi -.->|"dispatches to"| node_memory
node_storageapi -.->|"dispatches to"| node_localstorage
node_storageapi -->|"coordinates"| node_multi
node_queryapi -.->|"subscribes to"| node_events
node_replication -->|"uses"| node_storageapi
node_adapters -.->|"implements"| node_replication
node_app -->|"configures sync"| node_adapters
node_replication -->|"handles attachments"| node_attachments
node_app -->|"backs up data"| node_backup
node_app -->|"uses state"| node_state
node_app -->|"migrates schemas"| node_migration
node_app -->|"registers hooks"| node_middleware
node_app -.->|"integrates with"| node_react

click node_database "https://github.com/pubkey/rxdb/blob/master/src/rx-database.ts"
click node_collection "https://github.com/pubkey/rxdb/blob/master/src/rx-collection.ts"
click node_document "https://github.com/pubkey/rxdb/blob/master/src/rx-document.ts"
click node_schema "https://github.com/pubkey/rxdb/blob/master/src/rx-schema-helper.ts"
click node_events "https://github.com/pubkey/rxdb/blob/master/src/rx-change-event.ts"
click node_queryapi "https://github.com/pubkey/rxdb/blob/master/src/rx-query.ts"
click node_queryhelper "https://github.com/pubkey/rxdb/blob/master/src/rx-query-helper.ts"
click node_planner "https://github.com/pubkey/rxdb/blob/master/src/query-planner.ts"
click node_indexing "https://github.com/pubkey/rxdb/blob/master/src/custom-index.ts"
click node_storageapi "https://github.com/pubkey/rxdb/blob/master/src/rx-storage-helper.ts"
click node_memory "https://github.com/pubkey/rxdb/blob/master/src/plugins/storage-memory/rx-storage-instance-memory.ts"
click node_localstorage "https://github.com/pubkey/rxdb/blob/master/src/plugins/storage-localstorage/rx-storage-instance-localstorage.ts"
click node_multi "https://github.com/pubkey/rxdb/blob/master/src/rx-storage-multiinstance.ts"
click node_replication "https://github.com/pubkey/rxdb/blob/master/src/replication-protocol/index.ts"
click node_adapters "https://github.com/pubkey/rxdb/tree/master/src/plugins/replication"
click node_attachments "https://github.com/pubkey/rxdb/tree/master/src/plugins/attachments"
click node_backup "https://github.com/pubkey/rxdb/blob/master/src/plugins/backup/index.ts"
click node_state "https://github.com/pubkey/rxdb/tree/master/src/plugins/state"
click node_migration "https://github.com/pubkey/rxdb/tree/master/src/plugins/migration-schema"
click node_middleware "https://github.com/pubkey/rxdb/blob/master/src/plugins/pipeline/rx-pipeline.ts"
click node_react "https://github.com/pubkey/rxdb/tree/master/src/plugins/react"

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_database,node_collection,node_document,node_schema,node_events toneBlue
class node_queryapi,node_queryhelper,node_planner,node_indexing,node_storageapi,node_memory,node_localstorage,node_multi toneAmber
class node_replication,node_adapters toneMint
class node_attachments,node_backup,node_state,node_migration,node_middleware,node_react toneRose
class node_app toneIndigo
```

## Components

### Database Core

- [Database API](https://github.com/pubkey/rxdb/blob/master/src/rx-database.ts): `src/rx-database.ts`
- [Collections](https://github.com/pubkey/rxdb/blob/master/src/rx-collection.ts): `src/rx-collection.ts`
- [Documents](https://github.com/pubkey/rxdb/blob/master/src/rx-document.ts): `src/rx-document.ts`
- [Schema Handling](https://github.com/pubkey/rxdb/blob/master/src/rx-schema-helper.ts): `src/rx-schema-helper.ts`
- [Change Events](https://github.com/pubkey/rxdb/blob/master/src/rx-change-event.ts): `src/rx-change-event.ts`

### Query and Storage

- [Reactive Queries](https://github.com/pubkey/rxdb/blob/master/src/rx-query.ts): `src/rx-query.ts`
- [Query Preparation](https://github.com/pubkey/rxdb/blob/master/src/rx-query-helper.ts): `src/rx-query-helper.ts`
- [Query Planner](https://github.com/pubkey/rxdb/blob/master/src/query-planner.ts): `src/query-planner.ts`
- [Custom Indexes](https://github.com/pubkey/rxdb/blob/master/src/custom-index.ts): `src/custom-index.ts`
- [Storage Interface](https://github.com/pubkey/rxdb/blob/master/src/rx-storage-helper.ts): `src/rx-storage-helper.ts`
- [Memory Storage](https://github.com/pubkey/rxdb/blob/master/src/plugins/storage-memory/rx-storage-instance-memory.ts): `src/plugins/storage-memory/rx-storage-instance-memory.ts`
- [LocalStorage](https://github.com/pubkey/rxdb/blob/master/src/plugins/storage-localstorage/rx-storage-instance-localstorage.ts): `src/plugins/storage-localstorage/rx-storage-instance-localstorage.ts`
- [Multi-instance Events](https://github.com/pubkey/rxdb/blob/master/src/rx-storage-multiinstance.ts): `src/rx-storage-multiinstance.ts`

### Replication and Sync

- [Replication Protocol](https://github.com/pubkey/rxdb/blob/master/src/replication-protocol/index.ts): `src/replication-protocol/index.ts`
- [Sync Adapters](https://github.com/pubkey/rxdb/tree/master/src/plugins/replication): `src/plugins/replication`

### Feature Plugins

- [Attachments](https://github.com/pubkey/rxdb/tree/master/src/plugins/attachments): `src/plugins/attachments`
- [Backup](https://github.com/pubkey/rxdb/blob/master/src/plugins/backup/index.ts): `src/plugins/backup/index.ts`
- [Reactive State](https://github.com/pubkey/rxdb/tree/master/src/plugins/state): `src/plugins/state`
- [Schema Migration](https://github.com/pubkey/rxdb/tree/master/src/plugins/migration-schema): `src/plugins/migration-schema`
- [Pipeline Middleware](https://github.com/pubkey/rxdb/blob/master/src/plugins/pipeline/rx-pipeline.ts): `src/plugins/pipeline/rx-pipeline.ts`
- [React Integration](https://github.com/pubkey/rxdb/tree/master/src/plugins/react): `src/plugins/react`

### Other components

- **JavaScript App**

## Connections

- JavaScript App → Database API: uses (evidence: `README.md`)
- Database API → Collections: opens
- Collections → Schema Handling: validates with (evidence: `src/rx-schema-helper.ts`)
- Collections → Documents: creates
- Collections → Reactive Queries: queries
- Reactive Queries → Query Preparation: prepares (evidence: `src/rx-query.ts`)
- Query Preparation → Query Planner: plans with (evidence: `src/rx-query-helper.ts`)
- Query Planner → Schema Handling: reads schema (evidence: `src/query-planner.ts`)
- Query Preparation → Custom Indexes: uses indexes
- Collections → Storage Interface: persists through
- Storage Interface → Memory Storage: dispatches to (evidence: `src/plugins/storage-memory/rx-storage-instance-memory.ts`)
- Storage Interface → LocalStorage: dispatches to (evidence: `src/plugins/storage-localstorage/rx-storage-instance-localstorage.ts`)
- Storage Interface → Multi-instance Events: coordinates (evidence: `src/rx-storage-multiinstance.ts`)
- Reactive Queries → Change Events: subscribes to
- Replication Protocol → Storage Interface: uses (evidence: `src/replication-protocol/index.ts`)
- Sync Adapters → Replication Protocol: implements (evidence: `README.md`)
- JavaScript App → Sync Adapters: configures sync (evidence: `README.md`)
- Replication Protocol → Attachments: handles attachments (evidence: `src/replication-protocol/index.ts`)
- JavaScript App → Backup: backs up data (evidence: `README.md`)
- JavaScript App → Reactive State: uses state (evidence: `README.md`)
- JavaScript App → Schema Migration: migrates schemas (evidence: `README.md`)
- JavaScript App → Pipeline Middleware: registers hooks (evidence: `README.md`)
- JavaScript App → React Integration: integrates with
