gdb
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.
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.
- 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
- 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:
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.
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.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.
Repository Diagram
The project includes an interactive visualization of the repository’s history and structure, which you can explore here:
This graphical view is especially useful for new contributors or anyone looking to gain deeper insight into the project’s evolution and structure, providing a clear and visual understanding of the workflow.
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 and discussions! Here’s how you can get involved:
- Ask questions or share ideas: Join our GitHub Discussions.
- Real-time chat: For quick conversations, join us on Gitter.
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.
License
Project License
The minified builds of GenosDB (GDB) are provided free of charge (Freeware) for both personal and commercial use. You are welcome to integrate these builds into your applications without cost.
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 minified 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 minified 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: estebanrfp@gmail.com or start a conversation in GitHub Discussions.