アーキテクチャ

大きな変更を加える前に、コードの場所と適用されるルールを確認します。

概要

HolyArrs は Web アプリを組み込んだ 1 つの Go プログラムです。ポート 6262 で Web アプリと JSON API を提供し、データは設定フォルダー内の 2 つの SQLite ファイルに保存します。外部では、ダウンローダー、ソース(Jackett または Prowlarr 経由)、メディアサーバー、通知チャンネル、HolyArrs のメタデータサーバーを呼び出します。

1 つのリクエストを追ってみます。誰かが 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:embed は親フォルダーを参照できないため、go.mod はリポジトリのルートにあります。

どこに何があるか

変更したいもの	見る場所
リリースの選び方	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

ルール

ルールが 1 つでも破られると、app/backend/tools/structurecheck のチェックがビルドを失敗させます。実行するコマンドはテストにあります。

• レイヤーの順序。 モジュールがインポートできるのは、下のレイヤーにあるモジュールの、ルートパッケージだけです。同じレイヤーのモジュール同士はインポートしません。
• 上への呼び出し。 下のモジュールが上のモジュールの何かを必要とするときは、上のモジュールが単純なデータを下に渡すか、下のモジュールが小さなインターフェースを定義して wiring.go がそれを埋めます。
• SQL は自分のモジュールの中だけ。 SQL を書けるのはモジュール自身の store*.go ファイルだけで、対象も自分のテーブルだけです。ほかのモジュールの行を読むときは、そのモジュールのサービスを呼びます。
• 共有テーブルは core のもの。 settings、schedules、secrets、jobs、events には core のヘルパーを通してアクセスします。
• 外への出口は 1 つ。 外部への呼び出しはすべて core/outbound を通します。
• 既定でオフの機能は core/startup にスイッチを登録します。オフの間はルートが存在せず、ページにもその機能は表示されません。
• 寄せ集めパッケージは作らない。 util、common、shared、helpers は使いません。

レイヤーの順序はモジュールにあります。

上級者向け

モジュールの中身

バックエンドのモジュールはすべて同じファイル名を使います。

ファイル	内容
routes.go	API ルートと、それぞれに必要な権限
service.go とトピックごとのファイル	ほかのモジュールが呼び出すロジック
store.go、store_<topic>.go	モジュール自身のテーブルに対するすべての SQL
types.go	モジュールのレコード

Web 側では、lib/<module>/ に index.ts(ほかのモジュールが使ってよいもの)、Svelte のパーツとそのテストを置きます。api.ts と state.svelte.ts は、独自の呼び出しや状態があるときだけ置きます。

core のパッケージ

core は土台の部分です。製品のルールは持たず、モジュールもインポートしません。

パッケージ	内容
core/database	2 つの SQLite ファイルを開く処理とマイグレーション、クエリのヘルパー、設定とイベントのヘルパー、共通の行フィールド、履歴の削減
core/files	ファイルとフォルダーのヘルパー、ディスクの空き容量
core/releasename	リリース名から品質、グループ、エピソード番号を読み取る処理
core/outbound	外部のサーバーを呼び出す唯一の経路。アドレスのチェック付き
core/secrets	キーストアとキーのローテーション
core/logs	アプリのログとクラッシュの記録
core/jobs	ジョブキュー、スケジュール、クラッシュ後に再起動するループ
core/webserver	ルーターの土台、URL ベース、圧縮、ライブプッシュ
core/startup	実行ユーザー、低メモリモード、既定でオフの機能のスイッチ、メモリの上限、パート
core/parts	各モジュールが提供や実行の前に確認するパートのスイッチ
core/model	アクターやサブジェクトなどの共通の型

core がモジュールのデータに触れる必要があるときは、モジュールが wiring.go で core にフックを登録します。キーのローテーションはこの仕組みで動いています。

データ

ファイル	内容
holyarrs.db	ライブラリ、リクエスト、設定など、大事なものすべて
holyarrs-events.db	履歴とそのほかのイベントの行。サイズが増えていき、メインのファイルに触れずに削減されます

マイグレーションは、core/database/migrations/main と core/database/migrations/events にある番号付きの SQL ファイルです。起動時に実行されます。

関連ページ

• モジュール
• コントリビュート
• テスト