Архітектура

Дізнайся, де лежить код і які правила діють, перш ніж міняти щось велике.

Коротко

HolyArrs — це одна програма на Go з вбудованим вебзастосунком. Вона віддає вебзастосунок і JSON API на порту 6262, а дані зберігає у 2 файлах SQLite у теці конфігурації. Вона звертається до завантажувачів, джерел (через Jackett або Prowlarr), медіасерверів, каналів сповіщень і сервера метаданих HolyArrs.

Простеж один запит. Хтось запрошує фільм на сторінці Огляд.

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 лишається вдома. SQL містять лише власні файли store*.go модуля, і лише для його власних таблиць. Щоб прочитати рядки іншого модуля, виклич його сервіс.
• Спільні таблиці належать 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 має торкнутися даних модуля, модуль реєструє в core хук у wiring.go. Так працює ротація ключів.

Дані

Файл	Що містить
holyarrs.db	Бібліотеку, запити, налаштування і все інше важливе
holyarrs-events.db	Історію та інші рядки подій. Він росте й обрізається, не чіпаючи головний файл

Міграції — це пронумеровані файли SQL у core/database/migrations/main і core/database/migrations/events. Вони виконуються під час запуску.

Пов’язане

• Модулі
• Участь у розробці
• Тестування