# jlongster/crdt-example-app architecture

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

- Interactive diagram: https://gitdiagram.com/jlongster/crdt-example-app
- Repository: https://github.com/jlongster/crdt-example-app

## Overview

This is a demo collaborative todo app illustrating CRDT-style local edits and multi-device synchronization. Users edit todos and todo types in the browser; client code records timestamped changes, syncs them through a server, and uses Merkle differences to find missing messages. The server stores messages and returns changes for clients to apply. The graph covers the sampled app, client state and sync logic, shared ordering/consistency primitives, and server storage. Some source was only partially sampled, so relationships not shown there are omitted.

Main entry points: [`client/sync.js`](https://github.com/jlongster/crdt-example-app/blob/master/client/sync.js) (Sync engine), [`server/index.js`](https://github.com/jlongster/crdt-example-app/blob/master/server/index.js) (Message API), [`client/main.js`](https://github.com/jlongster/crdt-example-app/blob/master/client/main.js) (Todo interface), [`client/db.js`](https://github.com/jlongster/crdt-example-app/blob/master/client/db.js) (Todo data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_app_ui["Todo interface<br/>[main.js]"]
end

subgraph group_client_core["Client data and sync"]
  node_local_data["Todo data<br/>[db.js]"]
  node_client_clock["Client clock<br/>[clock.js]"]
  node_client_sync["Sync engine<br/>[sync.js]"]
end

subgraph group_shared["Shared primitives"]
  node_timestamps["Logical timestamps<br/>[timestamp.js]"]
  node_merkle["Merkle comparison<br/>[merkle.js]"]
end

subgraph group_server["Sync server"]
  node_sync_api["Message API<br/>[index.js]"]
  node_message_store[("SQLite message store<br/>[init.sql]")]
end

node_user(("App user"))

node_user -->|"edits todos"| node_app_ui
node_app_ui -->|"reads and updates"| node_local_data
node_app_ui -->|"requests sync"| node_client_sync
node_local_data -->|"sends changes"| node_client_sync
node_local_data -->|"gets timestamps"| node_client_clock
node_client_sync -->|"uses clock"| node_client_clock
node_client_sync -->|"parses timestamps"| node_timestamps
node_client_sync -->|"compares trees"| node_merkle
node_client_sync -->|"posts messages"| node_sync_api
node_sync_api -->|"stores and queries"| node_message_store
node_sync_api -->|"updates and diffs"| node_merkle
node_sync_api -->|"parses message times"| node_timestamps

click node_app_ui "https://github.com/jlongster/crdt-example-app/blob/master/client/main.js"
click node_local_data "https://github.com/jlongster/crdt-example-app/blob/master/client/db.js"
click node_client_clock "https://github.com/jlongster/crdt-example-app/blob/master/client/clock.js"
click node_client_sync "https://github.com/jlongster/crdt-example-app/blob/master/client/sync.js"
click node_timestamps "https://github.com/jlongster/crdt-example-app/blob/master/shared/timestamp.js"
click node_merkle "https://github.com/jlongster/crdt-example-app/blob/master/shared/merkle.js"
click node_sync_api "https://github.com/jlongster/crdt-example-app/blob/master/server/index.js"
click node_message_store "https://github.com/jlongster/crdt-example-app/blob/master/server/init.sql"

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_app_ui,node_user toneBlue
class node_local_data,node_client_clock,node_client_sync toneAmber
class node_timestamps,node_merkle toneMint
class node_sync_api,node_message_store toneRose
```

## Components

### Browser app

- [Todo interface](https://github.com/jlongster/crdt-example-app/blob/master/client/main.js): `client/main.js`

### Client data and sync

- [Todo data](https://github.com/jlongster/crdt-example-app/blob/master/client/db.js): `client/db.js`
- [Client clock](https://github.com/jlongster/crdt-example-app/blob/master/client/clock.js): `client/clock.js`
- [Sync engine](https://github.com/jlongster/crdt-example-app/blob/master/client/sync.js): `client/sync.js`

### Shared primitives

- [Logical timestamps](https://github.com/jlongster/crdt-example-app/blob/master/shared/timestamp.js): `shared/timestamp.js`
- [Merkle comparison](https://github.com/jlongster/crdt-example-app/blob/master/shared/merkle.js): `shared/merkle.js`

### Sync server

- [Message API](https://github.com/jlongster/crdt-example-app/blob/master/server/index.js): `server/index.js`
- [SQLite message store](https://github.com/jlongster/crdt-example-app/blob/master/server/init.sql): `server/init.sql`

### Other components

- **App user**

## Connections

- App user → Todo interface: edits todos (evidence: `client/main.js`)
- Todo interface → Todo data: reads and updates (evidence: `client/main.js`)
- Todo interface → Sync engine: requests sync (evidence: `client/main.js`)
- Todo data → Sync engine: sends changes (evidence: `client/db.js`)
- Todo data → Client clock: gets timestamps (evidence: `client/db.js`)
- Sync engine → Client clock: uses clock (evidence: `client/sync.js`)
- Sync engine → Logical timestamps: parses timestamps (evidence: `client/sync.js`)
- Sync engine → Merkle comparison: compares trees (evidence: `client/sync.js`)
- Sync engine → Message API: posts messages (evidence: `client/sync.js`)
- Message API → SQLite message store: stores and queries (evidence: `server/index.js`)
- Message API → Merkle comparison: updates and diffs (evidence: `server/index.js`)
- Message API → Logical timestamps: parses message times (evidence: `server/index.js`)