~qaul/community

2

Documentation feedback: technical intro

Details
Message ID
<871rs32ri4.fsf@kookie.space>
DKIM signature
missing
Download raw message
Hey,

I rewrote the technical documentation intro to be more up-to-date and
understandable.  I'd really appreciate some feedback on how it reads, if
there's any explanations missing or if some parts are badly structured.
Thanks!

~ spacekookie

---
# Technical Documentation

Welcome to the qaul.net technical documentation!

This section is aimed at two different types of people:

1. People wanting to contribute to qaul.net and it's libraries
2. People wanting to write their own apps for a qaul network

This page will offer a short introduction to the project structure to
get you started.  On each section in this document there are pages and
chapters that go into more detail than is required here.


## Introduction

Fundamentally, qaul.net is a highly distributed system.  As such, it
is not accountable to a single set of rules across all devices that
are part of this system.  It is important to make the distinction
between "qaul.net", the application, "qaul network", the distributed
network of devices, and other components provided by the project that
can be used to write decentralised applications.

The primary component in this ecosystem is called libqaul.  It
provides an abstraction layer for a distributed network of devices,
the users that interact with each other and the messages and data that
can be exchanged.  The API of this library is called the "service API"
in other parts of the docs.

Built on top of it are services (or apps), that provide more specific
functionality, such as text messaging or file sharing.  qaul.net (the
app) is merely a GUI and collection of a few different services all
running on the same libqaul instance on one device.


## Layers

The following sections will outline the different layers present in
qaul.net (the application), then there are pages for more details on
how to interact with each of these layers.


### libqaul: services & apps

As mentioned in the introduction it is possible to build applications
(or "services") with libqaul, that can interact with each other on a
distributed network.  These services provide high level functionality
such as sending text messages, a collaborative public feed (similar to
mastodon), and voice calls.

Following is a list of all the services that come bundled in qaul.net
by default (with links to sub pages for details).

- [feed]()
- [messages]()
- [files]()
- [voices]()
- [radio]()

The reason why qaul.net is built in such a modular way is to allow you
to write your own services, with their own functionality and UI, that
gets to interact with an existing service and user ecosystem.  libqaul
also helps you to build your application in a way where it doesn't
rely on central servers on a network and keeping your users' data
safe.


### libqaul: service API

The interface to libqaul is called the service API, and a versatile
abstraction over a decentralised network.  It handles local user
authentication, network user discovery, binary payload messages,
contact data, and even encrypted file storage at rest.

The API itself is available as an async Rust library and ffi C
interface, with some optional IPC add-ons:

- [http/json:api]() - this is how the qaul.net GUI is hooked up
- [socket-ipc]() - using a capt'n proto ipc protocol over unix sockets
- [android-ipc]() - implementing an Android specific ipc interface

The idea behind the variety of IPC interfaces is that your application
can bundle it's own copy of libqaul, to provide the network backends
required to join a mesh network, however it can also connect with a
running instance if one is available.  This way resources can be
shared.


### libqaul: internals

The internals of libqaul are intirely written in Rust, and hook into
various storage and networking abstractions.  libqaul primarily uses
two libraries, also written as part of this project, to do it's job:
alexandria, and ratman.
hellekin
Details
Message ID
<1B1B2291-3491-4311-82E6-0EA58F5FD6EA@zoethical.com>
In-Reply-To
<871rs32ri4.fsf@kookie.space> (view parent)
DKIM signature
missing
Download raw message
Hi there, the documentation reads fine, except for a couple of "it's" that should be "it's". I would expect links to the relevant code or specific library documentation, and maybe some code snippets to give an idea of the style and "get started" examples. Would you add a section mentioning how to contribute? (E g., with links to issues tagged for "good first contribution")

Cheers

==
hk


-------- Original Message --------
From: Katharina Fey <kookie@spacekookie.de>
Sent: January 13, 2020 6:30:43 PM GMT+01:00
To: ~qaul/community@lists.sr.ht
Cc: Amanjeev Sethi <aj@amanjeev.com>, Mathias Jud <jud@wachter-jud.net>
Subject: Documentation feedback: technical intro

Hey,

I rewrote the technical documentation intro to be more up-to-date and
understandable.  I'd really appreciate some feedback on how it reads, if
there's any explanations missing or if some parts are badly structured.
Thanks!

~ spacekookie

---
# Technical Documentation

Welcome to the qaul.net technical documentation!

This section is aimed at two different types of people:

1. People wanting to contribute to qaul.net and it's libraries
2. People wanting to write their own apps for a qaul network

This page will offer a short introduction to the project structure to
get you started.  On each section in this document there are pages and
chapters that go into more detail than is required here.


## Introduction

Fundamentally, qaul.net is a highly distributed system.  As such, it
is not accountable to a single set of rules across all devices that
are part of this system.  It is important to make the distinction
between "qaul.net", the application, "qaul network", the distributed
network of devices, and other components provided by the project that
can be used to write decentralised applications.

The primary component in this ecosystem is called libqaul.  It
provides an abstraction layer for a distributed network of devices,
the users that interact with each other and the messages and data that
can be exchanged.  The API of this library is called the "service API"
in other parts of the docs.

Built on top of it are services (or apps), that provide more specific
functionality, such as text messaging or file sharing.  qaul.net (the
app) is merely a GUI and collection of a few different services all
running on the same libqaul instance on one device.


## Layers

The following sections will outline the different layers present in
qaul.net (the application), then there are pages for more details on
how to interact with each of these layers.


