Architecture

Repérez où se trouve le code et quelles règles s’appliquent avant de faire un gros changement.

En bref

HolyArrs est un seul programme Go qui contient l’application web. Il sert l’application web et une API JSON sur le port 6262, et garde ses données dans 2 fichiers SQLite dans le dossier de configuration. Il appelle les clients de téléchargement, les sources (via Jackett ou Prowlarr), les serveurs multimédias, les canaux d’alerte et le serveur de métadonnées HolyArrs.

Suivez une demande. Quelqu’un demande un film dans Explore (Explorer).

1. requests enregistre la demande.
2. Après approbation, movies demande des releases à sources.
3. Les règles de sélection dans mediafiles leur donnent un score.
4. downloads envoie la meilleure au client de téléchargement.
5. Quand le téléchargement est terminé, mediafiles importe le fichier.
6. mediaservers et alerts sont prévenus.

Carte du code

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 est à la racine du dépôt, car go:embed ne peut pas atteindre un dossier parent.

Où trouver quoi

Vous voulez modifier	Regardez dans
La façon dont une release est choisie	internal/mediafiles
Un client de téléchargement	internal/downloads, tests de contrat dans internal/downloads/conformance_test.go
Un canal d’alerte	internal/alerts
La connexion, les utilisateurs, les clés API	internal/accounts
L’assistant de premier lancement	internal/setup, app/frontend/src/routes/welcome
L’import d’un fichier terminé (décompression, étiquettes, correspondance)	internal/importer
Les dossiers de bibliothèque, l’adoption et le renommage	internal/library
Le choix et l’ordre des rangées et des étagères	internal/suggest
Les modules de l’application qui sont activés	internal/core/parts
L’adresse d’une page	app/frontend/src/routes/
Une migration	internal/core/database/migrations/
L’image Docker	deploy/Dockerfile

Les règles

Les contrôles dans app/backend/tools/structurecheck font échouer le build dès qu’une règle n’est pas respectée. Lancez-les avec la ligne donnée dans Tests.

• Ordre des couches. Un module importe seulement des modules d’une couche inférieure, et seulement leur paquet racine. Les modules d’une même couche ne s’importent jamais entre eux.
• Appeler vers le haut. Quand un module inférieur a besoin de quelque chose d’un module supérieur, le module supérieur lui passe des données simples, ou le module inférieur définit une petite interface que wiring.go remplit.
• Le SQL reste chez lui. Seuls les fichiers store*.go d’un module contiennent du SQL, et seulement sur ses propres tables. Pour lire les lignes d’un autre module, appelez son service.
• Les tables partagées appartiennent à core. Accédez à settings, schedules, secrets, jobs et events par les fonctions d’aide de core.
• Une seule sortie. Chaque appel vers l’extérieur passe par core/outbound.
• Les fonctionnalités en réserve enregistrent un interrupteur auprès de core/startup. Tant qu’il est désactivé, la route n’existe pas et la page masque la fonctionnalité.
• Pas de paquets fourre-tout. Pas de util, common, shared ni helpers.

L’ordre des couches est dans Modules.

Pour les experts

Dans un module

Chaque module du backend utilise les mêmes noms de fichiers.

Fichier	Contient
routes.go	Les routes de l’API, chacune avec la permission qu’elle demande
service.go et les fichiers par sujet	La logique que les autres modules appellent
store.go, store_<topic>.go	Tout le SQL des tables du module
types.go	Les enregistrements du module

Côté web, lib/<module>/ contient index.ts (ce que les autres modules peuvent utiliser), ses composants Svelte et leurs tests, plus api.ts et state.svelte.ts seulement quand il a ses propres appels ou son propre état.

Paquets de core

Core, c’est la tuyauterie. Il ne contient aucune règle du produit et n’importe aucun module.

Paquet	Contient
core/database	L’ouverture et la migration des deux fichiers SQLite, les fonctions d’aide pour les requêtes, les fonctions d’aide pour les paramètres et les événements, les champs de ligne partagés, le nettoyage de l’historique
core/files	Les fonctions d’aide pour les fichiers et les dossiers, l’espace disque libre
core/releasename	La qualité, le groupe et les numéros d’épisode tirés du nom d’une release
core/outbound	La seule façon d’appeler des serveurs extérieurs, avec contrôle des adresses
core/secrets	Le magasin de clés et la rotation des clés
core/logs	Le journal de l’application et les notes de plantage
core/jobs	La file des tâches, les planifications et les boucles qui redémarrent après un plantage
core/webserver	La tuyauterie du routeur, la base d’URL, la compression, l’envoi en direct
core/startup	L’utilisateur d’exécution, le mode mémoire réduite, les interrupteurs des fonctionnalités en réserve, la limite de mémoire, les modules de l’application
core/parts	Les interrupteurs des modules de l’application, que chaque module consulte avant de servir ou de s’exécuter
core/model	Les types partagés, comme les acteurs et les sujets

Quand core doit toucher aux données d’un module, le module enregistre un point d’accroche auprès de core dans wiring.go. La rotation des clés fonctionne ainsi.

Données

Fichier	Contient
holyarrs.db	La Bibliothèque, les demandes, les paramètres et tout ce qui compte
holyarrs-events.db	L’historique et les autres lignes d’événements. Il grossit et il est nettoyé sans toucher au fichier principal

Les migrations sont des fichiers SQL numérotés dans core/database/migrations/main et core/database/migrations/events. Elles s’exécutent au démarrage.

Voir aussi

• Modules
• Contribuer
• Tests