diff --git a/README.md b/README.md
index a7f5efed3..43006dd04 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,20 @@
 # soapbox-fe
 
-This is the frontend for [Soapbox](https://soapbox.pub).
+> :warning: Not yet ready for production use.
+
+**soapbox-fe** is an alternative frontend for Pleroma.
+It's part of the [Soapbox](https://soapbox.pub) project.
+
 It is based on [Gab Social](https://code.gab.com/gab/social/gab-social)'s frontend which is in turn based on [Mastodon](https://github.com/tootsuite/mastodon/)'s frontend.
 
-> :warning: Not yet ready for production use.
+## How does it work?
+
+soapbox-fe is a [single-page application (SPA)](https://en.wikipedia.org/wiki/Single-page_application) that runs entirely in the browser with JavaScript.
+
+It has a single HTML file, `index.html`, responsible only for loading the required JavaScript and CSS.
+It interacts with the backend through [XMLHttpRequest (XHR)](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest).
+
+It incorporates much of the [Mastodon API](https://docs.joinmastodon.org/methods/) used by Pleroma and Mastodon, but requires many [Pleroma-specific features](https://docs-develop.pleroma.social/backend/API/differences_in_mastoapi_responses/) in order to function.
 
 # Running locally