genosdb

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), rule-based role promotion & demotion (Governance), and efficient local storage utilizing OPFS.

Table of Contents

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

How it works

GenosDB runs entirely in your browser — there is no central database server. The Security Manager signs every operation with your key, nodes are stored locally in OPFS, and changes replicate peer-to-peer over WebRTC through GenosRTC, GenosDB's own networking layer. Nostr relays only help peers discover each other — they never see your data.

Nostr Relays
    │
    │ peer discovery only
    ▼

Browser + GenosDB
│
├─► Security Manager      (signs operations)
│
├─► Graph Store (OPFS)    (stores nodes)
│    │
│    ├─► Other Peers      (GenosRTC / WebRTC sync)
│    │
│    └─► BroadcastChannel (cross-tab)
│
└─► db.map subscriptions  (reactive queries)

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.
  • Governance (Role Promotion & Demotion): Optional engine that resolves each user's role from declarative rules (native GenosDB queries) using last-match-wins — a merit ladder where climbing overrides lower tiers and losing the condition auto-demotes, each change signed by an online superadmin. (Governance)

🧪 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 signaling over the Nostr protocol. For large-scale applications (100+ peers), GenosRTC includes an optional Cellular Mesh overlay that reduces connection complexity from O(N²) to O(N), enabling large-scale networks.

  This module was developed internally for the specific needs of GenosDB and leverages state-of-the-art cryptographic dependencies, such as @noble/curves, to ensure maximum security and performance.

  Enables peer-to-peer synchronization, ensuring real-time updates across multiple instances of the application.

  Note: Among the available networks supported by GenosRTC, this project specifically uses the Nostr protocol for decentralized communication.

  What is Nostr?
  Nostr (Notes and Other Stuff Transmitted by Relays) is a decentralized protocol designed for censorship-resistant global communication. It operates without relying on centralized servers, instead using a network of relays to transmit signed messages between peers. Nostr is particularly well-suited for applications requiring secure, private, and scalable peer-to-peer interactions, such as social networks, messaging systems, or collaborative tools.

• BroadcastChannel:
  Facilitates lightweight communication between browser tabs, allowing seamless updates without relying on external servers.

General Note: These dependencies are integral to the project's performance and functionality, ensuring efficient data handling and real-time synchronization while leveraging decentralized technologies like Nostr.

Presentation Video

Contributing

We value community contributions and welcome your help in improving GenosDB! Currently, contributions are focused on:

• 📝 Improving our documentation.
• 💡 Submitting usage examples and tutorials.
• 🐞 Reporting bugs or suggesting new features.

Please read our Contribution Guidelines for more details. We do not accept pull requests for the core source code at this time.

Community

We value community contributions — get involved through:

• Issues — report bugs or request features
• Discussions — ask questions or share ideas

See the discussion on Product Hunt:

Feel free to ask questions, share ideas, or just say hello! 👋

For more details on contributing, check out our Contributing Guidelines.

Special Thanks

Being part of the GunDB community has given me the opportunity to contribute to and take part in incredible projects. GunDB and GenosDB belong to the same research effort in distributed systems. My sincerest gratitude to Mark Nadal, Founder of GunDB, for his friendship and unconditional support.

A special mention to William Blankenship, Network Fellow at WebAI, for his initial support and kind words about the vision for GenosDB.

License

Project License

The production builds of GenosDB (GDB) are free to use for both personal and commercial projects. You can integrate them into your applications without any licensing fees.

However, the source code for GenosDB is proprietary and is not available under an open-source license. You do not have the right to decompile, reverse-engineer, or modify the core source code.

Third-Party Licenses

This project includes third-party dependencies with their own respective licenses. For detailed information, see the Third-Party Licenses page.

Maintenance

This repository provides production builds of GenosDB (GDB), a decentralized P2P graph database designed for modern web applications. These builds are freely available for anyone to use and integrate into their projects. Please note that the source code is not publicly available at this time; only the production builds versions are provided. The project is actively maintained by Esteban Fuster Pozzi (@estebanrfp)

Author

Esteban Fuster Pozzi (@estebanrfp) — Full Stack JavaScript Developer and creator of GenosDB (GDB), a free-to-use real-time graph database built entirely with modern vanilla JavaScript.

Business Inquiries & Collaboration

GenosDB is an independently developed project with a long-term vision to power the next generation of secure, decentralized, and real-time applications.

For strategic partnerships, enterprise support inquiries, or discussions regarding the project's roadmap and future, please feel free to reach out directly.

Contact: [e-mail] or start a conversation in GitHub Discussions.