# GUN — Decentralized Real-Time Graph Database

> A peer-to-peer, decentralized graph database for building offline-first and real-time applications without a central server.

## Install

Save in your project root:

# GUN — Decentralized Real-Time Graph Database

## Quick Use
```bash
npm install gun
```
```js
import Gun from 'gun';

const gun = Gun();
gun.get('greeting').put({ text: 'Hello, world' });
gun.get('greeting').on(data => console.log(data.text));
```

## Introduction
GUN is a decentralized, peer-to-peer graph database that syncs data across browsers and servers in real time. It works offline by default and merges changes automatically when peers reconnect, making it a foundation for apps that need resilience without relying on a single backend.

## What GUN Does
- Stores graph-structured data that syncs across peers in real time
- Works fully offline and merges changes on reconnect via CRDTs
- Runs in browsers, Node.js, and React Native without a central server
- Provides built-in user authentication and data encryption (SEA module)
- Supports pub/sub style reactive data subscriptions

## Architecture Overview
GUN uses a directed graph model where every node is identified by a soul (unique key). Data propagates via a gossip protocol over WebSockets, WebRTC, or any custom transport. Conflict resolution relies on a HAM (Hypothetical Amnesia Machine) CRDT algorithm that deterministically merges concurrent writes without coordination. Peers can be browsers, relay servers, or both.

## Self-Hosting & Configuration
- Run a relay peer with `npx gun` or add GUN as Express/Koa middleware
- Relay peers are optional — browsers can sync directly via WebRTC
- Persistence is pluggable: RAD (Radix Storage Adapter) writes to disk, S3, or IPFS
- The SEA (Security, Encryption, Authorization) module handles user key pairs
- Configure peer URLs at instantiation to point at your relay servers

## Key Features
- No single point of failure; any peer can join or leave the network
- HAM-based CRDT ensures deterministic conflict resolution without locking
- Graph traversal API supports nested references and back-links
- End-to-end encryption via the SEA module for private user data
- Lightweight — the core library is under 10 KB gzipped

## Comparison with Similar Tools
- **Firebase Realtime Database** — cloud-managed and centralized; GUN is fully decentralized
- **CouchDB + PouchDB** — document-based with server-centric replication; GUN uses peer-to-peer gossip
- **OrbitDB** — built on IPFS; GUN has its own transport layer and works in plain browsers
- **Automerge** — CRDT library without a built-in database; GUN provides storage and networking together

## FAQ
**Q: Do I need a server to use GUN?**
A: No. Browsers can sync directly via WebRTC. A relay server helps with NAT traversal and persistence but is not mandatory.

**Q: How does conflict resolution work?**
A: GUN uses the HAM algorithm, a state-based CRDT that picks a deterministic winner for each field based on timestamps and state vectors.

**Q: Is the data encrypted by default?**
A: Not by default. Enable the SEA module to add user-level key pairs and field-level encryption.

**Q: Can GUN handle large datasets?**
A: It works best for real-time collaborative data. For analytical queries on large volumes, a traditional database is more appropriate.

## Sources
- https://github.com/amark/gun
- https://gun.eco

---
Source: https://tokrepo.com/en/workflows/09c76aef-429a-11f1-9bc6-00163e2b0d79
Author: AI Open Source