Architektura

Zanim zmienisz coś większego, sprawdź, gdzie leży kod i jakie reguły obowiązują.

W skrócie

HolyArrs to jeden program w Go z wbudowaną aplikacją webową. Udostępnia aplikację webową i API JSON na porcie 6262, a dane trzyma w 2 plikach SQLite w folderze konfiguracji. Łączy się z downloaderami, źródłami (przez Jackett lub Prowlarr), serwerami multimediów, kanałami powiadomień i serwerem metadanych HolyArrs.

Prześledź jedną prośbę. Ktoś prosi o film w Explore (odkrywaj).

1. requests zapisuje prośbę.
2. Po zatwierdzeniu movies prosi sources o releasy.
3. Reguły wyboru w mediafiles oceniają je punktami.
4. downloads wysyła najlepszy do downloadera.
5. Gdy pobieranie się skończy, mediafiles importuje plik.
6. mediaservers i alerts dostają informację.

Mapa kodu

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

Plik go.mod leży w głównym folderze repo, bo go:embed nie sięga do folderu nadrzędnego.

Gdzie co znaleźć

Chcesz zmienić	Zajrzyj do
Sposób wyboru release’u	internal/mediafiles
Klienta downloadera	internal/downloads, testy kontraktu w internal/downloads/conformance_test.go
Kanał powiadomień	internal/alerts
Logowanie, użytkowników, klucze API	internal/accounts
Kreator pierwszego uruchomienia	internal/setup, app/frontend/src/routes/welcome
Import gotowego pliku (rozpakowanie, tagi, dopasowanie)	internal/importer
Foldery biblioteki, przejmowanie i zmiana nazw	internal/library
Wybór i kolejność wierszy i półek	internal/suggest
Które moduły aplikacji są włączone	internal/core/parts
Adres strony	app/frontend/src/routes/
Migrację	internal/core/database/migrations/
Image Dockera	deploy/Dockerfile

Reguły

Kontrole w app/backend/tools/structurecheck przerywają build, gdy któraś reguła zostanie złamana. Uruchomisz je poleceniem ze strony Testy.

• Kolejność warstw. Moduł importuje tylko moduły z niższej warstwy i tylko ich główny pakiet. Moduły z tej samej warstwy nigdy nie importują się nawzajem.
• Wołanie w górę. Gdy niższy moduł potrzebuje czegoś z wyższego, wyższy przekazuje w dół zwykłe dane albo niższy definiuje mały interfejs, który uzupełnia wiring.go.
• SQL zostaje u siebie. SQL trzymają tylko własne pliki store*.go modułu i tylko dla jego własnych tabel. Żeby odczytać wiersze innego modułu, wywołaj jego serwis.
• Wspólne tabele należą do core. Do settings, schedules, secrets, jobs i events sięgaj przez helpery z core.
• Jedno wyjście. Każde wywołanie na zewnątrz idzie przez core/outbound.
• Funkcje wstrzymane rejestrują przełącznik w core/startup. Dopóki jest wyłączony, nie ma trasy, a strona ukrywa funkcję.
• Żadnych pakietów „na wszystko“. Żadnych util, common, shared ani helpers.

Kolejność warstw jest na stronie Moduły.

Dla zaawansowanych

Wnętrze modułu

Każdy moduł backendu używa tych samych nazw plików.

Plik	Zawiera
routes.go	Trasy API, każda z uprawnieniem, którego wymaga
service.go i pliki tematyczne	Logikę, którą wywołują inne moduły
store.go, store_<topic>.go	Cały SQL dla własnych tabel modułu
types.go	Rekordy modułu

Po stronie webowej lib/<module>/ zawiera index.ts (to, czego mogą używać inne moduły), części w Svelte i ich testy, a api.ts i state.svelte.ts tylko wtedy, gdy moduł ma własne wywołania lub stan.

Pakiety core

Core to techniczne zaplecze. Nie zawiera reguł produktu i nie importuje żadnego modułu.

Pakiet	Zawiera
core/database	Otwieranie i migrowanie obu plików SQLite, helpery zapytań, helpery ustawień i zdarzeń, wspólne pola wierszy, przycinanie historii
core/files	Helpery plików i folderów, wolne miejsce na dysku
core/releasename	Jakość, grupa i numery odcinków z nazwy release’u
core/outbound	Jedyny sposób wołania zewnętrznych serwerów, ze sprawdzaniem adresów
core/secrets	Magazyn kluczy i rotacja kluczy
core/logs	Log aplikacji i notatki o awariach
core/jobs	Kolejka zadań, harmonogramy i pętle, które uruchamiają się ponownie po awarii
core/webserver	Obsługa routera, URL base, kompresja, wysyłanie na żywo
core/startup	Użytkownik uruchamiający, tryb niskiego zużycia pamięci, przełączniki funkcji wstrzymanych, limit pamięci, moduły
core/parts	Przełączniki modułów, o które pyta każdy moduł, zanim zacznie działać
core/model	Wspólne typy, takie jak aktorzy i podmioty

Gdy core musi dotknąć danych modułu, moduł rejestruje w core hook w wiring.go. Tak działa rotacja kluczy.

Dane

Plik	Zawiera
holyarrs.db	Bibliotekę, prośby, ustawienia i wszystko inne, co ważne
holyarrs-events.db	Historię i inne wiersze zdarzeń. Rośnie i jest przycinany bez ruszania głównego pliku

Migracje to numerowane pliki SQL w core/database/migrations/main i core/database/migrations/events. Uruchamiają się przy starcie.

Powiązane strony

• Moduły
• Współtworzenie
• Testy