Files
youtube-generator/docs/ARCHITECTURE.md
T
poli0981andClaude Opus 5.5 5fd28e336c chore(release): v1.5.1
Accessibility (#238, #239): AA contrast, generated text marked with its
language, page names read out after a navigation, the single-key
shortcut switch, desktop zoom hotkeys, and ACCESSIBILITY.md in the repo,
the Legal Center and on the website.

- CHANGELOG v1.5.1, ROADMAP entry and status
- docs: ARCHITECTURE (RouteAnnouncer, settings, capabilities), TECH-SPEC
  (singleKeyShortcuts, contrast test, test count), PACKAGING (zoom
  hotkeys and permission), FEATURES
- version references: DISCLAIMER + Vietnamese, the bug-report template
- six manifests 1.5.0 -> 1.5.1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 20:19:21 +07:00

43 KiB
Raw Permalink Blame History

Architecture Document

YTDescGen — Technical Architecture

Reflects v1.5.1. Implementation details (configs, interfaces, file formats, CI) are in TECH-SPEC.md; desktop and Android builds in PACKAGING.md; running the web deployment in HOSTING.md.


1. High-Level Architecture

┌────────────────────────────────────────────────────────────────────┐
│                         Presentation Layer                         │
│  Pages: Editor · Output · Profiles · History · Settings · Batch    │
│         Social · Playlist · Logs · About · Legal (+ error pages)   │
│  Shell: Sidebar · Header · MobileNav · CommandPalette (cmdk)       │
│  Components: ui/ (Radix, Motion, sonner) · editor/ · output/       │
│              backup/ · profiles/ · presets/ · templates/ · …       │
├────────────────────────────────────────────────────────────────────┤
│                         Application Layer                          │
│  Hooks: useGeneratedOutput · useRenderOptions · useOutputCopy      │
│         useOutputLimits · useStrictBlock · useSaveToHistory · …    │
│  Stores (Zustand): editor · profiles · presets · templates         │
│         history · settings · logs · pending-invalid                │
│  i18next: 8 locales — en bundled, the other seven lazy-loaded      │
│  utils/: backup/ · library-apply · store-paste · file-ops          │
│          native · log-storage · validation · …                     │
├────────────────────────────────────────────────────────────────────┤
│         Core Engine Layer — src/engine/ (pure TypeScript)          │
│  renderAll() in template-renderer                                  │
│    ├─ title-builder                                                │
│    ├─ description-builder ── rig-block · timeline-parser           │
│    │                         channel-phrase · endings-format       │
│    └─ tag-generator                                                │
│  Also: title-variants · limits · social-post-builder · upscale     │
│        pinned-comment-builder · playlist-builder · graphics-vendor │
├────────────────────────────────────────────────────────────────────┤
│                        Infrastructure Layer                        │
│  localStorage (every platform) · Clipboard API                     │
│  Web: File System Access API or a download                         │
│  Tauri: name-only Rust commands (backups, logs) · Save/Open        │
│         dialogs run from Rust · opener plugin (external links)     │
└────────────────────────────────────────────────────────────────────┘

The same source ships two ways:

                 One React source (src/), two Vite builds
                  ┌──────────────────┴───────────────────┐
                  ▼                                      ▼
┌──────────────────────────────────┐   ┌──────────────────────────────────┐
│ Web — ytgenerator.stream         │   │ Tauri 2 — desktop and Android    │
│ BrowserRouter (real paths)       │   │ HashRouter (asset protocol)      │
│ Build adds: static /legal pages, │   │ Build (TAURI_ENV_PLATFORM set):  │
│   security.txt, analytics beacon │   │   no static pages or analytics   │
│ Cloudflare Worker (worker/):     │   │ Rust core (src-tauri/):          │
│   Turnstile gate · headers ·     │   │   name-only file commands,       │
│   /legal/* · static assets       │   │   native dialogs, tray (desktop) │
│ Data: the browser's localStorage │   │ Data: WebView localStorage +     │
│                                  │   │   app data dir (backups, logs)   │
└──────────────────────────────────┘   └──────────────────────────────────┘

Routing. App.tsx picks the router at runtime: BrowserRouter on the web — the Worker serves the app shell for every route, and Web Analytics counts page views by path — and HashRouter inside Tauri, whose asset protocol has no server-side fallback. Before the router reads the URL, main.tsx rewrites an old web bookmark (/#/output → /output); Tauri keeps hash URLs.

Route tree. /legal and /legal/:docId (the Legal Center) sit outside the consent guard, so the consent screen can open each document. Everything else is inside ConsentGuard, a layout route that renders ConsentGate until the user has accepted the current terms version (CURRENT_TERMS_VERSION = 2 since v1.0.0). Inside it, AppShell holds the pages: the Editor (index route) stays in the entry bundle; Output, Profiles, History, Settings, Batch, Social, Playlist, Logs and About are React.lazy chunks, each wrapped in its own ErrorBoundary + Suspense so a crash on one page cannot blank the app. On the web, /legal/<id> loaded directly is the Worker's static page; navigated to inside the app, it is the Legal Center — the same URL either way.

App shell. AppShell combines a collapsible Sidebar, the Header top bar (output and interface languages, theme), MobileNav (a bottom bar on phones, with a "More" drawer), and three lazily loaded pieces: the ⌘/Ctrl + K CommandPalette (cmdk), the shortcut help and the backup RestoreDialog, mounted only while a restore is pending. UI primitives in components/ui/ wrap Radix (Dialog, AlertDialog, Popover, Tooltip, Tabs, Switch, Checkbox, ToggleGroup); animation is Motion behind LazyMotion (its feature bundle loads after first paint, and MotionConfig reducedMotion="user" honours the OS setting); toasts are sonner, with translated region and close labels. RouteAnnouncer (v1.5.1) is a polite live region that reads out the new page's name after a navigation: every page names itself with useDocumentTitle, which fires ytdescgen:page-title once the commit's effects have run, and focus stays where it was. Accessibility as a whole: ACCESSIBILITY.md.

Error pages (v0.27). components/errors/ holds a reusable ErrorPage (404/403/419/500/offline/runtime) driven by the pure config/error-pages.ts map. The error routes (/403, /419, /500, /offline, catch-all *) are siblings of the AppShell route group inside the consent guard, so they render full-screen without the shell. ErrorPage is router-agnostic — Home is a plain location change (/ on the web, #/ in Tauri) and Back is history.back() — so the root ErrorBoundary, mounted in main.tsx outside the router, reuses it as its crash fallback.

Start-up. Before first paint:

  1. public/theme-init.js (a plain script in index.html) applies the saved theme and the Hide scrollbars class (hide-scrollbars, v1.1.0) and sets <html lang> to the saved UI language, so a light-theme user sees no dark flash.
  2. main.tsx rewrites old hash URLs (web), carries over a terms acceptance from the gate page's ytg_terms cookie (web), and registers a one-time reload for chunk files that a new deploy removed (vite:preloadError).
  3. It loads the saved UI and output languages (capped at 2 s), applies the theme and scrollbar classes, installs the external-link handler (Tauri: links open in the system browser through the opener plugin), then renders.

After mount, App.tsx starts a first-run draft in the Default Output Language, runs the Tauri data chores (startAppData(): legacy-file recovery, then automatic backups on desktop) before loading the persisted logs, prefetches the Output page when the browser is idle, keeps i18next in step with the appLanguage setting, and keeps the hide-scrollbars class in step with hideScrollbars (the Settings toggle, a restored backup and its undo).

2. Core Engine Design

The engine holds all generation logic with zero framework dependency: no React, no DOM, no storage, no clipboard. Every function is pure — typed input in, string (or list) out. Values from the environment come from the caller: the translator t, and the year for the copyright line and trending tags (the builders fall back to the current year when it is omitted).

Module Role
template-renderer.ts renderAll(input, t, options) → GeneratorOutput: title + description + tags, character counts, over-limit warnings
title-builder.ts Titles: video-type segment, quality badge (position, case), separator, order (game first / video first)
title-variants.ts Three alternative title shapes, each built by buildTitle with a different order / badge position
description-builder.ts The description, block by block (intro, timestamps, store links, video settings, rig, warnings, notes, donate, social, community, contact, copyright, …)
tag-generator.ts Tag pools, de-duplication, YouTube's own tag-length count (youtubeTagsLength) and trimming
timeline-parser.ts Timestamps → translated chapter lines; YouTube's chapter rules (checkChapters); "Tidy up" (normalizeTimeline)
channel-phrase.ts Drops "on {{channelName}}" (per language) when the channel name is empty
rig-block.ts The rig as localised Label: value lines in a fixed order (description and social captions)
endings-format.ts, graphics-vendor.ts Endings lists split across videos; valid upscaler / frame-generation options per vendor
upscale.ts Upscaled in the editor (v1.5.0): validUpscaleSource — the one rule the title badge, the Upscale line and the automatic tech note share
limits.ts Over-limit status per field, Copy All rules, < / > detection
social-post-builder.ts Captions for TikTok, YouTube Shorts, Instagram Reels, Facebook Reels, X (weighted count), Threads, Bluesky
pinned-comment-builder.ts, playlist-builder.ts Pinned comment; playlist title, description and comment
types.ts GeneratorInput, GeneratorOutput, YT_LIMITS, the option unions

2.1 Type Definitions (engine/types.ts)

// ── Video types (20) ──
// prettier-ignore
type VideoType =
  | "full" | "part" | "full_demo" | "demo_part"
  | "boss" | "boss_nohit" | "ending" | "speedrun" | "100percent"
  | "dlc" | "newgame_plus" | "challenge" | "side_quest" | "secret"
  | "comparison" | "guide" | "mods" | "collectibles" | "livestream" | "gacha_quest";

// ── Genres (42, up to 3 per video — MAX_GENRES) ──
// prettier-ignore
type Genre =
  | "action" | "hack_slash" | "beatemup" | "platformer"
  | "horror" | "survival_horror" | "psychological_horror"
  | "rpg" | "jrpg" | "action_rpg" | "crpg"
  | "fps" | "arena_shooter" | "tactical_fps" | "boomer_shooter" | "extraction_shooter" | "shmup"
  | "openworld" | "indie" | "soulslike" | "racing" | "story" | "simulation" | "city_builder"
  | "fighting" | "stealth" | "survival_craft" | "roguelike" | "metroidvania" | "mmo"
  | "rhythm" | "puzzle" | "tower_defense" | "card_game" | "deck_builder" | "auto_battler"
  | "battle_royale" | "tactical" | "space" | "farming" | "fmv" | "visual_novel";

// ── Supported languages (8) ──
type SupportedLanguage = "en" | "vi" | "ja" | "es" | "ko" | "zh" | "pt-BR" | "id";

// ── Input (abridged — about 75 fields) ──
interface GeneratorInput {
  // Core
  videoType: VideoType;
  language: SupportedLanguage;
  genres: Genre[];

  // Game and channel
  gameName: string;
  gameNameLocalized?: Partial<Record<SupportedLanguage, string>>;
  channelName: string; // may be empty
  platform: string;

  // Video-type specific: partNumber, bossName, dlcName, challengeName, modName, modList,
  // liveUrl, scheduledTime, gacha quest fields …
  // Video settings: resolution, upscaledFrom, fps, graphicsPreset, ray tracing,
  // frame generation, upscaling, artStyle, videoStyleEra, versionInfo …
  // Content: timestamps, playlistLink, emails, music, sponsor, publisher, content warnings,
  // tech notes, playthrough notes, endings, playtest, community links …

  // Deprecated since v0.11 (folded into contentWarnings), kept for old drafts
  spoilerWarning: boolean;
  matureWarning: boolean;

  // Links and hardware
  storeLinks: Partial<Record<string, string>>;
  storeLinkTypes?: Partial<Record<string, StoreLinkType>>; // "paid" | "free" | "demo"
  social: Partial<Record<string, string>>;
  rig: Partial<Record<string, string>>; // GPU as "gpu:<catalog id>" since v1.0.0
}

// ── Output ──
interface GeneratorOutput {
  title: string;
  description: string;
  tags: string[];
  tagString: string;
  charCounts: {
    title: number;
    description: number;
    tags: number; // YouTube's count: quotes around multi-word tags + commas
  };
  warnings: CharLimitWarning[]; // one per field strictly over its limit
}

2.2 Template Architecture

Templates are data-driven: every sentence the engine writes comes from the output language's templates.json, not from string concatenation in code. The engine interpolates {{placeholders}} through t. An excerpt of src/i18n/locales/en/templates.json:

{
  "title": {
    "separator": " — ",
    "separators": { "emDash": " — ", "hyphen": " - ", "colon": ": ", "pipe": " | " },
    "suffix": "Gameplay No Commentary",
    "videoType": {
      "full": "",
      "part": "Part {{partNumber}}",
      "full_demo": "Demo",
      "demo_part": "Demo Part {{partNumber}}",
      "boss": "{{bossName}} Boss Fight",
      "boss_nohit": "{{bossName}} Boss No Hit"
    }
  },
  "description": {
    "intro": {
      "full": "This video features the full gameplay of {{gameName}} on {{channelName}}.",
      "part": "This video features Part {{partNumber}} of {{gameName}} on {{channelName}}."
    },
    "noCommentaryLine": "No Commentary — pure gameplay for your enjoyment.",
    "sections": {
      "timestamps": "⏱ TIMESTAMPS",
      "storeLinksBuy": "🎮 GET THE GAME (if you want to buy)",
      "storeLinksDownload": "⬇️ DOWNLOAD THE GAME (if you want to play)",
      "videoSettings": "🖥 VIDEO SETTINGS",
      "rig": "💻 MY RIG",
      "playlist": "▶️ Watch the full series: {{link}}",
      "contact": "📧 Business inquiries: {{email}}",
      "cta": "👍 Like | 🔔 Subscribe | ↗️ Share"
    },
    "rigLabels": { "cpu": "CPU", "gpu": "GPU", "ram": "RAM" }
  }
}

The file's top-level sections are title, description, pinnedComment, hashtags, playlist and timeline (the translated chapter keywords). When the channel name is empty, the builders render {{channelName}} as a placeholder slot and channel-phrase.ts removes the words around it, per language.

2.3 Tag Generator Architecture

generateTags(input, { includeMultilingualTags, includeTrendingTags, year })

  priority  pool                 source
  1         game name            bare tag (≤ 30 chars) + a shorter form for composites
  2         boss name            bossNameTag(bossName) — Boss Fight / Boss No Hit only
  3         core                 CORE_TAGS_BY_LANG[language]
  4         genre                GENRE_TAG_REGISTRY[genre], for every selected genre
  5         video type           VIDEO_TYPE_TAGS[videoType]
  6         platform             PLATFORMS[].tagName ("Steam", "itch.io", …)
  7         quality              resolution / fps
  8         multilingual         MULTILINGUAL_TAGS[language]           (setting)
  9         trending             year-based, first genre only          (setting)
  10        publisher/developer  pubDevName, as a bare tag
                     │
                     ▼
  de-duplicate (case-insensitive) · drop tags over 30 characters
                     │
                     ▼
  trimToCharLimit(tags, 500): keep tags in priority order while they fit,
  measured the way YouTube measures them (youtubeTagsLength); a tag that
  doesn't fit is skipped and the shorter ones after it are still tried

The pools are registries — a new genre is one entry in GENRE_TAG_REGISTRY plus its search term in GENRE_SEARCH_TERMS (used by the trending tags), and tests/engine/tag-generator.test.ts fails if either disagrees with config/genres.ts:

// engine/tag-generator.ts
export const GENRE_TAG_REGISTRY: Record<string, (gameName: string) => string[]> = {
  action: (g) => [
    `${g} action`,
    "action game no commentary",
    "action adventure gameplay",
    `${g} combat`,
  ],
  // … one entry per genre in config/genres.ts
};

3. State Architecture

┌────────────────────────────────────────────────────────────────────┐
│  EditorStore — "ytdescgen-editor-draft", v21                       │
│  - the draft: every form field (EditorData) + setter actions       │
│  - persists data only (editorDataOf); migrateEditorState           │
├────────────────────────────────────────────────────────────────────┤
│  ProfileStore — "ytdescgen-profiles", v3                           │
│  - profiles: Profile[] — channel fields (PROFILE_FIELDS)           │
├────────────────────────────────────────────────────────────────────┤
│  PresetStore — "ytdescgen-presets", v2                             │
│  - presets: GamePreset[] — per-game fields (PRESET_FIELDS)         │
├────────────────────────────────────────────────────────────────────┤
│  TemplateStore — "ytdescgen-templates", v2                         │
│  - templates: EditorTemplate[] — whole-form snapshots              │
├────────────────────────────────────────────────────────────────────┤
│  HistoryStore — "ytdescgen-history", v3                            │
│  - entries: HistoryEntry[] — one per video, newest first           │
│  - capped by the History Limit setting (10–500, default 100)       │
├────────────────────────────────────────────────────────────────────┤
│  SettingsStore — "ytdescgen-settings", v12                         │
│  - theme · hideScrollbars · singleKeyShortcuts · appLanguage       │
│  - titleFormat                                                     │
│  - description toggles · strictMode · copyAllIncludesTags · …      │
│  - healSettings on every load; consent and UI state never exported │
├────────────────────────────────────────────────────────────────────┤
│  LogStore — not persisted by Zustand                               │
│  - ≤ 2000 entries in memory; log-storage.ts mirrors each entry     │
│  - (web: localStorage "ytdescgen-logs"; Tauri: daily JSONL files)  │
├────────────────────────────────────────────────────────────────────┤
│  PendingInvalidStore — not persisted (v0.35)                       │
│  - typed text that is invalid and therefore not saved              │
├────────────────────────────────────────────────────────────────────┤
│  useRestoreDialog (utils/backup) — not persisted                   │
│  - the file waiting in the restore dialog                          │
└────────────────────────────────────────────────────────────────────┘

Every persisted store uses Zustand persist with createJSONStorage(() => localStorage) — the only store on every platform. The Tauri "mirror" file of earlier versions is gone (see PACKAGING.md for how its leftovers are recovered). Each store exports its version and its migration function (EDITOR_STORE_VERSION / migrateEditorState, PROFILE_STORE_VERSION / migrateProfilesState, PRESET_STORE_VERSION / migratePresetsState, TEMPLATE_STORE_VERSION / migrateTemplatesState, HISTORY_STORE_VERSION / migrateHistoryState, SETTINGS_STORE_VERSION / healSettings). The migrations are idempotent and shared with backup import, which replays them from the version a file records (section 5).

Profiles, presets and templates

src/config/library-fields.ts is the one list of which editor fields each kind of library item carries — the save forms, Apply, backups and imports all read it:

  • Profile = the channel: PROFILE_FIELDS (channel name, emails, social, rig, resolution (+ upscaled from) / fps / graphics preset, ad text, Vietnamese donate fields, community links).
  • Preset = the game: PRESET_FIELDS (names, genres, platform, store links and their types, publisher, content warnings, language patch, game version, art style, the skip-graphics-settings switch, playlist link).
  • Template = the whole form (every field since v1.0.0).
  • PER_VIDEO_FIELDS is what belongs to one video only (boss, chapter, timestamps, pinned comment, endings, …).

src/utils/library-apply.ts does everything that fills or clears the editor in one go, each with Undo (the editor is snapshotted first): apply a profile / preset / template, Next part (part number + 1, per-video fields cleared), New video, same game, and Start over (keeps the profile fields and starts in the Default Output Language). Applying a preset for another game also clears the per-video fields. QuickStart (top of the editor) remembers the last profile and preset (lastProfileId, lastPresetId) and asks before overwriting filled-in fields. src/utils/store-paste.ts routes a store link pasted anywhere in the editor to the right store field (matching PLATFORMS[].urlPattern), sets the platform for the first link, and fills an empty game name from the URL (url-extractors.ts).

Settings → engine options

renderAll is called from three places (the Output hook, the multi-language Output hook, BatchPage). Each used to hand-copy the same twelve settings fields into an options object, and they had drifted — BatchPage's copy silently omitted splitContactEmail and showThirdPartyAds, so Batch rendered a different description than Output from identical data.

src/hooks/use-render-options.ts is now the single mapping, with two guards:

  • Compile-time — buildRenderOptions builds a Required<SettingsRenderOptions>, so omitting a key is a type error.
  • Runtime — tests/hooks/render-options-parity.test.ts diffs the produced keys against SETTINGS_DERIVED_RENDER_KEYS in both directions.

RenderOptions is split accordingly: SettingsRenderOptions (from the user) plus RenderOptionOverrides (tEn, bilingualContentBlocks, year — decided per call site, since Output wants bilingual content blocks and Batch does not).

Validation state

Two sources, unioned by useStrictBlock, because neither alone is sufficient:

Source Catches Why it's needed
collectEditorIssues (pure, over EditorData) Saved values that fail validation Bad data from imports — ValidatedInput refuses to commit invalid text, so imports are the main way it gets in
PendingInvalidStore Typed text that is invalid and therefore not saved Otherwise a field showing a red error is invisible to every gate, because the store behind it holds the last good value

Both are filtered through isRelevantIssueId, so a field that isn't currently shown (adEmail / gameKeyEmail / copyrightEmail with split-email off, zaloGroupLink outside Vietnamese output) can never block on a value with no visible input to fix it. Strict Mode is opt-in; with it off, no gate blocks.

The three purpose emails (v1.1.0) go through one validator in both places: validatePurposeEmails (src/utils/validation.ts) is validateEmails plus a rule that the part before @ of every address contains one of the field's words from PURPOSE_EMAIL_KEYWORDS (src/config/contact-emails.ts). ContactEmailEditor uses it to refuse the value and lists the words in each field's help text; collectEditorIssues uses it on saved values, so an older address without a word shows up for Strict Mode rather than being rewritten.

The first implementation registered issues from the inputs themselves and cleared on unmount. It typechecked and had passing tests, and did nothing: the fields live on the Editor page while the gates live on Batch / Social / Output, so navigating away cleared every issue. Deriving from state removes the mount coupling entirely.

4. i18n Architecture

i18n/
├── index.ts              # i18next setup + SUPPORTED_LANGUAGES
└── locales/
    ├── en/
    │   ├── ui.json           # UI strings: buttons, labels, tooltips, errors
    │   └── templates.json    # Generated content: titles, description blocks, pinned comment, playlist, chapter keywords
    ├── vi/  ja/  es/  ko/  zh/  pt-BR/  id/
    │   ├── ui.json
    │   └── templates.json
    └── _schema.json      # the expected key list for both namespaces

npm run validate:locales checks every locale against _schema.json, and tests/i18n/locale-registration.test.ts checks the language list against the locale folders in both directions. Adding a language is two JSON files plus registration: the SupportedLanguage union, SUPPORTED_LANGUAGES, detectBrowserLanguage in settings-heal.ts, and the per-language records TypeScript enforces (the tag pools in tag-generator.ts, the channel-phrase patterns in channel-phrase.ts). The Turnstile gate page keeps its own strings and language list in worker/gate-i18n.ts. See I18N.md.

Lazy loading (v0.26+): only English is bundled into the main chunk — it is the fallbackLng and the engine's bilingual tEn translator, both of which must resolve synchronously. Every other language is fetched on first use as a Vite async chunk via i18next-resources-to-backend + dynamic import(). Generation paths gate on bundle readiness (useLanguagesReady hook / ensureLanguagesLoaded): an unloaded language would otherwise silently render English fallback output. A chunk that fails to fetch degrades to English and logs to the in-app Log page — it never hangs the UI.

UI language vs output language: independent. The UI follows SettingsStore.appLanguage (loaded before the first render in main.tsx, then kept in step with i18next by App.tsx); the generated text follows EditorStore.language. A new draft — first run or Start over — starts in SettingsStore.defaultOutputLanguage. Both settings default to the browser's language when it is supported.

5. Backup & Restore

Code in src/utils/backup/, UI in src/components/backup/ (BackupSection in Settings › Backup & restore, ExportBackupDialog, RestoreDialog). Format and rules: TECH-SPEC.md § 4.

Module Role
format.ts The _format: 2 envelope, _type values, section list, per-section store versions, dated file names
collect.ts Builds a backup of the chosen sections, a single-section export, or the History CSV
detect.ts Recognises every file any version has written (v2, v0.15–v0.38 envelopes, bare arrays, the old desktop data file) and reports each section with its version
sanitize.ts Store migrations first, then a strict whitelist; keeps device-local settings
restore.ts Plans the restore (new / same / changed per row) and applies the choice in one step, with undo
restore-flow.ts Gets a file into the dialog: Open dialog, drop, or one of the desktop app's own backups
restore-request.ts useRestoreDialog — the pending file, kept apart so the shell can watch it without loading the rest
auto-backup.ts Desktop automatic backups
startup.ts Tauri start-up: legacy-file recovery, then automatic backups (desktop)
Restore from file · drop · desktop backup list · "Review" on the legacy toast
        │  restore-flow.ts (openTextFile / readTextFile / appBackups.read)
        ▼
detect.ts — readBackupText → sections + recorded versions
        │  (logs, social, unknown or newer files are refused with a message)
        ▼
useRestoreDialog.open → RestoreDialog (lazy)
        │
        ▼
restore.ts — planRestore
        │  sanitize.ts: store migrations → whitelist
        │  per row: new / same / changed; Merge (newer | both) or Replace
        ▼
applyRestore — one synchronous write to every store → toast with Undo
   (desktop: a "before-restore" automatic backup is written first)

Export: ExportBackupDialog → collectBackup(chosen sections) → saveTextFile (ytdescgen-backup-YYYY-MM-DD.json); the library tabs and History export single sections (History also as CSV).

6. Web Delivery

The web build is served at https://ytgenerator.stream by a Cloudflare Worker (worker/, configured by wrangler.jsonc) that Cloudflare Workers Builds deploys from main. The Worker puts a Turnstile check in front of the app (verified server-side; a signed HttpOnly __Host-ytg_gate cookie remembers the pass for 24 hours), serves the prerendered legal pages at /legal/* to everyone, sets the security headers (a CSP per page type), and answers 429 to a client that sends too many requests (Workers Rate Limiting bindings, behind a WAF rate limiting rule at the zone). Agreeing to the terms on the gate page sets the ytg_terms cookie, which the app reads so a web visitor meets one blocking screen, not two. Build-time extras for the web only — static legal pages, /.well-known/security.txt, the cookieless Web Analytics beacon — come from build-plugins/. The desktop and Android builds use none of this and contain no analytics. Request flow, cookies, headers and operations: HOSTING.md.

7. Desktop Packaging (Tauri)

React app (src/), built with TAURI_ENV_PLATFORM set
        │
        ▼
┌────────────────────────────────────────┐
│             Tauri 2 shell              │
│  ┌──────────────────────────────────┐  │
│  │ System WebView                   │  │ ← renders the same React app
│  │ WebView2 · WKWebView · WebKitGTK │  │
│  │ Android System WebView           │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ Rust core (src-tauri/src)        │  │
│  │ lib.rs                           │  │ ← plugins, commands, tray, single instance
│  │ storage.rs                       │  │ ← backups and logs, by file name
│  │ file_dialog.rs                   │  │ ← Save / Open dialogs run in Rust
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘
        │
        ▼
  Release assets:
  - Windows: .msi and NSIS .exe
  - macOS (Apple silicon): .app.tar.gz
  - Linux: .AppImage, .deb, .rpm
  - Android: universal .apk

The webview never names a path. Since v1.0.0 the Rust side exposes only name-only commands for its own files (backup_* and log_* under the app data directory, recover_legacy_data) and two commands that open the native Save / Open dialog themselves (export_text_file, import_text_file: text formats only, imports capped at 20 MB). The capability file grants the webview only core:default, opener:default and (v1.5.1, for the zoom hotkeys' macOS/Linux polyfill) core:webview:allow-set-webview-zoom; the fs and shell plugins are gone. The JavaScript bridge is src/utils/native.ts, used by file-ops.ts (exports and imports on every platform), log-storage.ts and utils/backup/. Details: PACKAGING.md.

Tauri advantages over Electron:

  • No bundled Chromium — uses the system WebView, so installers stay a few megabytes (the v0.38.0 MSI was 4.6 MB)
  • Lower memory use
  • A Rust backend for native features, with a capability system that limits what the webview can call

8. Extensibility Points

What How to extend Files to touch
New language Add locales/{code}/ui.json + templates.json and register it (see section 4 and I18N.md); lazy-loaded automatically 2 locale files + types.ts, i18n/index.ts, settings-heal.ts, tag-generator.ts, channel-phrase.ts
New genre Add it to the Genre union (engine/types.ts) and config/genres.ts, its tag pool (GENRE_TAG_REGISTRY) and search term (GENRE_SEARCH_TERMS) to engine/tag-generator.ts — a test keeps the three lists in sync — and its genres.<id> label to every ui.json 3 + N locale files
New video type Add it to the VideoType union and config/video-types.ts, its videoTypes.<id> label to every ui.json, and its title, intro and pinned-comment greeting to every templates.json 2 + 2N locale files
New store / platform Add an entry to config/platforms.ts (URL pattern, optional normaliser, tagName); optionally a game-name extractor in utils/url-extractors.ts 1–2 files
New social link Add an entry to config/social-fields.ts and its social.<id> label to every ui.json 1 + N locale files
New rig field Add an entry to config/rig-fields.ts, its rig.<id> label to every ui.json and description.rigLabels.<id> to every templates.json 1 + 2N locale files
New cross-post platform Add an entry to config/social-platforms.ts (limit, hashtags, count mode) and its socialPost.platforms.<id> label 1 + N locale files
Custom template text Edit templates.json for the target language 1 file
Desktop feature Add a command in src-tauri/src/ (a module like storage.rs), register it in lib.rs's generate_handler!, add a typed wrapper in src/utils/native.ts. Never take a path from the webview 3 files
Persisted data shape Bump the store's exported version and add an idempotent step to its exported migration; backups replay it 1 file

9. Data Flow

User input (form, paste, Quick start, command palette)
       │
       ▼
EditorStore (Zustand, persist → localStorage "ytdescgen-editor-draft")
       │
       ├──→ useCurrentGeneratorInput → GeneratorInput
       │         │
       │         ▼
       │    useGeneratedOutput
       │      ├─ useLanguagesReady ([output language])
       │      ├─ i18n.getFixedT(language, "templates") + the English tEn
       │      ├─ useRenderOptions (Settings → RenderOptions)
       │      └─ renderAll → buildTitle · buildDescription · generateTags
       │                      → GeneratorOutput (memoized)
       │                               │
       │                               ▼
       │          Output page · Editor live preview · Social captions ·
       │          Copy (limits.ts gates) · Ctrl/⌘+Shift+C · command palette
       │                               │
       │                               └──→ HistoryStore.addEntry
       │                                    (Output page and Ctrl/⌘+S; one entry per video)
       │
       ├──→ Profile / Preset / Template stores (save from the editor;
       │    apply through library-apply.ts) ──→ localStorage
       │
       └──→ Desktop: auto-backup.ts ──→ backup_write ──→ <app data>/backups/

The multi-language Output tabs (useMultilangOutput) and BatchPage call renderAll themselves, once per language, with the same useRenderOptions mapping.