Architettura

Scopri dove si trova il codice e quali regole valgono prima di cambiare qualcosa di grande.

In breve

HolyArrs è un unico programma Go con l’app web incorporata. Serve l’app web e un’API JSON sulla porta 6262 e tiene i dati in 2 file SQLite nella cartella di configurazione. Comunica con i downloader, le Fonti (tramite Jackett o Prowlarr), i server multimediali, i canali di avviso e il server di metadati di HolyArrs.

Segui una richiesta. Qualcuno richiede un film su Explore (Esplora).

1. requests registra la richiesta.
2. Dopo l’approvazione, movies chiede le release a sources.
3. Le regole di scelta in mediafiles le valutano.
4. downloads manda la migliore al downloader.
5. Quando ha finito, mediafiles importa il file.
6. mediaservers e alerts vengono avvisati.

Mappa del codice

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 si trova nella radice del repository perché go:embed non può raggiungere una cartella superiore.

Dove trovare le cose

Vuoi cambiare	Guarda in
Come viene scelta una release	internal/mediafiles
Un client di downloader	internal/downloads, test di contratto in internal/downloads/conformance_test.go
Un canale di avviso	internal/alerts
Accesso, utenti, chiavi API	internal/accounts
La procedura guidata del primo avvio	internal/setup, app/frontend/src/routes/welcome
Importare un file completato (decompressione, tag, abbinamento)	internal/importer
Cartelle della Libreria, adozione e rinomina	internal/library
Come vengono scelte e ordinate righe e scaffali	internal/suggest
Quali parti dell’app sono attive	internal/core/parts
L’indirizzo di una pagina	app/frontend/src/routes/
Una migrazione	internal/core/database/migrations/
L’immagine Docker	deploy/Dockerfile

Le regole

I controlli in app/backend/tools/structurecheck fanno fallire la compilazione quando una regola viene infranta. Eseguili con la riga indicata in Test.

• Ordine dei livelli. Un modulo importa solo moduli di un livello inferiore, e solo il loro pacchetto radice. I moduli dello stesso livello non si importano mai a vicenda.
• Chiamare verso l’alto. Quando un modulo inferiore ha bisogno di qualcosa da uno superiore, quello superiore gli passa dati semplici, oppure quello inferiore definisce una piccola interfaccia che wiring.go riempie.
• L’SQL resta a casa. Solo i file store*.go di un modulo contengono SQL, e solo sulle sue tabelle. Per leggere le righe di un altro modulo, chiama il suo servizio.
• Le tabelle condivise appartengono a core. Raggiungi settings, schedules, secrets, jobs ed events tramite gli helper di core.
• Una sola uscita. Ogni chiamata verso l’esterno passa da core/outbound.
• Le funzioni in sospeso registrano un interruttore con core/startup. Finché è disattivato, la route non c’è e la pagina nasconde la funzione.
• Niente pacchetti ripostiglio. Niente util, common, shared o helpers.

L’ordine dei livelli è in Moduli.

Per esperti

Dentro un modulo

Ogni modulo del backend usa gli stessi nomi di file.

File	Contiene
routes.go	Le route dell’API, ciascuna con il permesso che richiede
service.go e i file per argomento	La logica che chiamano gli altri moduli
store.go, store_<topic>.go	Tutto l’SQL per le tabelle del modulo
types.go	I record del modulo

Lato web, lib/<module>/ contiene index.ts (ciò che gli altri moduli possono usare), le sue parti Svelte e i relativi test, più api.ts e state.svelte.ts solo quando il modulo ha chiamate o stato propri.

Pacchetti core

Core è l’impianto di base. Non contiene regole di prodotto e non importa nessun modulo.

Pacchetto	Contiene
core/database	Apertura e migrazione dei due file SQLite, helper per le query, helper per impostazioni ed eventi, campi di riga condivisi, riduzione della Cronologia
core/files	Helper per file e cartelle, spazio libero su disco
core/releasename	Qualità, gruppo e numeri degli episodi dal nome di una release
core/outbound	L’unico modo per chiamare server esterni, con controllo degli indirizzi
core/secrets	L’archivio delle chiavi e la rotazione delle chiavi
core/logs	Il log dell’app e le note sui crash
core/jobs	La coda dei processi, le pianificazioni e i cicli che ripartono dopo un crash
core/webserver	Impianto del router, URL base, compressione, push in tempo reale
core/startup	Utente di esecuzione, modalità a basso consumo di memoria, interruttori delle funzioni in sospeso, limite di memoria, parti
core/parts	Gli interruttori delle parti che ogni modulo controlla prima di servire o eseguire
core/model	Tipi condivisi, come attori e soggetti

Quando core deve toccare i dati di un modulo, il modulo registra un hook con core in wiring.go. La rotazione delle chiavi funziona così.

Dati

File	Contiene
holyarrs.db	La Libreria, le richieste, le impostazioni e tutto il resto che conta
holyarrs-events.db	La Cronologia e altre righe di eventi. Cresce e viene ridotto senza toccare il file principale

Le migrazioni sono file SQL numerati in core/database/migrations/main e core/database/migrations/events. Vengono eseguite all’avvio.

Correlati

• Moduli
• Contribuire
• Test