Arkitektur

Find ud af, hvor koden ligger, og hvilke regler der gælder, før du ændrer noget stort.

Kort fortalt

HolyArrs er ét Go-program med web-appen bygget ind. Det serverer web-appen og et JSON-API på port 6262 og gemmer sine data i 2 SQLite-filer i konfigurationsmappen. Det kalder ud til downloadere, kilder (gennem Jackett eller Prowlarr), medieservere, beskedkanaler og HolyArrs’ metadataserver.

Følg et enkelt ønske. Nogen ønsker en film i Explore (udforsk).

1. requests registrerer ønsket.
2. Efter godkendelse beder movies sources om releases.
3. Udvalgsreglerne i mediafiles giver dem point.
4. downloads sender det bedste til downloaderen.
5. Når det er færdigt, importerer mediafiles filen.
6. mediaservers og alerts får besked.

Kodekort

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 ligger i roden af repoet, fordi go:embed ikke kan nå en overordnet mappe.

Hvor du finder tingene

Du vil ændre	Kig i
Hvordan et release vælges	internal/mediafiles
En downloaderklient	internal/downloads, kontrakttests i internal/downloads/conformance_test.go
En beskedkanal	internal/alerts
Login, brugere, API-nøgler	internal/accounts
Guiden ved første start	internal/setup, app/frontend/src/routes/welcome
Import af en færdig fil (udpakning, tags, matchning)	internal/importer
Biblioteksmapper, overtagelse og omdøbning	internal/library
Hvordan rækker og hylder vælges og sorteres	internal/suggest
Hvilke dele af appen der er slået til	internal/core/parts
En sideadresse	app/frontend/src/routes/
En migrering	internal/core/database/migrations/
Docker-imaget	deploy/Dockerfile

Reglerne

Tjek i app/backend/tools/structurecheck får buildet til at fejle, når en regel brydes. Kør dem med linjen i Testning.

• Lagrækkefølge. Et modul importerer kun moduler på et lavere lag, og kun deres rodpakke. Moduler på samme lag importerer aldrig hinanden.
• Kald opad. Når et lavere modul har brug for noget fra et højere, sender det højere modul almindelige data ned, eller det lavere definerer en lille grænseflade, som wiring.go udfylder.
• SQL bliver hjemme. Kun et moduls egne store*.go-filer indeholder SQL, og kun over modulets egne tabeller. Hvis du vil læse et andet moduls rækker, så kald dets service.
• Delte tabeller tilhører core. Brug core-hjælperne til settings, schedules, secrets, jobs og events.
• Kun én vej ud. Alle kald udad går gennem core/outbound.
• Tilbageholdte funktioner registrerer en kontakt hos core/startup. Så længe den er slået fra, findes ruten ikke, og siden skjuler funktionen.
• Ingen samlepakker. Ingen util, common, shared eller helpers.

Lagrækkefølgen står i Moduler.

For erfarne

Inde i et modul

Alle backend-moduler bruger de samme filnavne.

Fil	Indeholder
routes.go	API-ruter, hver med den rettighed, den kræver
service.go og emnefiler	Logik, som andre moduler kalder
store.go, store_<topic>.go	Al SQL til modulets egne tabeller
types.go	Modulets records

På websiden indeholder lib/<module>/ filen index.ts (det, andre moduler må bruge), modulets Svelte-dele og deres tests, samt api.ts og state.svelte.ts kun når modulet har egne kald eller egen tilstand.

Core-pakker

Core er rørføringen. Den indeholder ingen produktregler og importerer ingen moduler.

Pakke	Indeholder
core/database	Åbning og migrering af begge SQLite-filer, forespørgselshjælpere, hjælpere til indstillinger og hændelser, fælles rækkefelter, beskæring af historik
core/files	Fil- og mappehjælpere, ledig diskplads
core/releasename	Kvalitet, gruppe og afsnitsnumre ud fra et release-navn
core/outbound	Den ene vej til at kalde eksterne servere, med adressetjek
core/secrets	Nøglelageret og nøglerotation
core/logs	Applogen og nedbrudsnoter
core/jobs	Opgavekøen, tidsplaner og de løkker, der genstarter efter et nedbrud
core/webserver	Router-rørføring, URL base, komprimering, live push
core/startup	Kør-som-bruger, tilstand til lav hukommelse, tilbageholdte kontakter, hukommelsesgrænse, dele
core/parts	Delkontakterne, som alle moduler spørger, før de serverer eller kører
core/model	Fælles typer som aktører og emner

Når core skal røre et moduls data, registrerer modulet en hook hos core i wiring.go. Nøglerotation virker på den måde.

Data

Fil	Indeholder
holyarrs.db	Biblioteket, ønsker, indstillinger og alt andet, der betyder noget
holyarrs-events.db	Historik og andre hændelsesrækker. Den vokser og bliver beskåret uden at røre hovedfilen

Migreringer er nummererede SQL-filer i core/database/migrations/main og core/database/migrations/events. De kører ved start.

Se også

• Moduler
• Bidrag
• Testning