From bb2f745024aa7187b4130cce3c03a91f9d15e345 Mon Sep 17 00:00:00 2001 From: Yisroel Baum Date: Fri, 17 Jul 2026 16:19:20 +0300 Subject: [PATCH] document application mechanics --- README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/README.md b/README.md index eb603aa..cfc6dad 100644 --- a/README.md +++ b/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`