아키텍처

큰 변경을 하기 전에 코드가 어디에 있고 어떤 규칙이 적용되는지 확인하세요.

간단히 보기

HolyArrs는 웹 앱이 내장된 Go 프로그램 하나입니다. 포트 6262에서 웹 앱과 JSON API를 제공하고, 데이터는 설정 폴더의 SQLite 파일 2개에 보관합니다. 밖으로는 다운로더, 소스(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: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

규칙

규칙 하나라도 어기면 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 파일 2개 열기와 마이그레이션, 쿼리 헬퍼, 설정과 이벤트 헬퍼, 공유 행 필드, 기록 정리
core/files	파일과 폴더 헬퍼, 디스크 여유 공간
core/releasename	릴리스 이름에서 읽어 낸 품질, 그룹, 에피소드 번호
core/outbound	외부 서버를 호출하는 단 하나의 길. 주소 검사 포함
core/secrets	키 저장소와 키 교체
core/logs	앱 로그와 충돌 기록
core/jobs	작업 큐, 일정, 충돌 후 다시 시작되는 루프
core/webserver	라우터 배관, URL base, 압축, 실시간 푸시
core/startup	실행 사용자, 저메모리 모드, 보류 스위치, 메모리 한도, 파트
core/parts	모든 모듈이 제공하거나 실행하기 전에 확인하는 파트 스위치
core/model	행위자, 대상 같은 공유 타입

core가 모듈 데이터를 건드려야 할 때는 모듈이 wiring.go에서 core에 훅을 등록합니다. 키 교체가 이렇게 동작합니다.

데이터

파일	내용
holyarrs.db	라이브러리, 요청, 설정과 그 밖의 중요한 모든 것
holyarrs-events.db	기록과 그 밖의 이벤트 행. 계속 늘어나며, 메인 파일을 건드리지 않고 정리됩니다

마이그레이션은 core/database/migrations/main과 core/database/migrations/events에 있는 번호 붙은 SQL 파일입니다. 시작할 때 실행됩니다.

관련 문서

• 모듈
• 기여하기
• 테스트