document application mechanics

README.md

@@ -19,6 +19,48 @@ Production assumptions:
 All local and deployment workflows are Nix-first. Run commands from
 `nix develop`, or use direnv with the checked-in `.envrc`.
 
+## How the Application Works
+
+### Content and Public Browsing
+
+Torah media is organized into sets. Each set has a name, description, icon,
+and one root element. Elements form an ordered tree: the root can have child
+elements, and each child can have further children.
+
+Visitors browse the available sets at `/media`. Opening a set loads its root
+element, where the visitor can move through parent, child, and sibling links.
+An element can present an icon, formatted rich text, an embedded YouTube video,
+and short or long PDFs. The PDF viewer supports page navigation, zoom, search,
+download, printing, and opening the source document in a new tab.
+
+### Admin Editing
+
+Administrators sign in at `/login`. An authenticated session reveals the
+management controls on `/media` and protects all content-changing API calls.
+
+From the media page, an administrator can:
+
+- Create a set with a name, description, and icon. This also creates its root
+  element and opens that element in edit mode.
+- Edit an existing set's card details or replace its icon.
+- Delete a set together with its complete element tree and managed uploads.
+
+The `Edit Element` action on a public element opens its admin editor. The
+editor supports:
+
+- Editing the title, description, rich text, and YouTube URL. Rich text
+  includes headings, inline formatting, alignment, lists, links, and tables.
+- Uploading or removing an icon, a short PDF, and a long PDF.
+- Adding child elements, moving direct children up or down, and opening a
+  child directly in edit mode.
+- Removing a child together with all of its descendants and managed uploads.
+
+Title, description, rich text, and YouTube changes are written by the `Save`
+action. Icon and PDF changes are uploaded or removed immediately. The
+`View Element` action returns to the public presentation, and `Logout` ends
+the admin session. Development login credentials are listed under
+[Local Development](#local-development).
+
 ## Required Secrets and Environment
 
 Do not commit real secret values. Local examples can live in ignored `.env`