Welcome to the qaul.net technical documentation!
This section is aimed at two different types of people:
- People wanting to contribute to
qaul.netand it's libraries
- People wanting to write network services using
This page will offer a short introduction to the structure of the ecosystem which should be relevant to both groups 😉
qaul.net is a distributed system. As such, it deals
with a lot of moving parts, spread over a network and not accountable
to a single set of rules. The core component of
libqaul, is a library that aims to make the creation of distributed
systems, functioning independent of fixed infrastructure or internet
backbones, as easy as possible.
It is what
qaul.net, and the core services it provides, is built
on. In a lot of the design documents, the term
node is used. Being a
distributed system, one might think that the term refers to a computer
or device on the network. This is a false assumption.
node in the sense of
qaul.net is a user, i.e. an entity on the
network with a cryptographic identity. This is because multiple users
could be operating on the network via the same physical hardware,
which should not be exposed to anyone outside of this hardware.
When referring to a physical machine we will use the term "device"!
libqaul provides a "Service API", which exposes core components of
an application workflow, giving developers a glimpse into a wider
network of devices. An external program (called a "service") might use
send_message function provided by
libqaul to implement group
chats or announcement channels.
qaul.net (the app you install) comes
with four services by default:
prefs. Each of them is, in the sense of
libqaul, an external
application, that happens to get access to some internal state.
Anything these services do, you can do in your own application!
The "low level" service API consists of the following basic capabilities:
- Creating users, logging in, verifying existing tokens
- Managing a user's contact book (adding, deleting, setting trust levels)
- Read information about the local keystore (what keys are available)
- Sending messages to one, multiple or all users on a network
- Managing local files, stored, captured and downloaded by
- Get the current network state and configure network backends
- Send an interrupt with payload to another local service
libqaul, simple bundle it with your application and write
your app against it's API.
If a user is installing your app on a system that already has some
libqaul-enabled application running on it (say
qaul.net, it is
possible for it to connect to the existing instance, sharing it's
networking and user concepts. In this case, your service can even send
messages to other services, to use their functionality.
The following graphic demonstrates the concept.
Note: In this (qaul.net internal) setup the
"core" service is
special. It acts more like an API shim than an actual
service and simply exposes the
libqaul service API as an
HTTP interface that is easier for the qaul.net UI to
The insides of
libqaul consist of a few smaller (and larger)
libraries. When we consider their design, we assign them "layers" for
|Routing Layer||Handles network abstractions, frame routing and provides an API to interact with incoming messages|
|Service Layer||Provides persistent storage for users, services, cryptographic identities, trust and management functions|
|API Layer||A few very slim API-shims that either map to HTTP or platform native IPC mechanisms (i.e. Android intents or UNIX sockets)|
|Application Layer||An extenal network service which utilises the service API to provide different features to an application|
|Graphics layer||Displaying it all to a user, probably the entry-point to the end-user application|
As the author of a network service utilising
libqaul you don't need
to understand all that much about it's internal design. If you are
interested in contributing to it, check the