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.

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/developer/server/code-organization.md b/docs/developer/server/code-organization.md
new file mode 100644
index 0000000..d17b604
--- /dev/null
+++ b/docs/developer/server/code-organization.md
@@ -0,0 +1,25 @@
+# Code organization
+
+This document explains the rationale for the server's module structure and overall code layout, rather than the layout. If you're looking for a map, look in `src/lib.rs`.
+
+Trust your gut, and reorganize to meet new needs. We've already revised this scheme several times as the code base has grown, and there's no reason we can't do so again.
+
+## Topic modules
+
+High-level concerns are grouped into topical modules. These include `crate::channel`, `crate::events`, `crate::login`, and others. Those modules generally contain their own app types, their own repo types, their own extractors, and any other supporting code they need. They may also provide an interface to other modules in the program.
+
+Most topic modules contain one or more of:
+
+- An `app` module exposing the primary operations on the topic domain,
+- An `id` module defining any domain-specific identifier types,
+- A `handlers` module exposing Axum handler functions,
+- A `repo` module exposing database access types,
+- A `history` module exposing history types,
+- A `snapshot` module exposing state types, or
+- An `events` module exposing domain-specific event types.
+
+Not every topic modules hits every common convention, and some topic modules vary from the conventions to meet their specific design needs.
+
+## Cross-cutting modules
+
+However, some cross-cutting parts of the system have been pulled out into top-level modules of their own. These include `crate::routes`, `crate::app`, `crate::clock`, and others. Reasons for doing this include having multiple equally-valid modules the code could have been put in, keeping the use of namespaces legible, and others.