From 519fdb9326c7d6748f622a2a1853193eaa886b98 Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Mon, 29 Oct 2012 01:09:36 +0100
Subject: [PATCH] Update concepts description and graphs

---
 docs/api/concepts.rst  | 117 ++++++++++++++++++++++++++++++++---------
 docs/api/frontends.rst |   2 +
 2 files changed, 95 insertions(+), 24 deletions(-)

diff --git a/docs/api/concepts.rst b/docs/api/concepts.rst
index ae959237..5eca2349 100644
--- a/docs/api/concepts.rst
+++ b/docs/api/concepts.rst
@@ -1,29 +1,98 @@
 .. _concepts:
 
-**********************************************
-The backend, controller, and provider concepts
-**********************************************
+*************************
+Architecture and concepts
+*************************
 
-Backend:
-    The backend is mostly for convenience. It is a container that holds
-    references to all the controllers.
-Controllers:
-    Each controller has responsibility for a given part of the backend
-    functionality. Most, but not all, controllers delegates some work to one or
-    more providers. The controllers are responsible for choosing the right
-    provider for any given task based upon i.e. the track's URI. See
-    :ref:`core-api` for more details.
-Providers:
-    Anything specific to i.e. Spotify integration or local storage is contained
-    in the providers. To integrate with new music sources, you just add new
-    providers. See :ref:`backend-api` for more details.
+The overall architecture of Mopidy is organized around multiple frontends and
+backends. The frontends use the core API. The core actor makes multiple backends
+work as one. The backends connect to various music sources. Both the core actor
+and the backends use the audio actor to play audio and control audio volume.
 
-.. digraph:: backend_relations
+.. digraph:: overall_architecture
 
-    Backend -> "Current\nplaylist\ncontroller"
-    Backend -> "Library\ncontroller"
-    "Library\ncontroller" -> "Library\nproviders"
-    Backend -> "Playback\ncontroller"
-    "Playback\ncontroller" -> "Playback\nproviders"
-    Backend -> "Stored\nplaylists\ncontroller"
-    "Stored\nplaylists\ncontroller" -> "Stored\nplaylist\nproviders"
+    "Multiple frontends" -> Core
+    Core -> "Multiple backends"
+    Core -> Audio
+    "Multiple backends" -> Audio
+
+
+Frontends
+=========
+
+Frontends expose Mopidy to the external world. They can implement servers for
+protocols like MPD and MPRIS, and they can be used to update other services
+when something happens in Mopidy, like the Last.fm scrobbler frontend does. See
+:ref:`frontend-api` for more details.
+
+.. digraph:: frontend_architecture
+
+    "MPD\nfrontend" -> Core
+    "MPRIS\nfrontend" -> Core
+    "Last.fm\nfrontend" -> Core
+
+
+Core
+====
+
+The core is organized as a set of controllers with responsiblity for separate
+sets of functionality.
+
+The core is the single actor that the frontends send their requests to. For
+every request from a frontend it calls out to one or more backends which does
+the real work, and when the backends respond, the core actor is responsible for
+combining the responses into a single response to the requesting frontend.
+
+The core actor also keeps track of the current playlist, since it doesn't
+belong to a specific backend.
+
+See :ref:`core-api` for more details.
+
+.. digraph:: core_architecture
+
+    Core -> "Current\nplaylist\ncontroller"
+    Core -> "Library\ncontroller"
+    Core -> "Playback\ncontroller"
+    Core -> "Stored\nplaylists\ncontroller"
+
+    "Library\ncontroller" -> "Local backend"
+    "Library\ncontroller" -> "Spotify backend"
+
+    "Playback\ncontroller" -> "Local backend"
+    "Playback\ncontroller" -> "Spotify backend"
+    "Playback\ncontroller" -> Audio
+
+    "Stored\nplaylists\ncontroller" -> "Local backend"
+    "Stored\nplaylists\ncontroller" -> "Spotify backend"
+
+Backends
+========
+
+The backends are organized as a set of providers with responsiblity forseparate
+sets of functionality, similar to the core actor.
+
+Anything specific to i.e. Spotify integration or local storage is contained in
+the backends. To integrate with new music sources, you just add a new backend.
+See :ref:`backend-api` for more details.
+
+.. digraph:: backend_architecture
+
+    "Local backend" -> "Local\nlibrary\nprovider" -> "Local disk"
+    "Local backend" -> "Local\nplayback\nprovider" -> "Local disk"
+    "Local backend" -> "Local\nstored\nplaylists\nprovider" -> "Local disk"
+    "Local\nplayback\nprovider" -> Audio
+
+    "Spotify backend" -> "Spotify\nlibrary\nprovider" -> "Spotify service"
+    "Spotify backend" -> "Spotify\nplayback\nprovider" -> "Spotify service"
+    "Spotify backend" -> "Spotify\nstored\nplaylists\nprovider" -> "Spotify service"
+    "Spotify\nplayback\nprovider" -> Audio
+
+
+Audio
+=====
+
+The audio actor is a thin wrapper around the parts of the GStreamer library we
+use. In addition to playback, it's responsible for volume control through both
+GStreamer's own volume mixers, and mixers we've created ourselves. If you
+implement an advanced backend, you may need to implement your own playback
+provider using the :ref:`audio-api`.
diff --git a/docs/api/frontends.rst b/docs/api/frontends.rst
index fc54a8a2..2237b4e7 100644
--- a/docs/api/frontends.rst
+++ b/docs/api/frontends.rst
@@ -1,3 +1,5 @@
+.. _frontend-api:
+
 ************
 Frontend API
 ************