Архитектура

Намери къде живее кодът и кои правила важат, преди да променяш нещо голямо.

Накратко

HolyArrs е една програма на Go с вградено уеб приложение. Тя сервира уеб приложението и JSON API на порт 6262 и държи данните си в 2 файла SQLite в папката с конфигурация. Тя се обръща към програми за изтегляне, Източници (през Jackett или Prowlarr), медийни сървъри, канали за известия и сървъра за метаданни на HolyArrs.

Проследи една заявка. Някой заявява филм в Explore (Разглеждане).

1. requests записва заявката.
2. След одобрението movies пита sources за издания.
3. Правилата за избор в mediafiles им дават точки.
4. downloads праща най-доброто към програмата за изтегляне.
5. Когато свърши, mediafiles импортира файла.
6. mediaservers и alerts получават съобщение.

Карта на кода

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 стои в корена на хранилището, защото go:embed не може да достигне родителска папка.

Къде да търсиш

Искаш да промениш	Виж в
Как се избира издание	internal/mediafiles
Програма за изтегляне	internal/downloads, тестове за съвместимост в internal/downloads/conformance_test.go
Канал за известия	internal/alerts
Вход, потребители, API ключове	internal/accounts
Съветникът при първо стартиране	internal/setup, app/frontend/src/routes/welcome
Импортиране на готов файл (разархивиране, етикети, съпоставяне)	internal/importer
Папки на Библиотеката, поемане и преименуване	internal/library
Как се избират и подреждат редовете и рафтовете	internal/suggest
Кои модули на приложението са включени	internal/core/parts
Адрес на страница	app/frontend/src/routes/
Миграция	internal/core/database/migrations/
Образът на Docker	deploy/Dockerfile

Правилата

Проверките в app/backend/tools/structurecheck чупят билда, когато някое правило се наруши. Пусни ги с реда от Тестване.

• Ред на слоевете. Модулът импортира само модули от по-нисък слой и само техния коренов пакет. Модули от един и същ слой никога не се импортират помежду си.
• Извикване нагоре. Когато долен модул има нужда от нещо от по-горен, горният подава обикновени данни надолу или долният дефинира малък интерфейс, който wiring.go попълва.
• SQL си стои вкъщи. Само собствените store*.go файлове на модула съдържат SQL и то само върху собствените му таблици. За да прочетеш редове на друг модул, извикай неговата услуга.
• Споделените таблици са на core. Стигай до settings, schedules, secrets, jobs и events през помощниците на core.
• Един изход. Всяко извикване навън минава през core/outbound.
• Задържаните функции регистрират превключвател в core/startup. Докато е изключен, маршрутът го няма и страницата крие функцията.
• Без пакети за всичко. Без util, common, shared или helpers.

Редът на слоевете е в Модули.

За експерти

Вътре в един модул

Всеки модул в бекенда използва едни и същи имена на файлове.

Файл	Съдържа
routes.go	API маршрути, всеки с правото, което му трябва
service.go и файловете по теми	Логика, която извикват други модули
store.go, store_<topic>.go	Целият SQL за собствените таблици на модула
types.go	Записите на модула

В уеб частта lib/<module>/ съдържа index.ts (какво могат да ползват другите модули), своите части на Svelte и техните тестове, а api.ts и state.svelte.ts има само ако модулът си има собствени извиквания или състояние.

Пакетите на core

Core е инфраструктурата. Той не съдържа продуктови правила и не импортира модули.

Пакет	Съдържа
core/database	Отваряне и миграции на двата файла SQLite, помощници за заявки, за настройки и събития, споделени полета на редовете, подрязване на историята
core/files	Помощници за файлове и папки, свободно място на диска
core/releasename	Качество, група и номера на епизоди от името на издание
core/outbound	Единственият начин да извикаш външни сървъри, с проверка на адресите
core/secrets	Хранилището за ключове и смяната на ключове
core/logs	Дневникът на приложението и бележките за сривове
core/jobs	Опашката със задачи, графиците и циклите, които се рестартират след срив
core/webserver	Маршрутизация, URL base, компресия, живо изпращане
core/startup	Потребител за изпълнение, режим за малко памет, задържани превключватели, лимит на паметта, модули
core/parts	Превключвателите на модулите, които всеки модул проверява, преди да обслужва или да работи
core/model	Споделени типове, като актьори и субекти

Когато core трябва да пипне данни на модул, модулът регистрира hook при core във wiring.go. Смяната на ключове работи така.

Данни

Файл	Съдържа
holyarrs.db	Библиотеката, заявките, настройките и всичко останало, което има значение
holyarrs-events.db	Историята и други редове със събития. Расте и се подрязва, без да пипа главния файл

Миграциите са номерирани SQL файлове в core/database/migrations/main и core/database/migrations/events. Те се изпълняват при стартиране.

Свързано

• Модули
• Принос
• Тестване