Arsitektur

Cari tahu di mana kode berada dan aturan apa yang berlaku sebelum kamu mengubah sesuatu yang besar.

Ringkasnya

HolyArrs adalah satu program Go dengan aplikasi web di dalamnya. Program ini melayani aplikasi web dan API JSON di port 6262, dan menyimpan datanya di 2 file SQLite di folder konfigurasi. Program ini memanggil Downloader, Sumber (lewat Jackett atau Prowlarr), server media, saluran notifikasi, dan server metadata HolyArrs.

Ikuti satu permintaan. Seseorang meminta sebuah film di Explore (Jelajahi).

1. requests mencatat permintaan itu.
2. Setelah disetujui, movies meminta rilis dari sources.
3. Aturan pilihan di mediafiles memberi nilai pada rilis-rilis itu.
4. downloads mengirim yang terbaik ke Downloader.
5. Setelah selesai, mediafiles mengimpor filenya.
6. mediaservers dan alerts diberi tahu.

Peta kode

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 ada di root repo karena go:embed tidak bisa menjangkau folder induk.

Di mana mencari sesuatu

Yang mau kamu ubah	Lihat di
Cara sebuah rilis dipilih	internal/mediafiles
Klien Downloader	internal/downloads, contract test di internal/downloads/conformance_test.go
Saluran notifikasi	internal/alerts
Login, pengguna, kunci API	internal/accounts
Wizard pertama kali dijalankan	internal/setup, app/frontend/src/routes/welcome
Mengimpor file yang sudah selesai (ekstrak, tag, pencocokan)	internal/importer
Folder pustaka, mengambil alih dan mengganti nama	internal/library
Cara baris dan rak dipilih dan diurutkan	internal/suggest
Bagian aplikasi mana yang aktif	internal/core/parts
Alamat sebuah halaman	app/frontend/src/routes/
Sebuah migrasi	internal/core/database/migrations/
Image Docker	deploy/Dockerfile

Aturannya

Pemeriksaan di app/backend/tools/structurecheck menggagalkan build kalau ada yang dilanggar. Jalankan dengan baris perintah di Pengujian.

• Urutan layer. Sebuah modul hanya mengimpor modul di layer yang lebih rendah, dan hanya package root-nya. Modul di layer yang sama tidak pernah saling mengimpor.
• Memanggil ke atas. Kalau modul bawah butuh sesuatu dari modul atas, modul atas mengirim data biasa ke bawah, atau modul bawah mendefinisikan interface kecil yang diisi oleh wiring.go.
• SQL tetap di modulnya sendiri. Hanya file store*.go milik modul itu sendiri yang memegang SQL, dan hanya untuk tabelnya sendiri. Untuk membaca baris milik modul lain, panggil service-nya.
• Tabel bersama milik core. Akses settings, schedules, secrets, jobs, dan events lewat helper core.
• Satu jalan keluar. Setiap panggilan ke luar lewat core/outbound.
• Fitur yang ditunda mendaftarkan sakelar ke core/startup. Selama sakelarnya mati, route-nya tidak ada dan halaman menyembunyikan fiturnya.
• Tidak ada package serba-ada. Tidak ada util, common, shared, atau helpers.

Urutan layer ada di Modul.

Untuk yang mahir

Di dalam sebuah modul

Setiap modul backend memakai nama file yang sama.

File	Isinya
routes.go	Route API, masing-masing dengan izin yang dibutuhkan
service.go dan file topik	Logika yang dipanggil modul lain
store.go, store_<topic>.go	Semua SQL untuk tabel milik modul itu sendiri
types.go	Record milik modul

Di sisi web, lib/<module>/ berisi index.ts (yang boleh dipakai modul lain), bagian Svelte-nya beserta tesnya, plus api.ts dan state.svelte.ts hanya kalau modul itu punya panggilan atau state sendiri.

Package core

Core adalah lapisan dasar. Core tidak memegang aturan produk dan tidak mengimpor modul apa pun.

Package	Isinya
core/database	Membuka dan memigrasi kedua file SQLite, helper query, helper pengaturan dan kejadian, field baris bersama, pemangkasan riwayat
core/files	Helper file dan folder, ruang disk kosong
core/releasename	Kualitas, grup, dan nomor episode dari nama rilis
core/outbound	Satu-satunya jalan untuk memanggil server luar, dengan pemeriksaan alamat
core/secrets	Penyimpanan kunci dan rotasi kunci
core/logs	Log aplikasi dan catatan crash
core/jobs	Antrean tugas, jadwal, dan loop yang dimulai ulang setelah crash
core/webserver	Router, URL base, kompresi, push langsung
core/startup	Pengguna yang menjalankan, mode memori rendah, sakelar fitur yang ditunda, batas memori, bagian
core/parts	Sakelar bagian yang ditanyakan setiap modul sebelum melayani atau berjalan
core/model	Tipe bersama seperti aktor dan subjek

Kalau core harus menyentuh data modul, modul itu mendaftarkan hook ke core di wiring.go. Rotasi kunci bekerja dengan cara ini.

Data

File	Isinya
holyarrs.db	Pustaka, permintaan, pengaturan, dan semua hal penting lainnya
holyarrs-events.db	Riwayat dan baris kejadian lain. File ini terus membesar dan dipangkas tanpa menyentuh file utama

Migrasi adalah file SQL bernomor di core/database/migrations/main dan core/database/migrations/events. Migrasi berjalan saat program dimulai.

Terkait

• Modul
• Berkontribusi
• Pengujian