ארכיטקטורה

מצא איפה הקוד נמצא ואילו כללים חלים, לפני שאתה משנה משהו גדול.

בקצרה

HolyArrs בנוי כתוכנית Go אחת עם אפליקציית ה-web מובנית בתוכה. הוא מגיש את אפליקציית ה-web ו-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 image	deploy/Dockerfile

הכללים

הבדיקות ב-app/backend/tools/structurecheck מפילות את ה-build כשכלל נשבר. הרץ אותן עם השורה שבבדיקות.

• סדר השכבות. מודול מייבא רק מודולים בשכבה נמוכה יותר, ורק את החבילה הראשית שלהם. מודולים באותה שכבה אף פעם לא מייבאים זה את זה.
• קריאה כלפי מעלה. כשמודול נמוך צריך משהו ממודול גבוה, המודול הגבוה מעביר נתונים פשוטים כלפי מטה, או שהמודול הנמוך מגדיר ממשק קטן ש-wiring.go ממלא.
• SQL נשאר בבית. רק קבצי store*.go של המודול מכילים SQL, ורק על הטבלאות שלו. כדי לקרוא שורות של מודול אחר, קרא ל-service שלו.
• טבלאות משותפות שייכות ל-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	הרשומות של המודול

בצד ה-web, 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	טיפוסים משותפים כמו actors ו-subjects

כש-core צריך לגעת בנתונים של מודול, המודול רושם ב-wiring.go hook ב-core. כך עובדת החלפת מפתחות.

נתונים

קובץ	מכיל
holyarrs.db	הספרייה, בקשות, הגדרות וכל השאר שחשוב
holyarrs-events.db	היסטוריה ושורות אירועים אחרות. הוא גדל ומקוצץ בלי לגעת בקובץ הראשי

מיגרציות הן קבצי SQL ממוספרים ב-core/database/migrations/main וב-core/database/migrations/events. הן רצות בהפעלה.

קשור

• מודולים
• תרומה לפרויקט
• בדיקות