From 2a674c6bcdee5203011aa46ae5f361b52df643dd Mon Sep 17 00:00:00 2001
From: Gronod <gordon@i3omb.com>
Date: Sun, 17 May 2026 12:03:49 +0100
Subject: [PATCH] docs: replace ASCII art diagrams with Mermaid (renders
 natively in Gitea)

---
 docs/ARCHITECTURE.md | 139 +++++++++++++++++++++++--------------------
 1 file changed, 73 insertions(+), 66 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 0fbfad9..6226984 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -35,45 +35,46 @@ Admin users can view all users' downloads, see server status, cache statistics,
 
 ### High-Level Architecture
 
-```
-┌─────────────────────────────────────────────────────┐
-│                    Browser (SPA)                     │
-│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
-│  │  Login   │  │Dashboard │  │  Status Panel     │  │
-│  │  Form    │  │  Cards   │  │  (Admin only)     │  │
-│  └────┬─────┘  └────┬─────┘  └───────┬───────────┘  │
-│       │              │                │              │
-└───────┼──────────────┼────────────────┼──────────────┘
-        │ POST /login  │ GET /user-     │ GET /status
-        │              │ downloads      │
-        ▼              ▼                ▼
-┌─────────────────────────────────────────────────────┐
-│                Express Server (:3001)                 │
-│  ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────────┐  │
-│  │  Auth  │ │Dashboard │ │ Emby   │ │  Static    │  │
-│  │ Routes │ │  Routes  │ │ Routes │ │  Files     │  │
-│  └────┬───┘ └────┬─────┘ └────┬───┘ └────────────┘  │
-│       │          │            │                       │
-│  ┌────┴──────────┴────────────┴──────────────────┐   │
-│  │             Utilities Layer                    │   │
-│  │  ┌────────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │   │
-│  │  │ Poller │ │ Cache  │ │Config│ │qBittorrent│ │   │
-│  │  └───┬────┘ └────────┘ └──────┘ └──────────┘ │   │
-│  └──────┼────────────────────────────────────────┘   │
-└─────────┼────────────────────────────────────────────┘
-          │ HTTP/API calls
-          ▼
-┌──────────────────────────────────────────────────────┐
-│              External Services                        │
-│  ┌──────────┐ ┌────────┐ ┌────────┐ ┌────────────┐  │
-│  │ SABnzbd  │ │ Sonarr │ │ Radarr │ │qBittorrent │  │
-│  │ (Usenet) │ │ (TV)   │ │(Movie) │ │ (Torrent)  │  │
-│  └──────────┘ └────────┘ └────────┘ └────────────┘  │
-│  ┌──────────────────────────────────────────────┐    │
-│  │              Emby / Jellyfin                  │    │
-│  │          (Authentication + User DB)           │    │
-│  └──────────────────────────────────────────────┘    │
-└──────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+    subgraph Browser["Browser (SPA)"]
+        login["Login Form"]
+        dash["Dashboard Cards"]
+        status["Status Panel\n(Admin only)"]
+    end
+
+    subgraph Server["Express Server (:3001)"]
+        auth_r["Auth Routes\n/api/auth"]
+        dash_r["Dashboard Routes\n/api/dashboard"]
+        emby_r["Emby Routes\n/api/emby"]
+        static_f["Static Files\npublic/"]
+
+        subgraph Utils["Utilities Layer"]
+            poller["Poller"]
+            cache["Cache"]
+            config["Config"]
+            qbt["qBittorrent"]
+        end
+    end
+
+    subgraph Ext["External Services"]
+        sab["SABnzbd\n(Usenet)"]
+        sonarr["Sonarr\n(TV)"]
+        radarr["Radarr\n(Movies)"]
+        qbittorrent["qBittorrent\n(Torrent)"]
+        emby["Emby / Jellyfin\n(Auth + User DB)"]
+    end
+
+    login -->|"POST /login"| auth_r
+    dash  -->|"GET /stream SSE\nGET /user-downloads"| dash_r
+    status -->|"GET /status"| dash_r
+
+    auth_r -->|"authenticate"| emby
+    emby_r -->|"proxy"| emby
+    dash_r --> Utils
+    poller -->|"HTTP/API calls"| sab & sonarr & radarr
+    qbt    -->|"HTTP/API calls"| qbittorrent
+    static_f -.->|"serve"| Browser
 ```
 
 ---
@@ -361,22 +362,21 @@ The core logic in `dashboard.js` matches raw download client data to *arr servic
 
 For each download item (SABnzbd slot or qBittorrent torrent):
 
-```
-1. Try Sonarr QUEUE match (by title substring)
-   → resolve series via seriesMap (embedded in queue record)
-   → extract user tag → check tag matches requesting user
+```mermaid
+flowchart TD
+    Start(["Download item"]) --> SQ{"Sonarr QUEUE\nmatch (title)"}
+    SQ -->|yes| SQR["Resolve series via seriesMap\nextract user tag → check match"]
+    SQ -->|no|  RQ{"Radarr QUEUE\nmatch (title)"}
+    RQ -->|yes| RQR["Resolve movie via moviesMap\nextract user tag → check match"]
+    RQ -->|no|  SH{"Sonarr HISTORY\nmatch (title)"}
+    SH -->|yes| SHR["Resolve series via seriesId\nextract user tag → check match"]
+    SH -->|no|  RH{"Radarr HISTORY\nmatch (title)"}
+    RH -->|yes| RHR["Resolve movie via movieId\nextract user tag → check match"]
+    RH -->|no|  Skip(["Skip — unmatched"])
 
-2. Try Radarr QUEUE match (by title substring)
-   → resolve movie via moviesMap (embedded in queue record)
-   → extract user tag → check tag matches requesting user
-
-3. Try Sonarr HISTORY match (by title substring)
-   → resolve series via seriesMap (from queue) using seriesId
-   → extract user tag → check tag matches requesting user
-
-4. Try Radarr HISTORY match (by title substring)
-   → resolve movie via moviesMap (from queue) using movieId
-   → extract user tag → check tag matches requesting user
+    SQR & RQR & SHR & RHR --> Tagged{"Tag matches\nrequesting user?"}
+    Tagged -->|yes| Include(["Include in response"])
+    Tagged -->|no|  Skip
 ```
 
 ### Title Matching
@@ -593,18 +593,25 @@ The frontend is a **vanilla JavaScript SPA** with no build step. All logic resid
 
 ### UI States
 
-```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│ Splash Screen│────▶│  Login Form  │────▶│  Dashboard   │
-│ (on load)    │     │ (if no       │     │ (after auth) │
-│              │     │  session)    │     │              │
-└──────────────┘     └──────────────┘     └──────────────┘
-                                                │
-                                          ┌─────┴─────┐
-                                          │  Status   │
-                                          │  Panel    │
-                                          │ (admin)   │
-                                          └───────────┘
+```mermaid
+stateDiagram-v2
+    [*] --> SplashScreen : Page load
+    SplashScreen --> LoginForm : No session
+    SplashScreen --> Dashboard : Valid session
+    LoginForm --> Dashboard : Auth success
+    Dashboard --> LoginForm : Logout
+
+    state Dashboard {
+        [*] --> ActiveDownloads
+        ActiveDownloads --> ActiveDownloads : SSE update
+
+        state StatusPanel {
+            [*] --> Closed
+            Closed --> Open : Click Status (admin)
+            Open --> Closed : Click close
+            Open --> Open : 5s refresh
+        }
+    }
 ```
 
 ### Key Frontend Functions