From 06177c5e28a9c3c3e8768e31db5d66d200468e5f Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Wed, 7 Jan 2026 20:06:30 -0500 Subject: [PATCH] Add moderation action flow doc --- docs/moderation/action-flow.md | 55 ++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/moderation/action-flow.md diff --git a/docs/moderation/action-flow.md b/docs/moderation/action-flow.md new file mode 100644 index 00000000..93828e92 --- /dev/null +++ b/docs/moderation/action-flow.md @@ -0,0 +1,55 @@ +# Moderation action flow (end-to-end) + +This document describes how moderation data flows from Nostr reports and block lists into local state and UI updates. It complements the broader guidance in [`docs/moderation/README.md`](README.md). + +## Core services and responsibilities + +### `js/services/moderationService.js` + +`moderationService` aggregates report events, contact lists, and trusted mute lists, then emits summarized moderation data for the rest of the application to consume. + +* **Contacts + trusted reporters:** When contacts are rebuilt, the service emits a `contacts` event and recomputes every moderation summary. This ensures trusted reports stay in sync as the viewer’s social graph changes.【F:js/services/moderationService.js†L520-L569】 +* **Report summaries:** For each event, the service recomputes a summary of total vs. trusted reports, stores it, and emits a `summary` event with the updated data.【F:js/services/moderationService.js†L1869-L1998】 +* **Threshold transitions:** The service logs when trusted report counts cross the autoplay/block or blur thresholds. These thresholds are defined in the service (`AUTOPLAY_TRUST_THRESHOLD` and `BLUR_TRUST_THRESHOLD`) and used when trusted counts change.【F:js/services/moderationService.js†L7-L8】【F:js/services/moderationService.js†L668-L706】 + +### `js/services/moderationActionController.js` + +`ModerationActionController` is the orchestration layer for user-triggered moderation actions. It is responsible for: + +* **Overrides (“show anyway”):** `handleOverride` persists the override, clears hide state on the target video, decorates moderation state, refreshes the card UI, dispatches an override event, and resumes playback if needed.【F:js/services/moderationActionController.js†L77-L126】 +* **Block actions:** `handleBlock` ensures the viewer is logged in, updates the block list, clears overrides, re-decorates moderation state, refreshes the card UI, dispatches block/hide events, and triggers a list refresh so the feed reflects the new block state.【F:js/services/moderationActionController.js†L128-L224】 +* **Hide actions:** `handleHide` clears overrides, updates the moderation state, refreshes the card UI, and dispatches a hide event.【F:js/services/moderationActionController.js†L226-L263】 + +## Local state updates + +Moderation overrides are persisted in local state through the cache module: + +* `setModerationOverride` stores (and optionally persists) “show anyway” entries in the moderation override map and local storage.【F:js/state/cache.js†L1269-L1318】 +* `clearModerationOverride` removes entries and persists the cleanup when requested.【F:js/state/cache.js†L1320-L1341】 + +`ModerationActionController` uses these helpers via injected services when users override, hide, or block content, ensuring the UI state and local storage stay consistent.【F:js/services/moderationActionController.js†L10-L24】【F:js/services/moderationActionController.js†L77-L224】 + +## UI update flow + +### Application wiring (`js/app.js`) + +`bitvidApp` wires `ModerationActionController` to application state and UI updates. The controller receives callbacks to: + +* Decorate moderation state for videos. +* Refresh card moderation UI. +* Dispatch DOM events for moderation actions (`video:moderation-override`, `video:moderation-block`, `video:moderation-hide`).【F:js/app.js†L6029-L6114】 + +This keeps moderation mutations in one place while delegating the UI refresh to controllers and card views. + +### Profile modal integration (`js/ui/profileModalController.js`) + +`ProfileModalController` subscribes to `moderationService` contact updates and refreshes the friends list when the trusted contacts set changes. This keeps the moderation settings screen aligned with the viewer’s social graph.【F:js/ui/profileModalController.js†L891-L921】 + +## End-to-end flow summary + +1. **Ingest & summarize:** `moderationService` ingests reports/mutes/contacts, recomputes summaries, emits `summary` and `contacts`, and logs threshold transitions for autoplay and blur rules.【F:js/services/moderationService.js†L520-L706】【F:js/services/moderationService.js†L1869-L1998】 +2. **Decorate playback state:** Application-level logic consumes summaries and settings to decorate moderation state on videos (blur/autoplay/hide metadata) before rendering or playback decisions.【F:js/app.js†L5980-L6067】 +3. **User action:** UI triggers `ModerationActionController` (`handleOverride`, `handleHide`, `handleBlock`) to mutate overrides, update block lists, and refresh UI with event dispatches.【F:js/services/moderationActionController.js†L77-L224】 +4. **Persist & refresh:** Overrides persist via `js/state/cache.js`, and UI controllers refresh based on moderation events or service subscriptions.【F:js/state/cache.js†L1269-L1341】【F:js/ui/profileModalController.js†L891-L921】 + +For broader moderation policies and QA guidance, refer to [`docs/moderation/README.md`](README.md).