From c38d877b94c6ac5df2de4c9c939ae683d733e8b8 Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Mon, 23 Jun 2025 22:45:18 -0400 Subject: Organize the developer docs into a "Pilcrow for Developers" book. The audience for this is developers looking to make changes to Pilcrow, either on the server, on the included client, or via its data model. Most of the material here is drawn from existing documents, but organized somewhat more coherently. I've left some space for client documentation, though no such documents exist yet. --- docs/developer/introduction.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 docs/developer/introduction.md (limited to 'docs/developer/introduction.md') diff --git a/docs/developer/introduction.md b/docs/developer/introduction.md new file mode 100644 index 0000000..0b6233d --- /dev/null +++ b/docs/developer/introduction.md @@ -0,0 +1,24 @@ +# Introduction + +This book is for developers looking to make changes to Pilcrow, either on the server, on the included client, or via its data model. + +Pilcrow is a web-based chat system that enables users to send and receive short messages with (hopefully) low latency to other users within the same community. It is composed of two main parts: the Pilcrow server, and Pilcrow clients. The following chapters lay out how each of these components is organized and implemented. + +A Pilcrow deployment consists of one server, servicing any number of connected clients. + +## The Pilcrow server + +The Pilcrow server is a Unix application designed to run as a service. It exposes services to Pilcrow users via an HTTP API, both for synchronous operations, and for asynchronous notifications. The primary services are: + +- An _event stream_, notifying client applications of operations carried out by other clients or by the server, and +- A collection of _API endpoints_, allowing client applications to submit operations to the server. + +The Pilcrow server also includes a Pilcrow client application, served over HTTP. + +For ease of deployment and administration, the Pilcrow server stores persistent data in a single database file, on the server's local filesystem. + +## Clients + +A Pilcrow client consists of one or more applications that connect to the Pilcrow server on behalf of one or more users. A client must subscribe to and consume events, and may submit operations back to the server over its HTTP API. + +The included client is a [progressive web application](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps), which runs in most browsers that can run Javascript and provide complex layouts. When run, it connects to the server from which it was downloaded. It can also be installed on any OS or using any browser that supports local installation of progressive web applications. -- cgit v1.2.3