Fix #256: Added troubleshotting and technical overview documentation

docs/architecture.rst

@@ -0,0 +1,118 @@
+Architecture
+============
+
+Funkwhale is made of several components, each of them fulfilling a specific mission:
+
+.. graphviz::
+
+    digraph {
+        node [shape=record];
+        rankdir=TB
+        concentrate=true
+        user [group="frontend" label="User" fontsize="9"]
+        webui [group="frontend" label="Web interface (VueJS SPA)" fontsize="9"]
+        subapps [group="frontend" label="Subsonic-compatible apps (DSub, Clementine)" fontsize="9"]
+        proxy [label="Reverse proxy (Nginx/Apache)" fontsize="9"]
+        api [label="API Server (Django)" fontsize="9"]
+        db [label="Database (PostgreSQL)" fontsize="9"]
+        cache [label="Cache and message queue (Redis)" fontsize="9"]
+        worker [label="Worker (Celery)" fontsize="9"]
+        scheduler [label="Task scheduler (Celery Beat)" fontsize="9"]
+
+        user -> subapps -> proxy
+        user -> webui -> proxy
+        cache -> worker
+        proxy -> api
+        api -> cache
+        api -> db
+        scheduler -> cache
+        worker -> cache
+        worker -> db
+    }
+
+This graph may looks a bit scary, so we'll detail the role of each component below.
+
+The user
+--------
+
+Funkwhale users can interact with your instance using:
+
+- The official web interface
+- Third-party apps
+
+The web interface
+-----------------
+
+This refers to Funkwhale's built-in web interface, which is a Single Page application
+written in Vue JS. This application will interact with Funkwhale's API to retrieve
+or persist data.
+
+Third-party apps
+----------------
+
+Since Funkwhale implements a subset of the Subsonic API, it's compatible with existing apps such
+as DSub, Ultrasonic or Clementine that support this API. Those apps can be used as a replacement
+or in conjunction of the web interface, but the underlying data is the same.
+
+The reverse proxy
+-----------------
+
+Funkwhale's API server should never be exposed directly to the internet, as we require
+a reverse proxy (Apache or Nginx) for performance and security reasons. The reverse proxy
+will receive client HTTP requests, and:
+
+- Proxy them to the API server
+- Serve requested static files (Audio files, stylesheets, javascript, fonts...)
+
+The API server
+--------------
+
+Funkwhale's API server is the central piece of the project. This component is responsible
+for answering and processing user requests, manipulate data from the database, send long-running
+tasks to workers, etc.
+
+It's a Python/Django application.
+
+The database
+------------
+
+Most of the data such as user accounts, favorites, music metadata or playlist is stored
+in a PostgreSQL database.
+
+The cache/message queue
+-----------------------
+
+Fetching data from the database is sometimes slow or resource hungry. To reduce
+the load, Redis act as a cache for data that is considerably faster than a database.
+
+It is also a message queue that will deliver tasks to the worker.
+
+The worker
+----------
+
+Some operations are too long to live in the HTTP request/response cycle. Typically,
+importing a bunch of uploaded tracks could take a minute or two.
+
+To keep the API response time as fast as possible, we offload long-running tasks
+to a background process, also known as the Celery worker.
+
+Typical tasks include:
+
+- Handling music imports
+- Handling federation/ActivityPub messages
+- Scanning other instances libraries
+
+This worker is also able to retry failed tasks, or spawn automatically
+more process when the number of received tasks increase.
+
+The scheduler
+-------------
+
+Some long-running tasks are not triggered by user or external input, but on a recurring
+basis instead. The scheduler is responsible for triggering those tasks and put the corresponding
+messages in the message queue so the worker can process them.
+
+Recurring tasks include:
+
+- Cache cleaning
+- Music metadata refreshing