-the OSL database tables. The server process communicates with the
-AFS process via pipes and shared memory. Usually, the AFS process
-awakes only briefly whenever the current audio file changes. The AFS
-process determines the next audio file, opens it, verifies it has
-not been changed since it was added to the database and passes the
-open file descriptor to the server process, along with audio file
-meta-data such as file name, duration, audio format and so on. The
-server process then starts to stream the audio file.
-
-The AFS process also accepts connections from local clients via
-a well-known socket. However, only child processes of para_server
-may connect through this socket. All server commands that have the
-AFS_READ or AFS_WRITE permission bits use this mechanism to query or
-change the database.
+the database tables. The AFS process accepts incoming connections
+which arrive either on a pipe which is shared with para_server,
+or on the local socket it is listening on. The setup is as follows.
+
+ .___________________. .______________.
+ | | | |
+ | virtual streaming | | audio format |
+ | system | | handler |
+ |_________ _______| |_____ ______|
+ \ / \ /
+ | |
+ .-'""""`-. | | .-'""""`-.
+ ( ) | | ( )
+ |`-.____.-'| .__/ \________________/ \___. |`-.____.-'|
+ | | | | | |
+ | file |----| AFS (audio file selector) |----| OSL |
+ | system | | process | | database |
+ | | |___________________________| | |
+ |. ' "" ` .| | |. ' "" ` .|
+ | | | | |
+ `-.____.-' | `-.____.-'
+ ._______/ \_______.
+ | |
+ | command handler |
+ |_______ _______|
+ \ /
+ |
+ |
+ |
+ ._____/ \_____.
+ | |
+ | para_client |
+ |_____________|
+
+The virtual streaming system, which is part of the server process,
+communicates with the AFS process via pipes and shared memory. When
+the current audio file changes, it sends a notification through the
+shared pipe. The AFS process queries the database to determine the
+next audio file, opens it, verifies that it has not been changed since
+it was added to the database and passes the open file descriptor back
+to the virtual streaming system, along with audio file meta-data such
+as file name, duration, audio format and so on. The virtual streaming
+system then starts to stream the file.
+
+The command handlers of all AFS server commands use the local socket
+to query or update the database. For example, the command handler of
+the add command sends the path of an audio file to the local socket.
+The AFS process opens the file and tries to find an audio format
+handler which recognizes the file. If all goes well, a new database
+entry with metadata obtained from the audio format handler is added
+to the database.
+
+Note that AFS employs
+[libosl](http://people.tuebingen.mpg.de/maan/osl/), the object
+storage layer library, as the database backend. This library offers
+functionality similar to a relational database, but is much more
+lightweight than a full featured database management system.