From design/ia.md in the repository.

Annoudio information architecture

Status: decision, 2026-10-09. ROADMAP Phase 5c step 1. Phase 5c step 2 builds this file. Read CONTEXT.md first; this file uses its words, including Reply and Topic.

Sources: ia-C-journey-centred.md (the spine: lifecycle, who sees what, mails, member home, system return, no Unpublish), ia-A-task-centred.md (operator navigation: Today, job sidebar, Publish → next story, the 3-step wizard), ia-B-object-centred.md (the project frame on public surfaces, one project overview page). Not taken from B: per-project list scoping, the project cookie, the replaced sidebar, the two-level navigation, the stored project ↔ recording link. Payload facts come from the feasibility sections of A, B and C (checked against 3.90.2 types).

0 Decision summary

1. One story lifecycle with six names (Processing, Waiting for review, Returned, Published, Published · change waiting, Removed) on every surface: admin, Annotate page, player note, mail.
2. Unpublish goes. A story leaves the player by Return to the member (with a reason) or Remove. A return of a change keeps the published version visible.
3. The operator home is Today: a setup checklist on an empty stack, then the work that waits.
4. The sidebar names jobs in ≤ 3 words: Today, Review stories, Add a widget, Vocabulary, Members; then Settings: Projects, Recordings, Operators, Your account. (Vocabulary replaced Concepts on 2026-10-09: design/vocab.md §1.)
5. Publish opens a dialog with the visitor preview; after it, the next waiting story opens. Next story replaces "Keep as draft".
6. Add a widget to a site has 3 steps: Recording, Site (the project), Snippet. A new public route GET /embed/v1/recordings/{project}/{id}.json serves the CMS plugins.
7. Members get a home, Your stories, and Your account (name, mail choice, sign out). Six mails close every handoff; each has one link.
8. The project frame (name, theme, rights line) shows on the Annotate page; the player shows theme and rights line. The theme JSON gets three additive keys: name, rightsLine, rightsIri.
9. Schema: five new fields (story toldOn, changedBy, lastAction, rejection.automatic; member mailNotices; operator reviewMail). One migration.
10. Counts split stories and replies in words ("2 stories and 1 reply wait for review"); the catalogue column counts stories only, as the player's total does.

1 People, jobs, handoffs

A handoff is the moment when one person's action is the next person's trigger. Each handoff has a signal that reaches the next person when that person is away.

2 Story lifecycle

2.1 States

The UI state is derived from stored data. One function, stories.lifecycle(row), derives it. The admin, the Annotate page, the mails and the counts call only this function.

Transitions:

 Writing ──Send for review──> Processing ──media ready──> Waiting for review ──Publish──> Published
                                   │ file failed (system)        │ Return                │  │
                                   v                             v                       │  │ member changes
                               Returned <────────────────────────┘<──── Return ──────────┘  v
                                   │ member: Send for review           Published · change waiting
                                   └────> Processing or Waiting           (Return or Publish acts on the change)
 Remove: from any state → Removed (the story and its replies)

Rules:

1. publish-at-once: Waiting for review is skipped. Writing → Published, or Processing → Published when the media is ready (the media.settled consumer publishes it).
2. Return of a Published story (no newer draft) makes it a draft with the reason: visitors stop seeing it. This is the take-down path. Return of a change returns the newer draft only: the published version stays visible (Phase 5 decision 5).
3. System return: when a media body fails, the media.settled consumer sets rejection with automatic: true and the reason "We could not use your file. Attach a different file." The operator sees "Returned (automatic)".
4. A member never sees "draft". An operator sees "Draft" only in History.
5. A reply has the same states. Its parent must be Published for the reply to show (Phase 5b decision 7).

2.2 Who sees what

2.3 Mails

Mail rules: plain text plus a simple HTML copy. One link per mail. No operator name in a member mail: the voice is "the River Voices team" (it protects operators; the admin keeps rejection.operator). Mails go after the commit, never inside a hook transaction. A failed send logs and does not undo the action. Sender address: EMAIL_FROM (exists). Sender name: the project name for member mails, "Annoudio" for operator mails.

Opt-outs: the member's Your account has one checkbox, "Mail me when my story is published or gets a reply" (mailNotices, default on; M3, M4). The operator's Your account has "Review mail: once a day (default) / for each story / never" (reviewMail). The choice is per person, not per project: the person who gets the mail owns the choice.

