Architektur

Finde heraus, wo der Code liegt und welche Regeln gelten, bevor du etwas Großes änderst.

Die Kurzfassung

HolyArrs ist ein einziges Go-Programm mit eingebauter Web-App. Es liefert die Web-App und eine JSON-API auf Port 6262 aus und hält seine Daten in 2 SQLite-Dateien im Konfigurationsordner. Nach außen spricht es mit Downloadern, Quellen (über Jackett oder Prowlarr), Medienservern, Benachrichtigungskanälen und dem Metadaten-Server von HolyArrs.

Verfolge eine Anfrage. Jemand fragt unter Entdecken einen Film an.

1. requests hält die Anfrage fest.
2. Nach der Genehmigung fragt movies bei sources nach Releases.
3. Die Auswahlregeln in mediafiles bewerten sie.
4. downloads schickt das beste an den Downloader.
5. Wenn der Download fertig ist, importiert mediafiles die Datei.
6. mediaservers und alerts erfahren davon.

Code-Übersicht

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 liegt im Wurzelordner des Repos, weil go:embed keinen übergeordneten Ordner erreicht.

Wo du was findest

Du willst ändern	Schau in
Wie ein Release ausgewählt wird	internal/mediafiles
Einen Downloader-Client	internal/downloads, Vertragstests in internal/downloads/conformance_test.go
Einen Benachrichtigungskanal	internal/alerts
Anmeldung, Benutzer, API-Schlüssel	internal/accounts
Den Assistenten für den ersten Start	internal/setup, app/frontend/src/routes/welcome
Den Import einer fertigen Datei (Entpacken, Tags, Zuordnung)	internal/importer
Bibliotheksordner, Übernehmen und Umbenennen	internal/library
Wie Reihen und Regale ausgewählt und sortiert werden	internal/suggest
Welche Bereiche der App eingeschaltet sind	internal/core/parts
Eine Seitenadresse	app/frontend/src/routes/
Eine Migration	internal/core/database/migrations/
Das Docker-Image	deploy/Dockerfile

Die Regeln

Prüfungen in app/backend/tools/structurecheck lassen den Build scheitern, sobald eine Regel verletzt ist. Führe sie mit der Zeile unter Testen aus.

• Reihenfolge der Schichten. Ein Modul importiert nur Module einer tieferen Schicht, und von ihnen nur das Wurzelpaket. Module derselben Schicht importieren sich nie gegenseitig.
• Aufrufe nach oben. Braucht ein tieferes Modul etwas von einem höheren, reicht das höhere einfache Daten nach unten. Oder das tiefere legt ein kleines Interface fest, das wiring.go füllt.
• SQL bleibt zu Hause. SQL steht nur in den eigenen store*.go-Dateien eines Moduls und greift nur auf dessen eigene Tabellen zu. Um die Zeilen eines anderen Moduls zu lesen, rufst du dessen Service auf.
• Gemeinsame Tabellen gehören core. settings, schedules, secrets, jobs und events erreichst du über die Helfer von core.
• Ein Weg nach draußen. Jeder Aufruf nach außen läuft über core/outbound.
• Zurückgestellte Funktionen melden einen Schalter bei core/startup an. Solange er aus ist, gibt es die Route nicht und die Seite blendet die Funktion aus.
• Keine Sammelpakete. Kein util, common, shared oder helpers.

Die Reihenfolge der Schichten steht unter Module.

Für Fortgeschrittene

In einem Modul

Jedes Backend-Modul verwendet dieselben Dateinamen.

Datei	Enthält
routes.go	API-Routen, jede mit der Berechtigung, die sie braucht
service.go und Themendateien	Logik, die andere Module aufrufen
store.go, store_<topic>.go	Das gesamte SQL für die eigenen Tabellen des Moduls
types.go	Die Datensätze des Moduls

Auf der Web-Seite enthält lib/<module>/ die Datei index.ts (was andere Module verwenden dürfen), seine Svelte-Bausteine und deren Tests. api.ts und state.svelte.ts kommen nur dazu, wenn das Modul eigene Aufrufe oder eigenen Zustand hat.

Core-Pakete

Core ist reine Infrastruktur. Es enthält keine Produktregeln und importiert kein Modul.

Paket	Enthält
core/database	Öffnen und Migrieren beider SQLite-Dateien, Abfragehelfer, Helfer für Einstellungen und Ereignisse, gemeinsame Zeilenfelder, Kürzen des Verlaufs
core/files	Helfer für Dateien und Ordner, freier Speicherplatz
core/releasename	Qualität, Gruppe und Folgennummern aus einem Release-Namen
core/outbound	Der eine Weg zu Servern außerhalb, mit Adressprüfungen
core/secrets	Der Schlüsselspeicher und der Schlüsselwechsel
core/logs	Das App-Log und Absturznotizen
core/jobs	Die Aufgabenwarteschlange, Zeitpläne und die Schleifen, die nach einem Absturz neu starten
core/webserver	Router-Infrastruktur, URL base, Komprimierung, Live-Push
core/startup	Ausführender Benutzer, Modus für wenig Arbeitsspeicher, Schalter für zurückgestellte Funktionen, Arbeitsspeicherlimit, Bereiche
core/parts	Die Bereichsschalter, die jedes Modul abfragt, bevor es etwas ausliefert oder ausführt
core/model	Gemeinsame Typen wie Akteure und Subjekte

Muss core Moduldaten anfassen, meldet das Modul in wiring.go einen Hook bei core an. So funktioniert der Schlüsselwechsel.

Daten

Datei	Enthält
holyarrs.db	Die Bibliothek, Anfragen, Einstellungen und alles andere, was zählt
holyarrs-events.db	Verlauf und andere Ereigniszeilen. Sie wächst und wird gekürzt, ohne die Hauptdatei anzufassen

Migrationen sind nummerierte SQL-Dateien in core/database/migrations/main und core/database/migrations/events. Sie laufen beim Start.

Verwandte Seiten

• Module
• Mitwirken
• Testen