[github/Chocobozzz/PeerTube.git] / ARCHITECTURE.md

# Architecture

## Vocabulary

  - **Fediverse:** several servers following one another, several users
    following each other. Designates federated communities in general.
  - **Vidiverse:** same as Fediverse, but federating videos specifically.
  - **Instance:** a server which runs PeerTube in the fediverse.
  - **Origin instance:** the instance on which the video was uploaded and which
    is seeding (through the WebSeed protocol) the video.
  - **Cache instance:** an instance that decided to make available a WebSeed
    of its own for a video originating from another instance. It sends a `ptCache`
    activity to notify the origin instance, which will then update its list of
    WebSeeds for the video.
  - **Following:** the action of a PeerTube instance which will follow another
    instance (subscribe to its videos).

## Base

### Communications
  * All the communication between the instances are signed with [Linked Data
    Signatures](https://w3c-dvcg.github.io/ld-signatures/) with the private key
    of the account that authored the action.
  * We use the [ActivityPub](https://www.w3.org/TR/activitypub/) protocol (only
    server-server for now). Object models could be found in
    [shared/models/activitypub
    directory](/shared/models/activitypub).
  * All the requests are retried several times if they fail.

### Instance
  * An instance has a websocket tracker which is responsible for all videos
    uploaded by its users.
  * An instance has an administrator that can follow other instances.
  * An instance can be configured to follow back automatically.
  * An instance can blacklist other instances (only used in "follow back"
    mode).
  * An instance cannot choose which other instances follow it, but it can
    decide to **reject all** followers.
  * After having uploaded a video, the instance seeds it (WebSeed protocol).
  * If a user wants to watch a video, they ask its instance the magnet URI and
    the frontend adds the torrent (with WebTorrent), creates the HTML5 video
    player and streams the file into it.
  * A user watching a video seeds it too (BitTorrent). Thus another user who is
    watching the same video can get the data from the origin server and other
    users watching it.
Commit	Line	Data
fcaf1e0a	1	# Architecture
8c308c2b C	2
	3	## Vocabulary
	4
12b119c0 RK	5	- Fediverse: several servers following one another, several users
	6	following each other. Designates federated communities in general.
	7	- Vidiverse: same as Fediverse, but federating videos specifically.
e755a63a BB	8	- Instance: a server which runs PeerTube in the fediverse.
	9	- Origin instance: the instance on which the video was uploaded and which
	10	is seeding (through the WebSeed protocol) the video.
12b119c0 RK	11	- Cache instance: an instance that decided to make available a WebSeed
	12	of its own for a video originating from another instance. It sends a `ptCache`
	13	activity to notify the origin instance, which will then update its list of
	14	WebSeeds for the video.
e755a63a BB	15	- Following: the action of a PeerTube instance which will follow another
e755a63a BB	16	instance (subscribe to its videos).
8c308c2b C	17
	18	## Base
	19
8c308c2b	20	### Communications
e755a63a BB	21	* All the communication between the instances are signed with [Linked Data
	22	Signatures](https://w3c-dvcg.github.io/ld-signatures/) with the private key
	23	of the account that authored the action.
	24	* We use the [ActivityPub](https://www.w3.org/TR/activitypub/) protocol (only
	25	server-server for now). Object models could be found in
	26	[shared/models/activitypub
63bfad7e	27	directory](/shared/models/activitypub).
e755a63a	28	* All the requests are retried several times if they fail.
55e0591c	29
fcaf1e0a	30	### Instance
12b119c0 RK	31	* An instance has a websocket tracker which is responsible for all videos
12b119c0 RK	32	uploaded by its users.
e755a63a BB	33	* An instance has an administrator that can follow other instances.
	34	* An instance can be configured to follow back automatically.
	35	* An instance can blacklist other instances (only used in "follow back"
	36	mode).
	37	* An instance cannot choose which other instances follow it, but it can
	38	decide to reject all followers.
	39	* After having uploaded a video, the instance seeds it (WebSeed protocol).
	40	* If a user wants to watch a video, they ask its instance the magnet URI and
	41	the frontend adds the torrent (with WebTorrent), creates the HTML5 video
	42	player and streams the file into it.
	43	* A user watching a video seeds it too (BitTorrent). Thus another user who is
	44	watching the same video can get the data from the origin server and other
	45	users watching it.