### libqaul: services & apps

As mentioned in the introduction it is possible to build applications
(or "services") with libqaul, that can interact with each other on a
distributed network.  These services provide high level functionality
such as sending text messages, a collaborative public feed (similar to
mastodon), and voice calls.

Following is a list of all the services that come bundled in qaul.net
by default (with links to sub pages for details).

- [feed]()
- [messages]()
- [files]()
- [voices]()
- [radio]()

The reason why qaul.net is built in such a modular way is to allow you
to write your own services, with their own functionality and UI, that
gets to interact with an existing service and user ecosystem.  libqaul
also helps you to build your application in a way where it doesn't
rely on central servers on a network and keeping your users' data
safe.


### libqaul: service API

The interface to libqaul is called the service API, and a versatile
abstraction over a decentralised network.  It handles local user
authentication, network user discovery, binary payload messages,
contact data, and even encrypted file storage at rest.

The API itself is available as an async Rust library and ffi C
interface, with some optional IPC add-ons:

- [http/json:api]() - this is how the qaul.net GUI is hooked up
- [socket-ipc]() - using a capt'n proto ipc protocol over unix sockets
- [android-ipc]() - implementing an Android specific ipc interface

The idea behind the variety of IPC interfaces is that your application
can bundle it's own copy of libqaul, to provide the network backends
required to join a mesh network, however it can also connect with a
running instance if one is available.  This way resources can be
shared.


### libqaul: internals

The internals of libqaul are intirely written in Rust, and hook into
various storage and networking abstractions.  libqaul primarily uses
two libraries, also written as part of this project, to do it's job:
alexandria, and ratman.


-- 
p.s.:  <https://ps.zoethical.com>
Hybrid, fragile aesthetics
Collective practices & free software
hellekin
Details
Message ID
<88F2B7D6-1065-4601-B5A8-5AA40B15E99F@zoethical.com>
In-Reply-To
<871rs32ri4.fsf@kookie.space> (view parent)
DKIM signature
missing
Download raw message
s/intirely/entirely/


-------- Original Message --------
From: Katharina Fey <kookie@spacekookie.de>
Sent: January 13, 2020 6:30:43 PM GMT+01:00
To: ~qaul/community@lists.sr.ht
Cc: Amanjeev Sethi <aj@amanjeev.com>, Mathias Jud <jud@wachter-jud.net>
Subject: Documentation feedback: technical intro

Hey,

I rewrote the technical documentation intro to be more up-to-date and
understandable.  I'd really appreciate some feedback on how it reads, if
there's any explanations missing or if some parts are badly structured.
Thanks!

~ spacekookie

---
# Technical Documentation

Welcome to the qaul.net technical documentation!

This section is aimed at two different types of people:

1. People wanting to contribute to qaul.net and it's libraries
2. People wanting to write their own apps for a qaul network

This page will offer a short introduction to the project structure to
get you started.  On each section in this document there are pages and
chapters that go into more detail than is required here.


## Introduction

Fundamentally, qaul.net is a highly distributed system.  As such, it
is not accountable to a single set of rules across all devices that
are part of this system.  It is important to make the distinction
between "qaul.net", the application, "qaul network", the distributed
network of devices, and other components provided by the project that
can be used to write decentralised applications.

The primary component in this ecosystem is called libqaul.  It
provides an abstraction layer for a distributed network of devices,
the users that interact with each other and the messages and data that
can be exchanged.  The API of this library is called the "service API"
in other parts of the docs.

Built on top of it are services (or apps), that provide more specific
functionality, such as text messaging or file sharing.  qaul.net (the
app) is merely a GUI and collection of a few different services all
running on the same libqaul instance on one device.


## Layers

The following sections will outline the different layers present in
qaul.net (the application), then there are pages for more details on
how to interact with each of these layers.


### libqaul: services & apps

As mentioned in the introduction it is possible to build applications
(or "services") with libqaul, that can interact with each other on a
distributed network.  These services provide high level functionality
such as sending text messages, a collaborative public feed (similar to
mastodon), and voice calls.

Following is a list of all the services that come bundled in qaul.net
by default (with links to sub pages for details).

- [feed]()
- [messages]()
- [files]()
- [voices]()
- [radio]()

The reason why qaul.net is built in such a modular way is to allow you
to write your own services, with their own functionality and UI, that
gets to interact with an existing service and user ecosystem.  libqaul
also helps you to build your application in a way where it doesn't
rely on central servers on a network and keeping your users' data
safe.


### libqaul: service API

The interface to libqaul is called the service API, and a versatile
abstraction over a decentralised network.  It handles local user
authentication, network user discovery, binary payload messages,
contact data, and even encrypted file storage at rest.

The API itself is available as an async Rust library and ffi C
interface, with some optional IPC add-ons:

- [http/json:api]() - this is how the qaul.net GUI is hooked up
- [socket-ipc]() - using a capt'n proto ipc protocol over unix sockets
- [android-ipc]() - implementing an Android specific ipc interface

The idea behind the variety of IPC interfaces is that your application
can bundle it's own copy of libqaul, to provide the network backends
required to join a mesh network, however it can also connect with a
running instance if one is available.  This way resources can be
shared.


### libqaul: internals

The internals of libqaul are intirely written in Rust, and hook into
various storage and networking abstractions.  libqaul primarily uses
two libraries, also written as part of this project, to do it's job:
alexandria, and ratman.


-- 
p.s.:  <https://ps.zoethical.com>
Hybrid, fragile aesthetics
Collective practices & free software