New Structure for docs directory and some Content

.gitignore

@@ -18,3 +18,4 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+

docs/guides/collections.md

@@ -0,0 +1,87 @@
+---
+title: collections
+id: collections
+---
+
+## What is a Collection
+An collection is a set of feeds that are shared among peers.
+A feed is an append-only log of records. Each feed is only writable from a single device.
+A record is a unit of data. Each record has a type, a ref and a value.
+
+When sonar is started a local collection is available by default.
+
+Collections are assigned to a workspace. You can learn how to create a workspace in the workspace guide..
+
+
+## add or open collection
+
+To add a new collection to the workspace we simply call the ```createCollection()``` function to open it we use ```openCollection()``` as for example in this code snippet:
+
+
+```js
+/**
+ * Check if the collection already exists if not create a new collection
+ * @returns opened || new collection
+ */
+export async function Collection(): Promise<Collection> {
+  if (!collection) {
+    try {
+      collection = await workspace.openCollection(collectionName)
+    } catch (err: any) {
+      collection = await workspace.createCollection(collectionName)
+    }
+    //  console.log('opened collection', collection.key.toString('hex'))
+    await ensureSchema(collection, schema)
+  }
+  return collection
+}
+```
+
+## delete a collection
+Currently it is not possible to delete a collection, maybe we will enable this in the future.
+
+## list collections and get further informations
+
+
+To list the collections in a workspace and get more information about them you can use the following functions:
+
+``` js
+await workspace.listCollections
+collection.key
+collection.info
+```
+
+### getters
+
+Various getters are available to retrieve the parameters of the collection:
+
+
+```js
+  get name () {
+    if (this._info) return this._info.name
+    return this._nameOrKey
+  }
+  get key () {
+    return this._info && this._info.key
+  }
+  get localKey () {
+    return this._info && this._info.localKey
+  }
+  get info () {
+    return this._info
+  }
+  get id () {
+    return this._info && this._info.id
+  }
+  get length () {
+    return this._length || this._info.length || 0
+  }
+```
+
+## update a collection
+
+To update a collection configuration you can use ```updateCollection(name, info)```
+
+## more about collections
+
+Collections manage our feeds these can have different forms on the one hand you can add simple files to the collections so called `file records` on the other hand you can also manage your databases in a collection with the so called `record scheme`. Furthermore you can share your feeds with others or replicate them, more about this in the corresponding guides.

docs/guides/feeds.md

@@ -0,0 +1,11 @@
+---
+title: feeds
+id: feeds
+---
+
+Sonar uses feeds within the collections to manage the records.
+
+``` js
+// Collection: Feeds
+await collection.putFeed()
+```

docs/guides/fileRecord.md

@@ -0,0 +1,15 @@
+---
+title: file records
+id: fileRecord
+---
+
+To manage files in collections and their feeds there is a predefined scheme and some helper methods which allow us to access or create them in an easy way. 
+
+``` js
+await collection.fs.readFile(refOrPath)
+await collection.fs.createFile(refOrPath)
+await collection.fs.updateFile(refOrPath)
+await collection.fs.getFileMetadata(refOrPath)
+```
+
+Currently it is not possible to delete a records for real. When a record is deleted, it receives a tombstone to show other peers that it is no longer available.

docs/guides/runServer.md

