From 65ad32975845991626ff2b4d96577ad963208cd8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= <sporiff@funkwhale.audio>
Date: Wed, 13 Dec 2023 06:50:38 +0000
Subject: [PATCH] Add users concept overview

---
 docs/concepts/user/index.md | 43 +++++++++++++++++++++++++++++++++++++
 docs/index.md               | 11 ++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 docs/concepts/user/index.md

diff --git a/docs/concepts/user/index.md b/docs/concepts/user/index.md
new file mode 100644
index 000000000..21ab14e8e
--- /dev/null
+++ b/docs/concepts/user/index.md
@@ -0,0 +1,43 @@
+# User
+
+In Funkwhale, a **User** represents a **person** who uses the Funkwhale software.
+
+When a person signs up to a Funkwhale server, they create a user profile. This user profile is associated with all of that person's activities, such as:
+
+- Uploading content
+- Listening to content
+- Favoriting content
+- Editing metadata
+- Reporting issues
+
+## Web app behavior
+
+Funkwhale shows users a **Profile** which contains the information they have shared on the platform, including a summary of their activities and their content. Users may update this profile information at any time.
+
+Users may follow other users by navigating to their profile and sending a follow request. Following another user displays their shared activity on their profile as well as in activity streams on Funkwhale, such as the "Recently listened" and "Recently favorited" streams.
+
+## Federation behavior
+
+Funkwhale users are represented by [ActivityPub `Actor` objects][actor].
+
+```json-ld
+{
+  "@context": ["https://www.w3.org/ns/activitystreams",
+               {"@language": "en"}],
+  "type": "Person",
+  "id": "https://open.audio/@betterraves",
+  "following": "https://open.audio/@betterraves/following.json",
+  "followers": "https://open.audio/@betterraves/followers.json",
+  "liked": "https://open.audio/@betterraves/liked.json",
+  "inbox": "https://open.audio/@betterraves/inbox.json",
+  "outbox": "https://open.audio/@betterraves/feed.json",
+  "preferredUsername": "betterraves",
+  "name": "Amélie",
+  "summary": "A hip-hop artist from Belgium",
+  "icon": [
+    "https://open.audio/media/__sized__/betterraves.png"
+  ]
+}
+```
+
+[actor]: https://www.w3.org/TR/activitypub/#actor-objects
diff --git a/docs/index.md b/docs/index.md
index cff692516..45d94b0d4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -63,6 +63,17 @@ moderator/allow-listing/index
 
 ```
 
+```{toctree}
+---
+maxdepth: 1
+caption: Concepts
+hidden: true
+---
+
+concepts/user/index
+
+```
+
 ```{toctree}
 ---
 maxdepth: 1