> ## Documentation Index
> Fetch the complete documentation index at: https://moridb.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How Mori's proxy intercepts, classifies, routes, and merges database operations.

## Overview

Mori sits between your application and two databases: the production database (read-only) and the Shadow database (read-write). Every query is intercepted, classified, routed, and — when needed — results from both databases are merged transparently.

<img src="https://mintcdn.com/mori/_wu2tWdDWJ-COt7J/logo/mori-arch.png?fit=max&auto=format&n=_wu2tWdDWJ-COt7J&q=85&s=e72add2729d4a710c8f171d3b8d57972" alt="mori architecture" width="5561" height="4700" data-path="logo/mori-arch.png" />

## Components

**Protocol Handler** — Speaks the target database's native wire protocol. Accepts connections, performs handshake/authentication, parses incoming messages, serializes outgoing results. Indistinguishable from a real database server to the application.

**Classifier** — Parses each query to determine operation type (`READ`, `WRITE`, `DDL`, `TRANSACTION`), affected tables, extractable primary keys, and whether it's a JOIN. Lightweight syntactic analysis — fast, sits in the hot path.

**Router** — Takes classifier output + [delta/tombstone state](/docs/concepts/components) and selects an execution [strategy](/docs/concepts/strategies). The core decision point.

**[Delta Manager](/docs/concepts/components)** — Maintains the Delta Map and Tombstone Set. Supports transaction staging: additions are staged within a transaction, promoted on COMMIT, discarded on ROLLBACK.

**[Schema Registry](/docs/concepts/components#schema-registry)** — Tracks per-table schema divergence. Used to adapt Prod rows during reads (inject NULLs for new columns, strip dropped columns, rename, cast types) and during hydration.

**Transaction Manager** — Per-connection transaction state. Coordinates transactions across Prod (read-only) and Shadow (read-write). Enforces [staged delta semantics](/docs/concepts/strategies#transaction-management).

**Engine Manager** — Connection pools to Prod and Shadow. Each app connection gets one dedicated Prod connection (read-only) and one dedicated Shadow connection (read-write).

**Merge Engine** — Combines Prod and Shadow results during reads. Handles single-table merges, JOIN patching, over-fetching for LIMIT queries, row filtering, and schema adaptation.

**Write Engine** — INSERT (Shadow-only), UPDATE (hydrate + Shadow), DELETE (Shadow + tombstone). Coordinates with Delta Manager on every mutation.

## Routing Overview

The Router decides which backend(s) handle each query based on the operation type and whether the affected tables have local changes. See the [Strategies](/docs/concepts/strategies) page for the complete routing decision matrix and detailed execution paths.

| Operation               | Clean Tables     | Dirty Tables             |
| ----------------------- | ---------------- | ------------------------ |
| `SELECT`                | Prod Direct      | Merged Read / Join Patch |
| `INSERT`                | Shadow Write     | Shadow Write             |
| `UPDATE`                | Hydrate + Shadow | Hydrate + Shadow         |
| `DELETE`                | Shadow Delete    | Shadow Delete            |
| `DDL`                   | Shadow DDL       | Shadow DDL               |
| `BEGIN/COMMIT/ROLLBACK` | Both             | Both                     |