@@ -0,0 +1,67 @@
+---
+title: running a server
+id: runServer
+---
+
+The usual setup is that you run sonar-server on localhost and then interact with Sonar through the client, the UI running on http://localhost:9191 or the CLI. The CLI can be invoked with ./sonar from the root of this repository, and is also used to start the server.
+
+## Installation
+
+```bash
+npm install -g @arsonar/server
+sonar help
+sonar start
+```
+
+## Development
+
+> Note: At the moment [yarn 1](https://classic.yarnpkg.com/) is recommended, please [install it according to the instructions](https://classic.yarnpkg.com/en/docs/install#debian-stable).
+
+```bash
+# clone the sonar repository
+git clone https://github.com/arso-project/sonar.git
+cd sonar
+# install dependencies of all workspaces
+yarn
+# (re)build the user interface and docs
+yarn run rebuild
+# when developing on something that uses the ESM version of the
+# `@arsonar/client` library: watch and rebuild on changes.
+yarn dev:client
+```
+
+You can start sonar with `./sonar` from the repository root.
+
+If the start fails with errors related to `sonar-tantivy`, try to redownload or rebuild sonar-tantivy (the search engine included in sonar):
+
+```
+yarn run build:sonar-tantivy
+```
+
+If the start fails with errors related to `client`, try to rebuild client :
+
+```
+yarn run build:client
+```
+
+```bash
+# start the sonar server
+./sonar start
+
+# start the sonar server in dev mode
+./sonar start --dev
+
+```
+
+## Running the examples
+
+This repo includes a few examples. To run them locally, do the following:
+
+```bash
+# build the client library
+yarn build:client
+# start sonar
+./sonar start --disable-authentication --dev
+# run the example from the examples/ folder
+yarn example react
+```

docs/guides/schemaRecord.md

@@ -0,0 +1,61 @@
+---
+title: schema records
+id: schemaRecord
+---
+Since we understand sonar as a p2p database you can freely define a schema in which you can store your information.
+the schema has at least one fixed parameters  ``` js  type: string \\One of the Sonar field types  ```
+
+A typical scheme looks like this and more can be found at https://sonar.dev.arso.xyz/docs/api-schema:
+
+``` JSON
+const spec = {
+  title: 'Notes',
+  fields: {
+    title: {
+      type: 'string',
+      title: 'Title',
+      index: {
+        search: { title: true }
+      }
+    },
+    body: {
+      type: 'text'
+      title: 'Body',
+      index: {
+        // This could also be the default by field type
+        search: { bodytext: true }
+      }
+    },
+    date: {
+      type: 'date',
+      title: 'Date',
+      index: {
+        basic: true,
+        search: { facet: true }
+      }
+    },
+    tags: {
+      type: 'string',
+      multiple: true,
+      title: 'Tags',
+      index: {
+        basic: true,
+        search: { facet: true }
+      }
+    },
+    author: {
+      type: 'relation',
+      title: 'Author'
+    }
+
+  }
+}
+```
+
+## add new schema
+
+To add a new schema to a collection you need the function:
+
+``` js
+await collection.putType(schema)
+```

docs/guides/search.md

@@ -0,0 +1,20 @@
+---
+title: searching
+id: search
+---
+
+To search the records of a collection we can issue a query which returns an array with the matching records.
+
+```js
+await collection.query(name, args, opts)
+```
+
+The arguments for the query. Depends on the query being used. For records: `{ schema, name, id }` For history: `{ from: timestamp, to: timestamp }` For search: Either a "string" for a simple full-text search, or a tantivy query object. For indexes: `{ schema, prop, value, from, to, reverse, limit }` (to be documented) For relations: `{ subject, object, predicate }` where subject and object are ids and predicate is type #field
+
+Here is a small example from our peerBooks App which will return the records for the schema Book:
+
+```js
+  const records = await collection.query('records', {
+    type: 'sonar-peerBooks/Book'
+  })
+```

docs/guides/sharing.md

@@ -0,0 +1,19 @@
+---
+title: sharing
+id: sharing
+---
+With the function ```putFeeds()``` you can add feeds from other collections, which allows you to share them.
+
+``` js
+// Collection: Feeds
+await collection.putFeed()
+```
+
+If you know the key of a collection you can add it by using the subscribe mechanism.
+
+This will fetch all records from the first to the last and then waits for new records. Currently only intended for usage in bots (not in short-running Browser clients).
+
+``` js
+// Collection: Subscriptions
+await collection.subscribe(name, opts, callback)
+```

docs/guides/workspace.md

@@ -0,0 +1,36 @@
+---
+title: workspaces
+id: workspace
+---
+If you start Sonar it comes with a Default Workspace 
+
+When you start Sonar it provides a default workspace. Workspaces are our endpoints in which collections can be managed, more about this under the point Collections.
+
+There can be multiple workspaces on one Sonar server but in alpha state you should use only the default workspace.
+
+To use the workspace it must be added to the project:
+
+```npm install @arso-project/sonar-client```
+
+Afterwards this can be impoted and created via the constructor:
+
+```js
+import { Workspace } from "@arsonar/client";
+/**
+ * Get the URL and access token for 
+ * the Sonar instance running in the background. 
+ */
+const url = process.env.SONAR_URL || 'http://localhost:9191/api/v1/default'
+const token = process.env.SONAR_TOKEN
+/**
+ * Initializing a client 
+ */
+export const workspace = new Workspace({
+  url,
+  accessCode: token
+});
+```
+
+Now you can create, update, open and display collections on the workspace. Furthermore the workspace offers the possibility to manage the login of the client. More about the workspace can be found in the API description: [Workspace](https://sonar-apidocs.dev.arso.xyz/Workspace.html)
+
+How to create collections and so on you can find in the collection guide.

sidebars.js

@@ -3,19 +3,29 @@ module.exports = {
     'Getting started': [
       'intro-start'
     ],
+    Guides: [
+      'guides/runServer',
+      'guides/workspace',
+      'guides/collections',
+      'guides/feeds',
+      'guides/fileRecord',
+      'guides/schemaRecord',
+      'guides/sharing',
+      'guides/search'
+    ],
     Architecture: [
-      'hyperstack',
-      'kappa',
-      'tantivy',
-      'architecture-sonar'
+      'architecture/hyperstack',
+      'architecture/kappa',
+      'architecture/tantivy',
+      'architecture/architecture-sonar'
     ],
     'API docs': [
-      'apidocs-client'
+      'apiDocs/apidocs-client'
     ],
     API: [
-      'api-client',
-      'api-schema',
-      'api-glossary'
+      'api/api-client',
+      'api/api-schema',
+      'api/api-glossary'
     ]
   }
 }