{"id":18265907,"url":"https://github.com/aviondb/aviondb-specs","last_synced_at":"2025-09-17T20:10:01.663Z","repository":{"id":100330613,"uuid":"250490274","full_name":"aviondb/aviondb-specs","owner":"aviondb","description":"Specs for AvionDB","archived":false,"fork":false,"pushed_at":"2020-04-14T21:58:38.000Z","size":214,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-20T19:39:58.976Z","etag":null,"topics":["database","ipfs","orbitdb","orbitdb-stores","schemas"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aviondb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-03-27T09:17:31.000Z","updated_at":"2022-10-15T17:57:51.000Z","dependencies_parsed_at":"2023-05-13T22:00:09.418Z","dependency_job_id":null,"html_url":"https://github.com/aviondb/aviondb-specs","commit_stats":null,"previous_names":["aviondb/aviondb-specs","dappkit/aviondb-specs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviondb%2Faviondb-specs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviondb%2Faviondb-specs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviondb%2Faviondb-specs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aviondb%2Faviondb-specs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aviondb","download_url":"https://codeload.github.com/aviondb/aviondb-specs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247252396,"owners_count":20908682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","ipfs","orbitdb","orbitdb-stores","schemas"],"created_at":"2024-11-05T11:20:36.537Z","updated_at":"2025-09-17T20:09:56.620Z","avatar_url":"https://github.com/aviondb.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"## AvionDB Specs [Draft]\n\n---\n\n\u003e AvionDB aims to bring MongoDB-like developer interface to Web 3.0. This document provides an introduction to the AvionDB.\n\n**DISCLAIMER: This document will be subjected to drastic changes. I assure you, we are not even sure with name of the project 😂 Feel free to jump in to discuss about this document [here](https://discord.gg/sFXyza), and add issues, PR 😉**\n\nThis version of document uses [OrbitDB](https://github.com/orbitdb/orbit-db) at its core. OrbitDB provides a powerful way to write, read, update \u0026 delete data in a distributed way.\n\nAt the core of OrbitDB databases is the OPLOG, where all data are stored as a log of operations, which are then calculated into the appropriate schema for application use. Updating the database is equivalent to adding a new entry to its OPLOG. The OPLOG is calculated to give the current state of the database, which is the view you generally interact with.\n\nOrbitDB stores the data in [IPFS](https://ipfs.io) via [ipfs-log](https://github.com/orbitdb/ipfs-log). OrbitDB helps format how that data is stored, provides access control, and ability to replicate/sync that data between nodes. The only data stored separately by OrbitDB is a cache of heads, the manifest, etc.\n\nOrbitDB organizes its functionality by separating different data management concerns, schemas and APIs into **stores**.\n\nYou have the following stores available in OrbitDB out-of-the-box:\n\n| Name                                                                                              | Description                                                                                                                                                                     |\n| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **[log](https://github.com/orbitdb/orbit-db/blob/master/API.md#orbitdblognameaddress)**           | An _immutable_ (append-only) log with traversable history. Useful for _\"latest N\"_ use cases or as a message queue.                                                             |\n| **[feed](https://github.com/orbitdb/orbit-db/blob/master/API.md#orbitdbfeednameaddress)**         | A _mutable_ log with traversable history. Entries can be added and removed. Useful for _\"shopping cart\"_ type of use cases, or for example as a feed of blog posts or \"tweets\". |\n| **[keyvalue](https://github.com/orbitdb/orbit-db/blob/master/API.md#orbitdbkeyvaluenameaddress)** | A simple key-value database that supports any JSON-serializable data, even nested objects.                                                                                      |\n| **[docs](https://github.com/orbitdb/orbit-db/blob/master/API.md#orbitdbdocsnameaddress-options)** | A document database that stores JSON documents which can be indexed by a specified key. Useful for building search indices or version controlling documents and data.           |\n| **[counter](https://github.com/orbitdb/orbit-db/blob/master/API.md#orbitdbcounternameaddress)**   | An increment-only integer counter useful for counting events separate from log/feed data.                                                                                       |\n\n### Architecture\n\n![AvionDB Architecture](./assets/Architecture.png)\n\nAvionDB uses OrbitDB stores to model MongoDB-like Databases. It creates a notion of:\n\n- Each AvionDB instance can have several [Databases](#databases).\n- Each Database can have several [Collections](#collections). The strucuture of these Collections are defined by [Schemas](#Schemas)\n- Each Collection can have several [Documents](#Documents).\n\n#### Databases\n\nAvionDB maintains a list of Databases using a `kvstore`.\n\n```json\n{\n  \"database1\": {\n    \"address\": \"/orbitdb/zdpuAsMWWt6GGqBQYhVoTrRfNGCtVtMvoEDmc5QDvFfgn12xL/database1\",\n    \"createdAt\": \"Sat Mar 28 2020 11:34:26 GMT+0530 (India Standard Time)\"\n  },\n  \"database2\": {\n    \"address\": \"/orbitdb/zdpuAxy3c6kzRWQeP7BdoEXq4tkDdSNMVYfj2Mu44y5NGLffx/database2\",\n    \"createdAt\": \"Sat Mar 28 2020 11:34:26 GMT+0530 (India Standard Time)\"\n  }\n}\n```\n\nThis `kvstore` stores basic details about the created databases:\n\n- names of database: `database1`\n- address of database that points to Collections `kvstore`: `/orbitdb/zdpuAsMWWt6GGqBQYhVoTrRfNGCtVtMvoEDmc5QDvFfgn12xL/database1`\n- other details such as `createdAt`, etc.\n\n#### Collections\n\nAvionDB maintains a list of Collections using a `kvstore`.\n\n```json\n{\n  \"collection1\": {\n    \"address\": \"/orbitdb/zdpuAyfVXRNSRLyRBqWczweq5VtfZvBSikSLnbSySrZqC1raq/collection1\",\n    \"createdAt\": \"Sat Mar 28 2020 11:34:26 GMT+0530 (India Standard Time)\"\n  },\n  \"collection2\": {\n    \"address\": \"/orbitdb/zdpuAnnmAJxeeWdxcQb3EUjqBQwCC6qkBf1qJpkJRhDgk9TLM/collection2\",\n    \"createdAt\": \"Sat Mar 28 2020 11:34:26 GMT+0530 (India Standard Time)\"\n  }\n}\n```\n\nThis `kvstore` stores basic details about the created collections:\n\n- names of database: `collection1`\n- address of database that points to Collections `kvstore`: `/orbitdb/zdpuAyfVXRNSRLyRBqWczweq5VtfZvBSikSLnbSySrZqC1raq/collection1`\n- other details such as `createdAt`, etc.\n\n#### Documents\n\nAvionDB maintains a list of Documents using a `docstore`.\n\n```json\n[\n  {\n    \"_id\": \"0\",\n    \"name\": \"peer1\",\n    \"time\": \"Sat Mar 28 2020 12: 05: 26 GMT+0530 (India Standard Time)\"\n  },\n  {\n    \"_id\": \"1\",\n    \"name\": \"peer2\",\n    \"time\": \"Sat Mar 28 2020 12: 05: 26 GMT+0530 (India Standard Time)\"\n  }\n]\n```\n\nEach document in the `docstore` is indexed by an `\"_id\"`. It allows you to add additional application data defined by a [Schema](#Schemas).\n\n#### Schemas\n\nA AvionDB service document schema is a `JSON` object that allows you to define the shape and content of documents and embedded documents in a collection. You can use a schema to require a specific set of fields, configure the content of a field, or to validate changes to a document based on its beginning and ending states.\n\n[TODO: Add Schema Example]\n\n### Supported Methods/Operations\n\nAvionDB creates a wrapper around OrbitDB `put`, `get` methods, allowing for complex queries for adding, updating, fetching \u0026 deleting documents.\n\nFor example,\n\n- Adding bulk documents at once.\n- Updating all the documents in a `Users` collection whos `age` is greater than `21` and `address` is `Canada`.\n- Fetching all the documents in a `Users` collection whos `age` is greater than `21` and `address` is `India`.\n- Deleting all the documents in a `Users` collection whos `age` is less than `15` and `address` is `Canada`.\n\n### Storing \u0026 Retrieving big files\n\nAvionDB supports storing \u0026 retrieving big files (file size to be decided) like images, gifs, audio, video, etc. using [MagnumFS](#magnumfs).\n\n#### MagnumFS\n\nMagnumFS uses IPFS to store big files and manages the hashes of the files in IpfsDB. Something similar to [GridFS](https://docs.mongodb.com/manual/core/gridfs/) in MongoDB.\n\n[TODO: Add more details]\n\n### Decentralized Data Query (Local \u0026 Global)\n\nAvionDB allows you to query data in 2 ways: _Local_ \u0026 _Global_.\n\n#### Local Data Query\n\nIn this type of query, you usually deal with databases which are local to your IPFS node. So, the search happens only within your local AvionDB database.\n\n[TODO: Provide more details]\n\n#### Global Data Query\n\nIn this type of query, you deal with database that is distruted among several peers in the network. So, when you query for data, your query is executed over the network of peers.\n\nHere the databases can be pubic/private within a set of peers in the network.\n\n[TODO: Provide more details]\n\n### Dynamic Access Control\n\nAvionDB exposes a powerful dynamic access control, thanks to [OrbitDB's extensible authentication middleware](https://github.com/orbitdb/orbit-db-access-controllers#creating-a-custom-access-controller).\n\nBy default OrbitDB uses `OrbitDBAccessController` which can be extended to add additional authentication. This additional authentication can be anything ranging from authenticating with Metmask, 3ID, DIDs, etc., to calling any APIs to validate access.\n\nThere is on going discussion on dynamic access control using [ceramic protocol](https://www.ceramic.network/). You can join the dicussion [here](https://discord.gg/cXyREx).\n\n### Data Replication\n\nAs we are dealing with databases, we will require to replicate our databases for scaling, backup and sharing data across multiple peers. AvionDB uses [pub-sub](https://github.com/ipfs/interface-js-ipfs-core) to communicate addresses of databases, collections \u0026 documents among the peers in the network. Using the addresses, the peers can replicate the databases, collections \u0026 documents on their local IPFS nodes.\n\n[TODO: Add more details]\n\n### Encryption/Decryption\n\nAvionDB provides configurable encryption/decryption out-of-the-box. It provides basic encryption (encryption schemes to be decided) which can be configured to use any other encryption schemes of your choice \u0026 security needs.\n\n### On-Going Discussions\n\n- **Using [Ceramic Protocol](https://www.ceramic.network/) with AvionDB**: Join the discussion [here](https://discord.gg/cXyREx)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviondb%2Faviondb-specs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faviondb%2Faviondb-specs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviondb%2Faviondb-specs/lists"}