3 Object model as each role sees it

Nobody outside the admin sees Instance, Catalogue, IRI, Container, Body or Media body as words.

4 Navigation

4.1 Admin

┌ Annoudio ─────────────┬──────────────────────────────────────────────┐
│ ● Today               │                                              │
│   Review stories   3  │  (content)                                   │
│   Add a widget        │                                              │
│   Concepts            │                                              │
│   Members             │                                              │
│ SETTINGS              │                                              │
│   Projects            │                                              │
│   Recordings          │                                              │
│   Operators           │                                              │
│   Your account        │                                              │
└───────────────────────┴──────────────────────────────────────────────┘

Rules:

1. The badge on Review stories is the Waiting for review count (stories + replies). No other badge.
2. Job links come from beforeNavLinks. Stories, Media bodies, Concepts and Members have group: false. Projects, Recordings and Operators are in the group "Settings". The default Payload Nav stays.
3. Object pages (story, recording, concept, member, project) stay reachable by URL and by links. Breadcrumbs name the job: "Review stories / Story by Asha, 1:02–1:35".
4. Every job ends on a screen that says what happens next.

Today, empty stack and normal day:

┌ Today ─────────────────────────────────┐  ┌ Today ─────────────────────────────────────┐
│ Put your first player on a site        │  │ 2 stories and 1 reply wait for review.     │
│ [x] 1 Make a project for your site     │  │ The oldest came in 2 days ago.             │
│ [ ] 2 Add a recording                  │  │                       [ Start reviewing ]  │
│ [ ] 3 Put the snippet on a site        │  │ 1 story is processing.                     │
│       [ I pasted it ]                  │  │ 2 stories are returned. Members must       │
│ [ ] 4 Publish the first story          │  │   change them. 1 is automatic (file).      │
│ Optional: add concepts, so members     │  │ Other jobs: [ Add a widget ] [ Concepts ]  │
│ can choose topics.                     │  │ Last 7 days: 12 in, 9 published,           │
│              [ Add a recording ] ←next │  │   2 returned, 1 removed.                   │
└────────────────────────────────────────┘  └────────────────────────────────────────────┘

Checklist rules: a step ticks from data. 1: a project exists. 2: a recording exists. 3: the operator selects I pasted it, or a story arrives with a toldOn on a site of the project. 4: a story is published. The checklist goes when all four tick, or with Hide the list. Empty queue text: "No stories wait for review. The last story came in 3 days ago."

Review screen (Waiting for review) and the Publish dialog:

┌ Review stories / Story by Asha · Ferry crossing, 1962 ─── [Waiting for review · 2 days] ┐
│ River Voices                                                                            │
│ ▶ 1:02–1:35  ───■──────────                                                             │
│ "My father worked the ferry. The horn meant…"                                           │
│ Topics: Ferry, Horn        Voice note ▶ 0:41 (ready)                                    │
│ Told on: rivervoices.example.org/ferry   [ Open on the site ]                           │
│ No topic fits? [ Add a concept to River Voices ]                                        │
│ [ Publish ]  [ Return to the member ]  [ Next story ]                    ⋮  Remove      │
│ Tabs: Story · History                                                                   │
└─────────────────────────────────────────────────────────────────────────────────────────┘
   ┌ Publish this story? ────────────────────────────────┐
   │ Visitors see it like this, within one minute:       │
   │ ┌ Asha · 1:02–1:35 ───────────────────────────────┐ │
   │ │ My father worked the ferry…   [Ferry] [Horn]    │ │
   │ └─────────────────────────────────────────────────┘ │
   │ We mail Asha that it is published.                  │
   │ [ Publish the story ]  [ Cancel ]                   │
   └─────────────────────────────────────────────────────┘

After Publish the story: toast "Published. Visitors see it within one minute." and the next waiting story opens; at the end, the empty Waiting tab. In Processing, Publish is off with "The voice note is still processing." For a reply, the parent story shows above, read-only.

Add a widget to a site (/admin/add-widget):

