Architektura

Než změníš něco většího, zjisti, kde kód leží a jaká pravidla platí.

Stručně

HolyArrs je jeden program v Go s vestavěnou webovou aplikací. Na portu 6262 servíruje webovou aplikaci i JSON API a data ukládá do 2 souborů SQLite v konfigurační složce. Volá stahovače, zdroje (přes Jackett nebo Prowlarr), mediální servery, kanály upozornění a metadata server HolyArrs.

Sleduj jednu žádost. Někdo požádá o film na stránce Explore (objevovat).

1. requests zapíše žádost.
2. Po schválení se movies zeptá sources na release (nalezené verze).
3. Pravidla výběru v mediafiles je ohodnotí body.
4. downloads pošle nejlepší z nich do stahovače.
5. Až stahování skončí, mediafiles soubor naimportuje.
6. mediaservers a alerts se dozvědí, že je hotovo.

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 kořeni repozitáře, protože go:embed nedosáhne do nadřazené složky.

Kde co najdeš

Chceš změnit	Kam se podívat
Jak se vybírá release	internal/mediafiles
Klienta stahovače	internal/downloads, kontraktní testy v internal/downloads/conformance_test.go
Kanál upozornění	internal/alerts
Přihlášení, uživatele, API klíče	internal/accounts
Průvodce prvním spuštěním	internal/setup, app/frontend/src/routes/welcome
Import hotového souboru (rozbalení, tagy, přiřazení)	internal/importer
Složky knihovny, převzetí a přejmenování	internal/library
Jak se vybírají a řadí řádky a police	internal/suggest
Které části aplikace jsou zapnuté	internal/core/parts
Adresu stránky	app/frontend/src/routes/
Migraci	internal/core/database/migrations/
Docker image	deploy/Dockerfile

Pravidla

Kontroly v app/backend/tools/structurecheck shodí build, když se některé pravidlo poruší. Spustíš je příkazem z testování.

• Pořadí vrstev. Modul importuje jen moduly z nižší vrstvy, a to jen jejich kořenový balíček. Moduly na stejné vrstvě se navzájem neimportují.
• Volání nahoru. Když nižší modul potřebuje něco od vyššího, vyšší mu předá obyčejná data dolů, nebo nižší definuje malé rozhraní, které doplní wiring.go.
• SQL zůstává doma. SQL obsahují jen soubory store*.go daného modulu, a to jen nad jeho vlastními tabulkami. Řádky jiného modulu čti přes jeho službu.
• Sdílené tabulky patří jádru. K settings, schedules, secrets, jobs a events se dostaneš přes pomocné funkce jádra.
• Jediná cesta ven. Každé volání ven jde přes core/outbound.
• Odložené funkce se registrují s přepínačem v core/startup. Dokud je vypnutý, trasa neexistuje a stránka funkci skryje.
• Žádné odkladiště. Žádné balíčky util, common, shared ani helpers.

Pořadí vrstev najdeš v modulech.

Pro pokročilé

Uvnitř modulu

Každý backendový modul používá stejné názvy souborů.

Soubor	Obsahuje
routes.go	Trasy API, každou s oprávněním, které potřebuje
service.go a soubory podle témat	Logiku, kterou volají jiné moduly
store.go, store_<topic>.go	Veškeré SQL pro vlastní tabulky modulu
types.go	Záznamy modulu

Na straně webu obsahuje lib/<module>/ soubor index.ts (co smějí používat jiné moduly), své Svelte části s testy a api.ts a state.svelte.ts jen tehdy, když má vlastní volání nebo stav.

Balíčky jádra

Jádro jsou jen rozvody. Neobsahuje žádná pravidla produktu a neimportuje žádný modul.

Balíček	Obsahuje
core/database	Otevření a migrace obou souborů SQLite, pomocné funkce pro dotazy, nastavení a události, sdílená pole řádků, ořezávání historie
core/files	Pomocné funkce pro soubory a složky, volné místo na disku
core/releasename	Kvalitu, skupinu a čísla epizod z názvu releasu
core/outbound	Jediná cesta k vnějším serverům, s kontrolou adres
core/secrets	Úložiště klíčů a výměnu klíčů
core/logs	Log aplikace a poznámky o pádech
core/jobs	Frontu úloh, plány a smyčky, které se po pádu znovu spustí
core/webserver	Směrování, URL base, kompresi, živé zasílání
core/startup	Uživatele spuštění, režim s nízkou pamětí, přepínače odložených funkcí, limit paměti, části
core/parts	Přepínače částí, na které se před spuštěním nebo obsluhou ptá každý modul
core/model	Sdílené typy, například aktéry a subjekty

Když se jádro musí dotknout dat modulu, modul u něj v wiring.go zaregistruje hák. Takhle funguje výměna klíčů.

Data

Soubor	Obsahuje
holyarrs.db	Knihovnu, žádosti, nastavení a všechno ostatní důležité
holyarrs-events.db	Historii a další řádky událostí. Roste a ořezává se, aniž by se sahalo na hlavní soubor

Migrace jsou číslované soubory SQL v core/database/migrations/main a core/database/migrations/events. Spouštějí se při startu.

Související

• Moduly
• Přispívání
• Testování