doc/Parser.md

@@ -55,12 +55,41 @@ Existing services
 Metadata Extraction
 -------------------
 
+The first step is to extract information about the MRL being processed. This MRL doesn't necessarily represents a media, but could also point to a playlist or a collection.
+
+This is currently the only step that requires an external service provided by the application. For mobile applications, this is done using libvlc's preparse feature, but it has to be implemented through libvlccore API for the desktop versions.
+
+Since the media library is built without (lib)vlc support for desktop platforms, it is up to the media library use (in this case, the VLC media library module) to provide this service.
+
+The resulting metadata are serialized and exposed through the `parser::IItem` interface, in order to provide a common way of accessing the results throughout the rest of the pipeline.
+
+:warning: The extraction task will systematically run as long as the task isn't entirely completed. This is because the rest of the services assume that they have all the information required to do their processing. In theory this requirement could be lifted for some linking tasks, as they are likely not to depend on the metadata themselves, but rather the information stored in database.
+
 Metadata Analysis
 -----------------
 
+The analysis step is the main one, and is responsible for creating most entities in the database. It also handles refreshing tasks by removing previous information and performing a rescan if needed.
+
+The list of operations depend on the type of task. In all cases, the entity represented by the MRL will be created first, when analyzed for the first time. Once the media/playlist/collection is created in database, the later stages will attempt to populate the various fields with the information available.
+
+For album tracks, the flowchart can be seen [here](https://code.videolan.org/videolan/medialibrary/-/wikis/Album-selection)
+
+For videos, a best effort attempt at extracting show information is done by analyzing the file name. If the video isn't detected as a show, nothing more is performed for now.
+
+For playlists, the processing usually consists in flushing the currently known content and spawning a linking task per playlist item.
+
+For collections, we currently do not flush the previously known content and simply ignore duplicated elements when processing the linking task.
+
 Linker
 ------
 
+The `LinkService` is responsible for linking things together. This currently means:
+- Linking a media to a playlist or collection
+- Linking a file to a media (for instance an external subtitle track)
+
+The linking step was separated from the rest of the pipeline in order to simplify linking an analyzed media to a playlist. There is no way of knowing if the media will be analyzed before the playlist, or the other way around. 
+
+By having a task dedicated to linking, we can postpone a task until later, once we know we have  the required entities in database. This is done by returning `Requeue` as a status from the `Service::run` member function.
 
 Tasks in database
 =================
\ No newline at end of file