Extended development documentation.

docs/developer-guide.md

@@ -6,12 +6,14 @@ This page gives insights on extending Aura Engine internals or through the API.
 
 - [Aura Engine Development Guide](#aura-engine-development-guide)
     - [Architecture](#architecture)
-    - [Required Data Sources](#required-data-sources)
-    - [Provided API Endpoints](#provided-api-endpoints)
-    - [Components](#components)
-    - [Running the Engine](#running-the-engine)
-    - [Default ports used by Engine](#default-ports-used-by-engine)
-    - [Debugging Liquidsoap](#debugging-liquidsoap)
+        - [Components](#components)
+    - [API](#api)
+        - [Required Data Sources](#required-data-sources)
+        - [Provided API Endpoints](#provided-api-endpoints)
+    - [Web Applications using the Engine API](#web-applications-using-the-engine-api)
+    - [More infos for debugging](#more-infos-for-debugging)
+        - [Default ports used by Engine](#default-ports-used-by-engine)
+        - [Debugging Liquidsoap](#debugging-liquidsoap)
     - [Read more](#read-more)
 
 <!-- /TOC -->
@@ -23,7 +25,18 @@ based on a REST API. All external information is retrieved using JSON data-struc
 
 To get the basic architectural overview, visit the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
 
-## Required Data Sources
+### Components
+
+
+**engine-core.py**: It is the server which is connected to the external programme source (e.g. aura steering and tank), to liquidsoap and is listening for redis pubsub messages. This precious little server is telling liquidsoap what to play and when.
+
+**Liquidsoap**: The heart of AuRa Engine. It uses the built in mixer, to switch between different sources. It records everything and streams everything depending on your settings in aura.ini.
+
+**engine-api.py**: A Flask web server which provides the API endpoints. This component can be (re-) started independently from the core engine.
+
+## API
+
+### Required Data Sources
 
 The AURA Project "**Dashboard**" provides the GUI to organize shows, schedules/timelsots
 and organize uploads in form of playlists. Those playlists can be organized in timeslots
@@ -47,7 +60,7 @@ to be played and its meta-data:
 More information you can find here: <https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md>
 
 
-## Provided API Endpoints
+### Provided API Endpoints
 
 **Soundserverstate:** Returns true and false values of the internal In- and Outputs  
 
@@ -59,32 +72,25 @@ More information you can find here: <https://gitlab.servus.at/autoradio/meta/blo
 /api/v1/trackservice/
 
 
-## Components
-
-
-**aura.py**: It is the server which is connected to the external programme source (e.g. aura steering and tank), to liquidsoap and is listening for redis pubsub messages. This precious little server is telling liquidsoap what to play and when.
-
-**Guru**: The commandline tool for interacting with the server. Also provides the communication from Liquidsoap to the Python (Command-)Server.
-
-**Liquidsoap**: The heart of AuRa Engine. It uses the built in mixer, to switch between different sources. It records everything and streams everything depending on your settings in aura.ini.
-
-
-## Running the Engine
-
-Aura Engine is consisting of two components: The Python Engine and Liquidsoap Core.
+## Web Applications using the Engine API
 
-It's important to start both components in the correct order:
+Under `./contrib` you'll find two Web Applications which utilize the Engine API:
 
-    1. Run the Python engine
+- [Track Service](contrib/aura-player/README.md)
+- [Studio Clock](contrib/aura-clock/README.md)
 
-    ./run.sh
+When you start the engine-api using
 
-    2. Run the Liquidsoap core
+```shell
+    ./run.sh api-dev
+```
 
-    ./run.sh lqs
+this automatically builds these web applications and copies the resulting assets to the
+relevant `./web/**` folders.
 
+## More infos for debugging
 
-## Default ports used by Engine
+### Default ports used by Engine
 
 Aura Engine requires a number of ports for internal and external communication.
 
@@ -95,7 +101,7 @@ Those are the default port numbers:
 * `5000` ... Svelte development mode; dynamically uses some other port if occupied
 
 
-## Debugging Liquidsoap
+### Debugging Liquidsoap
 
 Connect to Liquidsoap via Telnet
 

docs/installation-development.md

@@ -105,17 +105,17 @@ This includes the Liquidsoap audio engine, but does not start the API server.
 
 **Run the Engine Core and Liquidsoap separately**
 
-This requires to start the Liquidsoap component within some other terminal. This is helpful for
-debugging purposes.
+When developing and debugging engine it is helpful to start the core and the Liquidsoap
+component separately. In such case it is important to start both in the correct order.
+
+First start the core of the engine:
 
 ```shell
     ./run.sh core
 ```
 
-**Run Liquidsoap only**
-
-This requires to start the core component in another terminal. This is helpful for
-debugging purposes.
+When engine-core completed its boot phase, indicated by a log that it is waiting for 
+Liquidsoap, you can run following:
 
 ```shell
     ./run.sh lqs  
@@ -126,7 +126,7 @@ debugging purposes.
 This requires to start the core component in another terminal.
 
 ```shell
-    ./run.sh api
+    ./run.sh api-dev
 ```
 
 In development mode Engine uses the default [Flask](https://palletsprojects.com/p/flask/) web server.