Arquitectura

Encuentra dónde vive el código y qué reglas se aplican antes de cambiar algo grande.

La versión corta

HolyArrs es un solo programa en Go con la app web incluida. Sirve la app web y una API JSON en el puerto 6262, y guarda sus datos en 2 archivos SQLite en la carpeta de configuración. Se comunica con Gestores de descargas, Fuentes (a través de Jackett o Prowlarr), servidores multimedia, canales de avisos y el servidor de metadatos de HolyArrs.

Sigue una solicitud. Alguien pide una película en Explorar.

1. requests registra la solicitud.
2. Tras la aprobación, movies pide Lanzamientos a sources.
3. Las Reglas de elección de mediafiles los puntúan.
4. downloads envía el mejor al Gestor de descargas.
5. Cuando termina, mediafiles importa el archivo.
6. Se informa a mediaservers y a alerts.

Mapa del código

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á en la raíz del repositorio porque go:embed no puede llegar a una carpeta superior.

Dónde encontrar cada cosa

Quieres cambiar	Mira en
Cómo se elige un Lanzamiento	internal/mediafiles
Un cliente de Gestor de descargas	internal/downloads, pruebas de contrato en internal/downloads/conformance_test.go
Un canal de avisos	internal/alerts
Inicio de sesión, usuarios, claves de API	internal/accounts
El asistente de primer inicio	internal/setup, app/frontend/src/routes/welcome
La importación de un archivo terminado (descompresión, etiquetas, coincidencias)	internal/importer
Carpetas de la Biblioteca, adoptar y renombrar	internal/library
Cómo se eligen y ordenan las filas y los estantes	internal/suggest
Qué partes de la app están activadas	internal/core/parts
La dirección de una página	app/frontend/src/routes/
Una migración	internal/core/database/migrations/
La imagen de Docker	deploy/Dockerfile

Las reglas

Las comprobaciones de app/backend/tools/structurecheck hacen fallar la compilación cuando se rompe una. Ejecútalas con la línea que está en Pruebas.

• Orden de capas. Un módulo importa solo módulos de una capa inferior, y solo su paquete raíz. Los módulos de la misma capa nunca se importan entre sí.
• Llamar hacia arriba. Cuando un módulo inferior necesita algo de uno superior, el superior le pasa datos simples hacia abajo, o el inferior define una interfaz pequeña que wiring.go completa.
• El SQL se queda en casa. Solo los archivos store*.go de un módulo contienen SQL, y solo sobre sus propias tablas. Para leer las filas de otro módulo, llama a su servicio.
• Las tablas compartidas son de core. Accede a settings, schedules, secrets, jobs y events mediante las funciones de ayuda de core.
• Una sola salida. Toda llamada al exterior pasa por core/outbound.
• Las funciones retenidas registran un interruptor en core/startup. Mientras está desactivado, la ruta no existe y la página oculta la función.
• Sin paquetes cajón de sastre. Nada de util, common, shared ni helpers.

El orden de capas está en Módulos.

Para expertos

Dentro de un módulo

Todos los módulos del backend usan los mismos nombres de archivo.

Archivo	Contiene
routes.go	Las rutas de la API, cada una con el permiso que necesita
service.go y archivos por tema	La lógica a la que llaman otros módulos
store.go, store_<topic>.go	Todo el SQL de las tablas propias del módulo
types.go	Los registros del módulo

En el lado web, lib/<module>/ contiene index.ts (lo que otros módulos pueden usar), sus partes de Svelte y sus pruebas, además de api.ts y state.svelte.ts solo cuando tiene llamadas o estado propios.

Paquetes de core

Core es la fontanería. No contiene reglas del producto y no importa ningún módulo.

Paquete	Contiene
core/database	Apertura y migración de los dos archivos SQLite, ayudas para consultas, ayudas para ajustes y eventos, campos de fila compartidos, recorte del historial
core/files	Ayudas para archivos y carpetas, espacio libre en disco
core/releasename	Calidad, grupo y números de episodio a partir del nombre de un lanzamiento
core/outbound	La única vía para llamar a servidores externos, con comprobación de direcciones
core/secrets	El almacén de claves y la rotación de claves
core/logs	El registro (log) de la app y las notas de fallos
core/jobs	La cola de tareas, las programaciones y los bucles que se reinician tras un fallo
core/webserver	Fontanería del enrutador, URL base, compresión, envío en vivo
core/startup	Usuario de ejecución, modo de poca memoria, interruptores de funciones retenidas, límite de memoria, Partes
core/parts	Los interruptores de Parte que cada módulo consulta antes de servir o ejecutar algo
core/model	Tipos compartidos, como actores y sujetos

Cuando core tiene que tocar datos de un módulo, el módulo registra un enganche en core desde wiring.go. La rotación de claves funciona así.

Datos

Archivo	Contiene
holyarrs.db	La Biblioteca, las solicitudes, los ajustes y todo lo demás que importa
holyarrs-events.db	El Historial y otras filas de eventos. Crece y se recorta sin tocar el archivo principal

Las migraciones son archivos SQL numerados en core/database/migrations/main y core/database/migrations/events. Se ejecutan al iniciar.

Relacionado

• Módulos
• Contribuir
• Pruebas