Version 0.5

Author: ErrorxCode

docs/Banner.png

@@ -0,0 +1,117 @@
+<p align="center"><img alt="clorabase" height="300" src="/Banner.png"></p>
+<p align="center">
+  <img src="https://img.shields.io/github/license/ErrorxCode/Clorabase?style=for-the-badge">
+  <img src="https://img.shields.io/github/stars/ErrorxCode/Clorabase?style=for-the-badge">
+  <img src="https://img.shields.io/github/issues/ErrorxCode/Clorabase?color=red&style=for-the-badge">
+  <img src="https://img.shields.io/github/forks/ErrorxCode/Clorabase?color=teal&style=for-the-badge">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Author-Rahil--Khan-cyan?style=flat-square">
+  <img src="https://img.shields.io/badge/Open%20Source-Yes-cyan?style=flat-square">
+  <img src="https://img.shields.io/badge/Written%20In-Java-cyan?style=flat-square">
+  <img src="https://jitpack.io/v/Clorabase/Clorabase.svg">
+</p>
+
+
+## Clorabase
+> *Turn your github repo into a No-SQL database*
+
+Clorabase is a free backend alternative (BaaS) for Android and java apps that uses GitHub API & Github repo to facilitate NoSQL database & NTFS like storage system. Clorabase is mostly made for small apps which has small backend/server/database requirements. If your app scales large or you need more database storage or bandwidth, Clorabase may not serve you. You should consider using [Firebase](https://firebase.google.com). Clorabase AIMS provides a money-free production-ready backend for building Android apps as a hobby or start-up. It is for those who don't earn money from their apps and build apps just for learning or non-profit use.
+
+<a href="https://github.com/Clorabase/Clorabase/releases/download/0.5/Console-stable-v0.5.apk"> <img alt="Download console" height=40 src="/button.png"></a>
+
+## Features
+- No account needed
+- Uses GitHub usage & quota
+- Absolutely Free, No paid plans
+- Serverless NO-SQL database
+- In-app messaging
+- In-app updates
+- Cloud storage for apps
+
+
+## Implementation
+#### To add SDK
+In your project **build.gradle**
+```
+allprojects {
+		repositories {
+			...
+			maven { url 'https://jitpack.io' }
+		}
+	}
+```
+In module **build.gradle** inside **dependencies** block:
+- For Android SDK:
+```
+implementation 'com.github.Clorabase.Clorabase:SDK:0.5'
+```
+- For Java SDK:
+```
+implementation 'com.github.Clorabase.Clorabase:Clorabase4j:0.5'
+```
+
+
+
+#### To generate a GitHub OAuth token
+1. Goto [Create token](https://github.com/settings/tokens/new)
+2. Select the 'Classic' token type and set the expiry to 'No expiration'
+3. Check the following in the scope sections:
+   - delete_repo
+   - repo
+4. Click generate.
+
+Now you can use this token to access the console and SDK.
+
+⚠️**NOTE:** Never publish your code containing this token on GitHub, if you do, then the token will automatically be deleted and your code will break
+
+
+### Documentation
+- [User guide](https://clorabase.github.io)
+
+## Clorabase vs Firebase
+The rule of thumb is, if you’re building a small project or dedicated mobile application, and you don’t mind the high bandwidth or database storage, Clorabase is a great place to start. If you’re looking for a more general-purpose data solution, value performance at scale and advanced querying, Firebase is going to serve your needs best.
+
+See the table below to compare Clorabase and Firebase with their features.
+
+| Feature | Clorabase | Firebase |
+| :--- | :--- | :--- |
+| **Primary Use Case** | Small, non-commercial Android apps, hobby projects, proof-of-concepts, learning. | Professional, scalable, and cross-platform applications (mobile & web). |
+| **Cost** | **Absolutely free, no paid plans or usage barriers.** | **Freemium model:** Generous free tier, but a "pay-as-you-go" plan for high usage. |
+| **Backend Storage** | Your data is stored in your own **GitHub repository** | Data is stored on **Google's cloud infrastructure** (Firestore, Realtime Database, Cloud Storage). |
+| **Scalability** | **Limited.** Best for small-scale applications. It may not perform well with large amounts of traffic or data. | **Highly Scalable.** Built to handle millions of concurrent connections and terabytes of data. |
+| **Core Services** | Databases (NoSQL), Cloud Storage, Push Messaging, In-App Messaging, In-App Updates. | Databases (Firestore, Realtime DB), Authentication, Cloud Functions, Hosting, Machine Learning, Analytics, Push Notifications, and more. |
+
+
+#### Choose Clorabase when...
+   -   Your primary concern is **cost**, and you need a completely free solution.
+        
+   -   You are building a personal or hobby project that won't have a large user base.
+        
+-   The app is an Android or Java only project.
+        
+  -   You have a simple data model and don't require advanced queries, authentication, or other integrated services.
+        
+-    You are comfortable with a more hands-on, DIY approach and are willing to handle things like user authentication yourself.
+
+
+
+## Contributing to Clorabase
+First off, thank you for considering contributing to Clorabase! It's because of people like you that this project can be what it is today.
+
+We welcome all types of contributions, from reporting bugs and suggesting new features to writing code and improving documentation.
+
+ Refer to [contribution.md](/contribution.md) to start contributing
+
+*-> For personal assitance, you can contact the repo owner at [email protected] or [x1.rahil](https://instagram.com/x1.rahil) on instagram*
+
+
+
+## Support
+This project comprises of lot's of energy, brainstorming, coding, testing and time. If this project has helped you in any way, please consider giving it a ⭐ to show your support and help it grow! Also, *watch* the repo to notify about updates.
+
+[![Readme Quotes](https://quotes-github-readme.vercel.app/api?type=horizontal&theme=dracula)](https://github.com/piyushsuthar/github-readme-quotes)
+
+
+![water](https://raw.githubusercontent.com/mayhemantt/mayhemantt/Update/svg/Bottom.svg)

docs/README.md

@@ -0,0 +1,14 @@
+![logo](favicon.png)
+
+# Clorabase<small>0.5 (Preview)</small>
+
+> Turn your GitHub into a No-SQL database
+
+- Simple and lightweight
+- Easy, manageable and accessible
+- Uses GitHub API
+- Always free
+
+[Website](https://clorabase.netlify.app)
+[Get Started](#clorabase)
+

docs/button.png

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Clorabase documentation</title>
+  <link rel="icon" href="favicon.png" />
+  <meta name="keywords" content="clorabase, android backend, firebase alternative, clorastoreDB, github as backend, supabase alternative, nosql database, mongoDB alternative, firestore alternative"/>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Clorabase is a free % open source backend (BaaS) alternative for Android/Java apps. Turn your GitHub repo into a NoSQL database and cloud storage for your app. Use database, storage, in-app messages, in-app updates and lot more">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'Clorabase',
+      repo: 'https://github.com/Clorabase/Clorabase',
+      coverpage: 'cover.md',
+      loadSidebar: 'toc.md'
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+</body>
+</html>

docs/cover.md

@@ -0,0 +1,155 @@
+# Clorabase Database
+
+Clorabase Database is an open-source, flexible, serverless database for Android & Java apps built on top of [ClorastoreDB](https://github.com/Clorabase/ClorastoreDB) that uses GitHub API to facilitate your online database. It has a dedicated SDK for Android apps written on top of a Java library. The SDK uses Google's Tasks API as a wrapper of a Java library, which helps you to write async code.  
+
+## Key features
+
+*   No extra account is needed
+*   Simple & easy SDK
+*   NO-SQL databases
+*   Can be managed using the console and Github web UI
+
+  
+
+## Usage / Examples
+
+This database is implemented from the [ClorastoreDB](https://github.com/Clorabase/ClorastoreDB) offline version. See its docs to understand the pattern of the database.  
+Refer to the [Wikipedia article](https://en.wikipedia.org/wiki/Document-oriented_database) to learn more about this.  
+  
+
+### Get the root collection of the database
+
+```java
+Clorabase clorabase = Clorabase.getInstance(GITHUB_USERNAME,GITHUB_TOKEN, PROJECT_NAME);
+Collection root = clorabase.getDatabase();
+```
+
+  
+To get your Oauth token, check the [Implementation](https://github.com/ErrorxCode/docs/edit/main/clorabase/README.md#implementation) part of the README  
+
+
+?> **In Android SDK:** Every method has its `async` version and `non-async` version. All the async methods end with `async` and return `async`. Implementation of the class.  
+?> **In the Java library:** There are only sync functions with the same name  
+
+### Writing/Updating data
+
+Let's insert a new user into `users` collection :
+
+```java
+Map data = new HashMap<>();
+data.put("name","John");
+data.put("age",25);
+data.put("is_married",false);
+
+root.collection("users").documentAsync("user1").setDataAsync(data)
+        .addOnSuccessListener(unused -> System.out.println("Success"))
+        .addOnFailureListener(e -> System.out.println("Failed"));          
+```
+
+  
+If the `user1` document already exists in that collection, **then it will update its fields.**  
+  
+?> **Tip**  
+\>Every database operation method returns a `Task` . See tasks [documentation](https://developers.google.com/android/guides/tasks) for more info.  
+  
+The structure created will be like this,  
+  
+![image](https://user-images.githubusercontent.com/65817230/230773260-1a207a69-03e6-4c3a-9fca-d4f0bba305c3.png)  
+  
+  
+You can also have a collection inside a collection, but not a collection or document inside a document.  
+  
+
+### Reading data
+
+To read data from the database, use `getDataAsync()` method on the **document** where it was inserted.
+
+```java
+root.collection("users").documentAsync("user1").getDataAsync()
+        .addOnSuccessListener(System.out::println)
+        .addOnFailureListener(Throwable::printStackTrace);
+```
+
+  
+
+### Deleting data
+
+To delete a document or collection, go to its parent collection and call `delete()method. To delete a field in a node, just put its value to null`
+
+```java
+root.collection("users").deleteAsync("user1")
+        .addOnSuccessListener(System.out::println)
+        .addOnFailureListener(Throwable::printStackTrace);
+```
+
+  
+  
+
+### Querying data
+
+Querying data in **ClorastoreDB** is as easy as pie. You just have to pass a `Predicate as a condition for querying data. The database will include every document for which the Predicate` return true.  
+  
+Suppose if your structure is like this (\*JSON representation of collection & it's document, where `users is the collection and each user` object is it's document\*):
+
+```json
+{
+  "users": [
+    "user1": {
+      "name": "John",
+      "age": 30,
+      "is_married": false
+    },
+    "user2": {
+      "name": "Mary",
+      "age": 25,
+      "is_married": true
+    },
+    "user3": {
+      "name": "Mike",
+      "age": 27,
+      "is_married": false
+    }
+  ]
+}
+```
+
+  
+
+*   To get all the users whose age is greater than 18,
+
+```java
+root.collection("users").query().whereGreater("age",18)
+```
+
+  
+
+*   To get users whose name start's with 'a'
+
+```java
+db.collection("users").query().where(data -> data.get("name").toString().startsWith("a"));
+```
+
+  
+**Note**: You need to manually check for the `return value of data.get("age")` , as it could be null if some document does not contain that value.  
+
+*   To order data by a particular field (Ascending order)
+
+```jva
+root.collection("users").query().orderBy("age",20);
+```
+
+  
+  
+  
+_That's all that you need to know about the database._
+
+
+
+
+
+
+
+
+
+
+

docs/favicon.png

@@ -0,0 +1,76 @@
+# Managing project/app
+
+  
+The main feature of clorabase is that it turns your GitHub repo into an application database. Since all the data is stored within your repo contents, you can also manage it using the GitHub Web UI, just like you do for your other projects on GitHub. However, due to a custom protocol & specification that clorabase uses inside, you cannot do everything from the GitHub UI that you can do from the console app.  
+  
+
+## What things can you do using GitHub UI
+
+*   Upload a small file to storage
+*   Insert/Send an in-app message to the queue
+*   Create a versioned app update
+*   Delete database documents/collection
+*   Delete storage files
+*   Delete project
+*   Edit in-app messages/updates
+*   Edit or change project configurations
+
+  
+
+### Uploading a file into storage
+
+To upload a file to your project storage, you can directly go to the project storage directory and upload a file there.  
+The project storage directory can be found inside your project folder from the root of the "Clorabase-database" repo.  
+Eg. `foobar/storage/user1/photos` --> Upload a file here  
+  
+
+### Send in-app message
+
+To send an in-app message, just create/upload a JSON file that contains the message spec, with a random name, into the project's messaging directory, i.e `project/messages`  
+  
+**Example message.json:**  
+
+```json
+{
+  "title": "Demo title",
+  "message": "Demo message...",
+  "link": "https://errorxcode.github.io/clorabase",
+  "type": "simple"
+}
+```
+
+  
+**Note: All the fields are mandatory**  
+  
+
+### Create a versioned app
+
+All the updates related information is created and managed in the update directory of your project. In this directory, there are folders with the package name of your Android application, which then contain the information about the current version of the app.  
+  
+To add a versioned application to your project, just create a `versions.json` inside your app package folder, in the project's updates directory, i.e `project/updates/com.foo.bar`  
+  
+**Example versions.json:**  
+
+```json
+{
+  "code": 5,
+  "name": "4dgg",
+  "package": "clorabase.sample.app",
+  "downloadUrl": "https://google.com",
+  "downloadCount": 0,
+  "mode": "flexible",
+  "date": "12-09-2025"
+}
+```
+
+  
+  
+  
+
+### Deleting document/file/message or anything:
+
+Deleting is very easy; you just need to delete the respective files from the respective directory. For example, you can delete any document from the database, any message from the message queue or any files from the storage. _There's nothing much you have to take care of while deleting_  
+  
+  
+
+> _That's all, Thank you for paying attention to the docs :)_