Gandalf/sofarr
1
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases 15 Wiki Activity

docs: merge Mermaid diagram migration from develop

Browse Source
This commit is contained in:
Gronod
2026-05-17 12:04:00 +01:00
parent da0898f52a 2a674c6bcd
commit ffd9e84a00
1 changed files with 73 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
docs/ARCHITECTURE.md
View File

@@ -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