# Technical Documentation

This is an introductory chapter into the technical layers of qaul!
It is aimed at two different types of people:

1. People wanting to contribute to the qaul core
2. People wanting to write apps for a qaul network

Before getting started, we need to cover a few basics in project
structure.  Each section in this document has it's own sub-chapter
that will go into more details.


## Introduction

Fundamentally, qaul is a highly distributed system.  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", 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,
user profiles that interact with each other, and the messages and data
that are exchanged.  The API of this library is called the "libqaul
service API" in other parts of the docs.  An application written to
use `libqaul` is called a "service".

A service provicdes more specific functionality.  Not all services are
user-facing.  For example, a service can provide an easy interface to
send rich-payload messages, that operates on a higher level than the
libqaul service API.  Other services can then depend on this
high-level API.

qaul (the app bundle) is primarily a GUI for a collection of
services, that all run on the same libqaul instance under the hood.

Unless otherwise stated, all code is written in Rust.


## Layers

The qaul stack is heavily abstracted into layers to keep logic
simple on each layer.  No layer should have to care about data that is
not meant to be consumed by it.

- **User Interfaces**: users interact with these clients
- **RPC broker**: allows remote clients to connect to the same daemon,
  without having to bundle their own libraries.
- **App services**: a set of services that provide user-facing
  functionality (text messaging, file sharing, ...)
- **Core services**: utility services that extend the `libqaul` API
- **libqaul**: primary user profile, and database handler
- **ratman**: decentralised packet router, responsible for dispatching
  and receiving messages.
- **Network Modules**: driver plugins for `ratman` that implement the
  actual wire-formats for networking
- **Platform Support**: os-specific utilities and tools


### Services & apps

A service (app) provides it's own API to clients, either via native
bindings, or via the common rpc-broker system.  Following is a list of
all the services that come bundled in qaul by default (more
details [here][services]).

- feed
- messages
- files
- voices
- radio

[services]: ./qaul/services.html

When connecting your own apps to a `libqaul` instance you can check
for the existence of other services, meaning that your application can
rely on extrenal functionality.  This way the binary bundles can be
kept small and focussed.


### RPC broker

To allow external applications to integrate with an existing qaul/
`libqaul` stack, the RPC message broker provides various interfaces to
integrate with.

- **[http/json]** - http server for `libqaul` and associated services
- **[socket-ipc]** - unix ipc socket interface with binary payloads
- **[android-ipc]** - a specific ipc implementation for Android

[http/json:api]: https://docs.qaul.org/http-api/
[socket-ipc]: ./libqaul/ipc/socket.html
[android-ipc]: ./libqaul/ipc/android.html


### libqaul

The primary state handler is called `libqaul`.  It handles database
transactions, local and remote user profiles, and connections to the
router.  Services can register themselves with a running instance for
authentication, to gain access to a per-service encrypted backing
storage.

While the main API is written (and accessible) in Rust, most services
will likely use the RPC broker system built on top of `libqaul`.


### ratman

A decentralised packet router, modelled partially on BATMAN-adv.  It
provides an API that takes messages to send to peers on the network,
and returns messages received from the network.  It handles network
announcements, network segmentation, message journaling, route
updates, and networked archive storage.  It's the main driver behind
qaul, and flexible enough to embed into various other use-cases.

Addresses on a ratman network are 32-byte ed25516 public keys, meaning
that all messages are automatically encrypted.  Additionally this
means that the valid address space isn't modelled on IP addresses, or
similar, and is nearly un-exhaustable.


### Network Modules

When sending messages over an internet overlay network, translation
between ratman IDs (provided by the `ratman-identity` crate) and the
various IP spaces needs to be performed.  This logic is implemented in
the network driver plugins (called "netmods").
