สถาปัตยกรรม

รู้ว่าโค้ดอยู่ตรงไหนและมีกฎอะไรบ้าง ก่อนแก้ส่วนที่ใหญ่

สรุปสั้น ๆ

HolyArrs เป็นโปรแกรม Go ตัวเดียวที่มีเว็บแอปฝังอยู่ในตัว ให้บริการเว็บแอปและ JSON API ที่ port 6262 และเก็บข้อมูลไว้ในไฟล์ SQLite 2 ไฟล์ในโฟลเดอร์คอนฟิก โปรแกรมเรียกออกไปยังตัวดาวน์โหลด แหล่งค้นหา (ผ่าน Jackett หรือ Prowlarr) มีเดียเซิร์ฟเวอร์ ช่องทางการแจ้งเตือน และเซิร์ฟเวอร์ metadata ของ 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 อยู่ที่รากของ repo เพราะ go:embed เข้าถึงโฟลเดอร์แม่ไม่ได้

หาของได้ที่ไหน

ถ้าต้องการแก้	ดูที่
วิธีเลือกรีลีส	internal/mediafiles
ตัวเชื่อมตัวดาวน์โหลด	internal/downloads ส่วนเทสต์สัญญาอยู่ใน internal/downloads/conformance_test.go
ช่องทางการแจ้งเตือน	internal/alerts
การล็อกอิน ผู้ใช้ API key	internal/accounts
ตัวช่วยตั้งค่าครั้งแรก	internal/setup, app/frontend/src/routes/welcome
การนำเข้าไฟล์ที่ดาวน์โหลดเสร็จ (แตกไฟล์ แท็ก การจับคู่)	internal/importer
โฟลเดอร์คลัง การรับเข้าดูแล และการเปลี่ยนชื่อ	internal/library
วิธีเลือกและเรียงแถวและชั้นวาง	internal/suggest
ส่วนใดของแอปที่เปิดอยู่	internal/core/parts
ที่อยู่ของหน้า	app/frontend/src/routes/
migration	internal/core/database/migrations/
Docker image	deploy/Dockerfile

กฎ

การตรวจสอบใน app/backend/tools/structurecheck จะทำให้บิลด์ล้มเหลวเมื่อมีข้อใดข้อหนึ่งถูกละเมิด รันได้ด้วยคำสั่งในหน้า การทดสอบ

• ลำดับชั้น โมดูลนำเข้าได้เฉพาะโมดูลในชั้นที่ต่ำกว่า และเฉพาะ package ราก โมดูลในชั้นเดียวกันห้ามนำเข้าหากัน
• การเรียกขึ้นข้างบน เมื่อโมดูลชั้นล่างต้องการบางอย่างจากชั้นบน โมดูลชั้นบนส่งข้อมูลธรรมดาลงมาให้ หรือโมดูลชั้นล่างกำหนด interface เล็ก ๆ ให้ wiring.go เติมให้
• SQL อยู่บ้านตัวเอง มีเพียงไฟล์ store*.go ของโมดูลเองที่มี SQL และใช้กับตารางของโมดูลเองเท่านั้น หากต้องการอ่านแถวของโมดูลอื่น ให้เรียก service ของโมดูลนั้น
• ตารางที่ใช้ร่วมกันเป็นของ core เข้าถึง settings, schedules, secrets, jobs และ events ผ่านตัวช่วยของ core
• ทางออกทางเดียว ทุกการเรียกออกไปภายนอกต้องผ่าน core/outbound
• ฟีเจอร์ที่ยังไม่เปิดให้ใช้ ลงทะเบียนสวิตช์กับ core/startup ขณะที่สวิตช์ปิด จะไม่มีเส้นทางนั้น และหน้าเว็บจะซ่อนฟีเจอร์
• ห้ามมี package แบบรวมของจิปาถะ ห้ามมี 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 ซึ่งมีเฉพาะเมื่อโมดูลมีการเรียก API หรือสถานะของตัวเอง

แพ็กเกจของ core

Core คือโครงสร้างพื้นฐาน ไม่มีกฎของตัวผลิตภัณฑ์ และไม่นำเข้าโมดูลใด

Package	เก็บอะไร
core/database	การเปิดและ migrate ไฟล์ SQLite ทั้งสอง ตัวช่วยสำหรับ query ตัวช่วยของ settings และ events ฟิลด์ของแถวที่ใช้ร่วมกัน การตัดประวัติเก่า
core/files	ตัวช่วยจัดการไฟล์และโฟลเดอร์ พื้นที่ดิสก์ว่าง
core/releasename	คุณภาพ กลุ่ม และเลขตอน จากชื่อรีลีส
core/outbound	ทางเดียวที่ใช้เรียกเซิร์ฟเวอร์ภายนอก พร้อมการตรวจที่อยู่
core/secrets	ที่เก็บคีย์และการหมุนคีย์
core/logs	Log ของแอปและบันทึกการแครช
core/jobs	คิวงาน ตารางเวลา และลูปที่เริ่มใหม่เองหลังแครช
core/webserver	โครงสร้าง router, URL base, การบีบอัด, live push
core/startup	ผู้ใช้ที่ใช้รัน โหมดประหยัดหน่วยความจำ สวิตช์ของฟีเจอร์ที่ยังไม่เปิดให้ใช้ ขีดจำกัดหน่วยความจำ ส่วนต่าง ๆ
core/parts	สวิตช์ของแต่ละส่วนที่ทุกโมดูลต้องถามก่อนให้บริการหรือทำงาน
core/model	ชนิดข้อมูลที่ใช้ร่วมกัน เช่น actor และ subject

เมื่อ core ต้องแตะข้อมูลของโมดูล โมดูลจะลงทะเบียน hook กับ core ใน wiring.go การหมุนคีย์ทำงานด้วยวิธีนี้

ข้อมูล

ไฟล์	เก็บอะไร
holyarrs.db	คลัง คำขอ การตั้งค่า และทุกอย่างที่สำคัญ
holyarrs-events.db	ประวัติและแถวเหตุการณ์อื่น ๆ ไฟล์นี้โตและถูกตัดเก่าออกได้โดยไม่แตะไฟล์หลัก

Migration คือไฟล์ SQL ที่มีเลขลำดับ อยู่ใน core/database/migrations/main และ core/database/migrations/events และจะรันตอนเริ่มโปรแกรม

หน้าที่เกี่ยวข้อง

• โมดูล
• การมีส่วนร่วม
• การทดสอบ