┌ Add a widget to a site ── 1 Recording ─ 2 Site ─ 3 Snippet ─────────┐
│ 1 Recording                                                           │
│ ( ) Choose a recording  [ search the recordings… ]                    │
│ (•) New recording   Title [Ferry crossing, 1962      ]                │
│                     Audio address [https://archive.example/f.mp3]     │
│                     ✓ The audio plays in this browser. Length: 30:34. │
│                                                       [ Next ]        │
├───────────────────────────────────────────────────────────────────────┤
│ 2 Site                                                                │
│ Which site shows the player?                                          │
│ (•) River Voices  rivervoices.example.org                             │
│ ( ) Kochi Voices  kochivoices.example.org                             │
│ ( ) New project: Name [        ]  Website address [https://     ]     │
│                                                       [ Next ]        │
├───────────────────────────────────────────────────────────────────────┤
│ 3 Snippet                                                             │
│ <script async src="https://stories.org.example/embed/v1.js"></script> │
│ <annoudio-player project="river-voices" recording="1"                 │
│   src="https://archive.example/f.mp3"></annoudio-player>              │
│ [ Copy the snippet ]   ✓ Copied.                                      │
│ Paste these two lines into the page. A page needs the first line      │
│ one time only. Members come back only to rivervoices.example.org.     │
│ WordPress or Omeka S: type the recording number 1 in the block.       │
│ ┌ preview: the real player with the River Voices theme ──────────────┐│
│ └────────────────────────────────────────────────────────────────────┘│
│                                                       [ Done ]        │
└───────────────────────────────────────────────────────────────────────┘

How the project is chosen: step 2 lists the projects. With one project, it is selected and step 2 shows one line, "Site: River Voices. [Change]". With no project, step 2 shows the inline form (name, website address); the other project settings get defaults. The snippet holds the three values: project (step 2 slug), recording (step 1 id), src (step 1 audio address). Done goes to Today. The wizard and the recording page call the same catalogue functions; the Recordings list has no create button of its own: its button is Add a widget.

The recording JSON route GET /embed/v1/recordings/{project}/{id}.json → { id, title, url, duration } (CORS *, anonymous, 404 for an unknown project or recording). Callers: the WordPress block and the Omeka S module (the editor check fills src from the number; Phase 7a request 1), and step 3's line "type the recording number 1", which is true only because of this route. Step 3 itself reads catalogue.recording(id) in process, the same function that the route serves.

4.2 Annotate page (member, phone)

No sidebar. Top bar: project name (small), recording title, "Asha ▾" (menu: Your stories, Your account, Sign out). One way back on every screen: Back to the site (the checked return), else Your stories. Footer: the rights line, for example "Stories here are shared under CC BY 4.0." with the rights link. The page sets the project's theme tokens on its root.

Your stories (phone, 360 px):

┌ Your stories ─────────────── Asha ▾ ┐
│ Returned to you (1)                 │
│ ┌ Ferry crossing, 1962 · 1:02–1:35 ┐│
│ │ River Voices         [Returned]  ││
│ │ "Please remove the full name…"   ││
│ │ [ Change the story ]             ││
│ └──────────────────────────────────┘│
│ Processing (0)                      │
│ Waiting for review (1)          ▸   │
│ Published (4)                   ▸   │
│ Replies (2)                     ▸   │
│ ─────────────────────────────────── │
│ Empty: You have no stories yet. On  │
│ a site, select "Tell a story".      │
└─────────────────────────────────────┘

Groups in this order: Returned to you, Processing, Waiting for review, Published (with "change waiting" on its card), Replies. Each card names its recording, project and range. Your stories has no single project, so it uses the default theme.

Your account (minimum): Email (read-only), Name (Save), checkbox "Mail me when my story is published or gets a reply", Sign out. Delete: open question 1.

4.3 Player (visitor)

No navigation. Exits: Tell a story (the Annotate link) and Reply (per open story). The project frame: theme tokens (exists) and the rights line once, below the story list, in a new part rights. The player does not show the project name: the host page already names the site.

Empty state:

┌ ▶ 0:00 / 30:34  ───────────────────────────── ┐
│ No stories yet. Tell the first one.          │  ← message
│ [ Tell a story ]                             │  ← annotate-link
│ Stories here are shared under CC BY 4.0.     │  ← rights (new part)
└──────────────────────────────────────────────┘

4.4 Links between surfaces

5 Screen inventory

Marks: NEW, CHANGED, UNCHANGED against the Phase 5b code.

5.1 Admin

5.2 Annotate page

5.3 Player

Mail screens M1–M7: section 2.3 (M1 CHANGED: project name in the subject; M2–M7 NEW).

6 Flows

F1 First operator on an empty stack. 1. /admin → O0 → Create the first operator. 2. O3 shows the checklist. 3. Make a project → O15 → name, website address, rights line → Save; step 1 ticks. 4. Add a recording → O7 → F2.

F2 Recording to live player. 1. O7 step 1: New recording, title, audio address; the probe says "The audio plays in this browser. Length: 30:34." Next. 2. Step 2: River Voices is selected (one project). Next. 3. Step 3: Copy the snippet → "Copied." The operator pastes it on the host page (H1). On WordPress or Omeka S, the editor types the number 1; the block reads the recording route. 4. Done → O3; the operator selects I pasted it; step 3 ticks. 5. A visitor opens the page: V2.

F3 Story to visible. 1. Visitor plays to 1:02 → Tell a story (H3) → P1. 2. P1 → M1 → P2 → P3 (first time) → P4 with Start 1:02. 3. Member sets End, writes, picks topics, records a voice note (P4m). 4. Send for review → host page, V5 "Your story is sent…" (or P5). The story stores toldOn. 5. Worker ends (H5): Processing → Waiting for review. M6 goes the next morning. 6. Operator: O3 Start reviewing → O5 → Publish → O5a → Publish the story; the next story opens. 7. M3 to the member (H7); the visitor sees the story in ≤ 60 s (H8). With publish-at-once: step 4 shows "published", steps 5–6 do not occur, M3 goes only if the media made the publish wait.

F4 Returned and sent again. 1. O5 Return to the member → O5b reason → Return the story. The next story opens; the row moves to Returned. 2. M2 (H6) → Change your story → P6 with the reason banner (P1–P2 first if signed out). 3. Member changes it → Send for review. The rejection clears. 4. O5 shows "Sent again after a return"; History keeps the reason. Publish → F3 step 7. Variant: a change to a Published story; the published version stays visible during the whole flow. Variant: a failed file gives the same flow with "Returned (automatic)" and no operator step 1.

F5 Item added and used. 1. O5: no item fits → Add an item to Places → the page of the list → Add an item → O11 with the project and the list set → label "Strike" → Save. Or O5: an own answer "Ravi (new)" → Add "Ravi" to People (the story keeps its own answer). 2. Members see "Strike" in P4 at the next page load. Operators do not change stories: the operator can return the story with "Choose Strike as the place". 3. After the next publish, the widget shows "Place: Strike". 4. A later rename runs conceptChanged; O11 says "12 stories use this item".

F6 Reply. 1. Visitor opens a story (V4) → Reply → Annotate page with replyTo. 2. Sign in as F3 → P4r → Send for review. 3. O4 row "Reply to: My father worked…"; O5 shows the parent above. Publish. 4. M3 to the replier, M4 to the parent's member (H9). Visitors see the thread under the parent.

F7 Take down. 1. A complaint names a story. O4 All tab, search → O5 (Published). 2. Content can come back after a change → Return to the member (it leaves the player; M2). Content must go → ⋮ Remove → O5c → Remove the story (its replies go too; M5 to each member). 3. The player drops it within 60 s.

7 Naming

8 Data model and interface changes

No projects.recordings link: the instance stays derived (CONTEXT). The Overview tab lists recordings with stories in the project only.

9 Feasibility per screen

Payload default = no code beyond labels. Customised = Payload slots and API. Custom page = an admin view (admin.components.views[key] with DefaultTemplate, own operator check). Outside = Next routes or embed/.

10 Build order (Phase 5c step 2)

Each slice ≤ 5 files. Each slice keeps test:int, test:e2e, tsc, lint green.

11 Open questions

1. Can a member delete their own account? Default: not in 5c. Your account says "To delete your account and your stories, write to {EMAIL_FROM}." An operator then removes the stories and blocks the member. A real delete (with what happens to published stories and replies) goes to Phase 7.
2. Does Remove also remove the replies under the story? Default: yes. A reply is served only under a published parent (5b decision 7), so a kept reply is invisible data. Each reply's member gets M5.
3. Should the stack tick "Put the snippet on a site" by itself? Default: no new write. The step ticks by I pasted it or by the first story with a toldOn on that site. A "player seen" record per site origin needs a write on the cached read path, which today writes nothing (proposal C §8.3).