Architektúra

Zisti, kde kód býva a aké pravidlá platia, skôr než zmeníš niečo veľké.

Skrátene

HolyArrs je jeden program v Go s vstavanou webovou aplikáciou. Servíruje webovú aplikáciu a API s JSON na porte 6262 a dáta drží v 2 súboroch SQLite v konfiguračnom priečinku. Volá sťahovače, zdroje (cez Jackett alebo Prowlarr), mediálne servery, kanály upozornení a metadátový server HolyArrs.

Sleduj jednu žiadosť. Niekto požiada o film v Objavovaní.

1. requests zaznamená žiadosť.
2. Po schválení movies požiada sources o releasy.
3. Pravidlá výberu v mediafiles ich ohodnotia.
4. downloads pošle najlepší sťahovaču.
5. Keď sa sťahovanie dokončí, mediafiles súbor importuje.
6. mediaservers a alerts sa dozvedia o novinke.

Mapa kódu

app/backend/cmd/holyarrs/            main.go starts the program; wiring.go builds the modules and joins them
app/backend/internal/<module>/       one flat folder per module
app/backend/internal/core/           plumbing every module may use
app/backend/tools/                   dev-only programs
app/frontend/                        the SvelteKit web app; embed.go bundles its build
app/frontend/src/routes/<page>/      thin pages that combine module parts
app/frontend/src/lib/<module>/       each module's web code
app/frontend/src/lib/ui/             parts used by 2 or more modules, and nothing else
app/frontend/src/lib/core/           server client, app state, helpers
app/tests/                           end-to-end tests (Playwright)
deploy/                              the Dockerfile and release scripts
docs/                                guides and these pages

go.mod leží v koreni repozitára, pretože go:embed nedosiahne do nadradeného priečinka.

Kde čo nájdeš

Chceš zmeniť	Pozri do
Ako sa vyberá release	internal/mediafiles
Klient sťahovača	internal/downloads, kontraktové testy v internal/downloads/conformance_test.go
Kanál upozornení	internal/alerts
Prihlásenie, používatelia, kľúče API	internal/accounts
Sprievodca prvým spustením	internal/setup, app/frontend/src/routes/welcome
Import hotového súboru (rozbalenie, tagy, priradenie)	internal/importer
Priečinky knižnice, prevzatie a premenovanie	internal/library
Ako sa vyberajú a radia riadky a police	internal/suggest
Ktoré časti aplikácie sú zapnuté	internal/core/parts
Adresa stránky	app/frontend/src/routes/
Migrácia	internal/core/database/migrations/
Docker image	deploy/Dockerfile

Pravidlá

Kontroly v app/backend/tools/structurecheck zlyhajú pri zostavení, ak sa niektoré pravidlo poruší. Spustíš ich príkazom zo stránky Testovanie.

• Poradie vrstiev. Modul importuje iba moduly z nižšej vrstvy, a to iba ich koreňový balík. Moduly na rovnakej vrstve sa navzájom neimportujú.
• Volanie smerom nahor. Keď nižší modul potrebuje niečo z vyššieho, vyšší mu pošle obyčajné dáta nadol, alebo nižší definuje malé rozhranie, ktoré vyplní wiring.go.
• SQL zostáva doma. SQL majú iba súbory store*.go daného modulu a iba nad jeho vlastnými tabuľkami. Riadky iného modulu prečítaš volaním jeho služby.
• Spoločné tabuľky patria core. K settings, schedules, secrets, jobs a events pristupuj cez pomocné funkcie core.
• Jedna cesta von. Každé volanie von ide cez core/outbound.
• Pozdržané funkcie zaregistrujú prepínač v core/startup. Kým je vypnutý, cesta neexistuje a stránka funkciu skryje.
• Žiadne zberné balíky. Žiadne util, common, shared ani helpers.

Poradie vrstiev nájdeš v stránke Moduly.

Pre expertov

Vnútri modulu

Každý backendový modul používa rovnaké názvy súborov.

Súbor	Obsahuje
routes.go	Cesty API, každá s oprávnením, ktoré potrebuje
service.go a súbory podľa tém	Logiku, ktorú volajú iné moduly
store.go, store_<topic>.go	Všetko SQL pre vlastné tabuľky modulu
types.go	Záznamy modulu

Na strane webu lib/<module>/ obsahuje index.ts (čo smú používať iné moduly), svoje súčasti v Svelte a ich testy, a api.ts a state.svelte.ts iba vtedy, keď má vlastné volania alebo stav.

Balíky core

Core je technický základ. Neobsahuje pravidlá produktu a neimportuje žiadny modul.

Balík	Obsahuje
core/database	Otváranie a migrácie oboch súborov SQLite, pomocné funkcie pre dotazy, nastavenia a udalosti, spoločné polia riadkov, orezávanie histórie
core/files	Pomocné funkcie pre súbory a priečinky, voľné miesto na disku
core/releasename	Kvalita, skupina a čísla epizód z názvu releasu
core/outbound	Jediný spôsob, ako volať vonkajšie servery, s kontrolou adries
core/secrets	Úložisko kľúčov a rotácia kľúčov
core/logs	Log aplikácie a poznámky o páde
core/jobs	Fronta úloh, plány a slučky, ktoré sa po páde znova spustia
core/webserver	Smerovanie, URL base, kompresia, živé posielanie
core/startup	Používateľ, pod ktorým beží program, režim s nízkou pamäťou, pozdržané prepínače, limit pamäte, časti
core/parts	Prepínače častí, na ktoré sa pýta každý modul, skôr než začne slúžiť alebo bežať
core/model	Spoločné typy, napríklad aktéri a subjekty

Keď sa core musí dotknúť dát modulu, modul zaregistruje v core hook vo wiring.go. Takto funguje rotácia kľúčov.

Dáta

Súbor	Obsahuje
holyarrs.db	Knižnicu, žiadosti, nastavenia a všetko ostatné, čo je dôležité
holyarrs-events.db	Históriu a ďalšie riadky udalostí. Rastie a orezáva sa bez zásahu do hlavného súboru

Migrácie sú číslované súbory SQL v core/database/migrations/main a core/database/migrations/events. Spúšťajú sa pri štarte.

Súvisiace stránky

• Moduly
• Prispievanie
• Testovanie