GenosDB (GDB) – Decentralized P2P Graph Database

A lightweight, decentralized graph database designed for modern web applications, offering real-time peer-to-peer synchronization, SM (Security Manager) Provides WebAuthn-based authentication, role-based access control (RBAC), Access Control Lists (ACLs), and efficient local storage utilizing OPFS.

---

<!-- ### Nostr.band Followers  -->

Table of Contents

• Main Features
• Project Status
• Installation
• Documentation
• Contributing
• License
• Business Inquiries Collaboration

Main Features

✅ GenosDB Core

• High-Performance Engine & Efficient Storage: Utilizes OPFS for fast, local-first storage. The engine is optimized for extreme write loads, capable of processing tens of thousands of operations per second without blocking the main UI thread.
• Powerful & Flexible Queries: Supports standard CRUD operations for nodes and relationships, plus advanced, multi-hop recursive graph traversals to discover deep connections.
• Real-time Synchronization:
  • Between Devices (P2P): Employs an intelligent hybrid system (via GenosRTC) that combines real-time delta updates with a full-state fallback to ensure data consistency across all peers. This feature is enabled by initializing the database with the { rtc: true } option.
  • Between Tabs: Uses BroadcastChannel for instant, local synchronization.
  • Massive Scalability: Optional Cellular Mesh topology ({ rtc: { cells: true } }) enables horizontal scaling to large-scale networks by organizing peers into cells with bridge interconnections. (GenosRTC Cells)
• Optimized Data Handling: Efficiently serializes data with MessagePack and compresses it with Pako to reduce storage footprint and network payload.
• Extensible & Modular: The core is lightweight, but its capabilities can be easily extended with external modules for features like advanced indexing (e.g., Radix Tree).

Project Status

• Phase: Stable Beta
• Current Focus: The project has completed its major feature development and has entered a hardening phase. Our current focus is on rigorous testing, performance tuning, and solidifying API stability for the first stable release.
• Completed Features:
  • Basic queries.
  • Advanced queries.
  • Recursive Graph Traversal Queries: Execute complex, multi-hop graph traversals using the recursive $edge operator. This operator uses the source nodes as a starting point to discover and return all connected nodes that match a powerful sub-query, regardless of their relational distance. The entire traversal logic is resolved within a single, declarative query, eliminating the need for manual, multi-step lookups in the application code. The query engine is designed to handle deeply nested relational paths with exceptional speed.
  • Distributed storage.
  • Conflict resolution module (LWW).
  • Performance optimization.
  • Intelligent Hybrid Synchronization: GenosDB overcomes the limitations of naive P2P sync with an intelligent, dual-mode engine. It automatically exchanges tiny, compressed Deltas between active peers using a sliding-window Oplog for blazing-fast, low-latency updates. For peers that are too far out of sync, it seamlessly switches to a robust Full-State Fallback, guaranteeing absolute data consistency for everyone, no matter how long they've been offline.
  • Access Control Lists (ACLs): Optional submodule for fine-grained, node-level permissions, allowing owners to grant/revoke specific permissions ('read', 'write', 'delete') to other users per node, complementing the existing RBAC system.

🧪 API Status: Stable Beta

The GenosDB API is currently in a stable beta. We are actively adding features and improving stability. We recommend checking the CHANGELOG as we continue to refine the API for its first stable release.

✅ Role Based Access Control (RBAC)

• Customizable role hierarchy (superadmin, admin, etc)
• Biometric Registration and Authentication with WebAuthn
• Granular permissions (read/write/delete/publish)
• Role assignment with automatic expiration
• Cryptographic transaction verification

✅ Security

• Digital signature of critical operations
• Real-time permission validation
• Secure storage of roles in internal graph
• Security Manager (SM Architecture)

A Note on P2P System Reliability

GenosDB operates in a real-world P2P environment, which exposes the system to network uncertainties by design. Our engineering focus is on mitigating these uncertainties within our software through robust conflict resolution (CRDTs) and synchronization logic. While we cannot control external network conditions, our commitment is to the continuous research and development required to ensure the highest possible resilience of the GenosDB engine.

---

Installation

1. Via NPM

npm install genosdb

import { gdb } from "genosdb"

2. Direct use in browser from a CDN

<script type="module">
  import { gdb } from "https://cdn.jsdelivr.net/npm/genosdb@latest/dist/index.min.js"
</script>

Documentation

• Technical Docs: Find API references and guides in /docs.

• Introduction & Concepts: Visit our GitHub Wiki for an overview.

• Tutorials: Explore use cases on Medium.

For interactive, AI-assisted GenosDB documentation:

Mintlify GenosDB Documentation

Examples

We’ve created a collection of interactive examples to help you understand how GDB works in real-world scenarios. These examples cover everything from basic setup to advanced features like RBAC and P2P synchronization.

👉 Explore /docs/Examples

Project Documentation

• 🧭 ROADMAP.md (Planned features and milestones)
• 📄 WHITEPAPER.md (Architecture and design paper)
• 📜 PHILOSOPHY.md (Project philosophy, founder history, and coreprinciples)
• 🏠 README.md (Project overview, installation, and docs)
• 🧾 CHANGELOG.md (Release notes and version history)
• 🤝 CONTRIBUTING.md (How to contribute examples and guidelines)
• 🔀 MIGRATION.md (Migrate from "new GDB()" to "await gdb(..)")
• 🛡️ SECURITY.md (Security policy and vulnerability reporting)

---

Internal Dependencies

Below is a list of internal dependencies and their purposes within the project:

| Dependency | Usage | | ------------------ | ---------------------------------------------------------------------------------------| | @msgpack/msgpack | Data serialization/deserialization in MessagePack format. | | pako | Data compression/decompression using gzip. | | genosrtc | New Internal Module for P2P synchronization for sharing changes in real-time between tabs/devices. | | BroadcastChannel | Communication between browser tabs to notify local changes. |

Additional Information

• @msgpack/msgpack:
  This library is used to efficiently serialize and deserialize data, reducing payload sizes for storage and transmission.

• pako:
  Provides gzip compression to optimize data storage and network communication.

• GenosRTC (Internal Module for GenosDB) :
  GenosRTC is the real-time communication module for GenosDB, implementing peer-to-peer connections via WebRTC with