Files
android_multiviewwer/ARCHITECTURE.md
T
lun_admin bc859494b1 build: :core:core-utils 모듈 분리 및 유틸성 클래스 17종 이관
- core/core-utils 모듈 신규 생성 (namespace: bums.lunatic.launcher.core.utils):
  * AlphabetToChosungMap, APILevel, BitmapConverter, CategoryManualMapper, CommonUtils, CompressStringUtil, EnToKo, FileUtils, HashUtils, ImageUtils, JsoupUtils, KoreanTrans, MediaBitmapUtil, PlayCategory, PreferencesUtil, RssList, StringEscapeUtils 총 17종 이관
  * (@GlideModule 어노테이션 프로세서 제약이 있는 CustomOkHttpGlideModule.kt만 :app에 유지)
- settings.gradle.kts, app/build.gradle.kts, ARCHITECTURE.md 갱신
- 검증: ./gradlew :app:compileDebugKotlin 빌드 성공 확인 (11s, 133 actionable tasks)
2026-11-16 13:33:02 +09:00

10 KiB

LunarLauncher 아키텍처 개요

LunarLauncher는 Android 홈 런처를 중심으로 RSS/커뮤니티 피드, 웹 리더(GeckoView/WebView), 토렌트 및 미디어 다운로드, 네이티브 FFmpeg 기반 미디어/문서/이미지 뷰어, 라이브 월페이퍼, Google Drive 백업, Wear OS 제스처 연동을 통합한 멀티 모듈 Android 프로젝트입니다.


1. Gradle 모듈 구성

settings.gradle.kts 기준 모듈 구성은 다음과 같습니다.

모듈 역할 비고
:app 메인 Android 애플리케이션 (bums.lunatic.launcher) compileSdk 35, minSdk 26, arm64-v8a 네이티브(C++/CMake) 포함
:core:core-common 공통 로거(Blog), 유틸(JamoUtils, DataUtils), ML Kit 헬퍼(MlKitTranslationHelper) :app, :core:core-database, :feature:*에서 참조
:core:core-database Realm Kotlin 모델(model/*, TokizModels, RecentCall), WorkersDb, CustMigration io.realm.kotlin api 노출
:core:core-network 공용 OkHttpClient 싱글톤(NetworkClient) OkHttp3 커넥션 풀 공유
:core:core-utils 파일/이미지/인코딩/Jsoup/한글변환/설정/카테고리 유틸리티 17종 :core:core-common, :core:core-network 의존
:feature:feature-player NativePlayer, PageIndexer, ImageViewerActivity 미디어/이미지 뷰어 코어 PhotoView, ExifInterface, Glide
:feature:feature-reader WebReaderActivity, PagedTextLayout, TouchArea 리더 코어 :core:core-common 의존
:feature:feature-torrent TorrentService/TorrentTask 및 jlibtorrent JAR 격리 모듈 :core:core-common 의존
:feature:feature-wallpaper MyWallpaperService/NativeRenderer 라이브 월페이퍼 모듈 :core:core-common, :core:core-database 의존
:gdrive Google Drive appDataFolder 기반 로그인 및 백업 모듈 :app에서 implementation(project(":gdrive"))로 참조
:lun_launcher Wear OS 컴패니언 앱 (bums.lunatic.launcher, minSdk 30, compileSdk 36) Compose for Wear OS, Tile, Complication, 제스처 전송(MessageClient)

2. :app 패키지 구조 (bums.lunatic.launcher)

app/src/main/
├── cpp/                         # C++ 네이티브 엔진 (FFmpeg, AAudio, Sonic, Live Wallpaper 렌더러)
└── kotlin/bums/lunatic/launcher/
    ├── LunaticLauncher.kt       # Application 클래스 (GeckoRuntime, Picasso, 로그 초기화)
    ├── LauncherActivity.kt      # 메인 홈 런처 Activity (HOME/LAUNCHER)
    ├── apps/                    # 앱 서랍, 앱/연락처 어댑터, 아이콘 팩, 검색 메뉴
    ├── behavior/                # 화면 전환/동작 인터랙션 전략 패턴
    ├── common/                  # 공통 Activity 기반 클래스, 리모트 제스처 Fragment, 타입 별칭
    ├── feeds/                   # 시스템 상태, 앱 위젯 호스트(WidgetHost), RSS 파서/어댑터
    ├── helpers/                 # ForegroundService, WorkManager 워치독, 설정(PrefHelper), 잠금/수신기
    ├── home/                    # 홈 피드(RssHome), NeoRssActivity, 파일/웹/번역 화면 및 각종 BottomSheet
    │   ├── adapters/            # 북마크, 알림, 통화/SMS, RSS, 토렌트, 날씨 RecyclerView 어댑터
    │   ├── tokiz/               # 텍스트/웹툰/소설 리더(TokiFragment, HistoryManager, PagedTextLayout)
    │   └── weather/             # 날씨 API 클라이언트 및 파서
    ├── model/                   # Realm Kotlin 데이터 모델 (AppInfo, RssData, WeatherForcast 등)
    ├── player/                  # 네이티브 미디어 플레이어, 문서/이미지 뷰어 Activity
    ├── qaccess/                 # 퀵 액세스 패널
    ├── receiver/                # NotificationListenerService(NLService), 전화/SMS/패키지/연락처 리시버
    ├── settings/                # 런처 및 하위 카테고리별 설정 Activity/Fragment
    ├── utils/                   # 한글 초성/자모 변환, 파일/이미지/인코딩/Jsoup 유틸리티
    ├── view/                    # 커스텀 UI 뷰 (FloatingActionMenu, LunaticBrowserLayout, ZoomImageView 등)
    ├── wall/                    # 라이브 월페이퍼 서비스(MyWallpaperService) 및 JNI 브리지(NativeRenderer)
    └── workers/                 # Realm DB(WorkersDb), 백그라운드 수집기(*Getter), 토렌트/위치/워치 서비스

3. 핵심 컴포넌트 역할 요약

3.1. Activity

  • LauncherActivity: MAIN / HOME / LAUNCHER 인텐트를 처리하는 메인 홈 런처. 앱 위젯 호스트, 앱 서랍(AppDrawerBottomSheet), 키보드/게임패드/리모트 입력 및 SEND/SEND_MULTIPLE 공유 수신을 담당합니다.
  • NeoRssActivity: RSS/커뮤니티 피드(RssHome), 웹/콘텐츠 리더(TokiFragment) 등을 호스팅하며 WEB_SEARCH 및 SEND 인텐트를 처리합니다.
  • WebReaderActivity: 별도 런처 아이콘(리더)으로 실행되는 WebView 기반 웹 리더. 파일 업로드/백업 복원(ActivityResultContracts) 및 JS 브리지를 제공합니다.
  • CompletedFilesActivity: 별도 런처 아이콘(파일즈)으로 실행되는 다운로드/완료 파일 탐색기. 파일 목록 조회, 미리보기, 문서/이미지 뷰어 연동을 수행합니다.
  • TranslatorActivity: ML Kit 언어 식별(LanguageIdentification) 및 번역(Translation), Android TextToSpeech를 연동한 번역기 화면입니다.
  • PlayerActivity: TextureView와 NativePlayer를 사용해 동영상을 재생하는 플레이어. 외부/내장 자막 동기화 및 ML Kit 기반 자막 실시간 번역, 재생 오류 시 엔진 복구(rebootEngine)를 지원합니다.
  • DocumentViewerActivity: PageIndexer와 PagedTextLayout을 이용해 대용량 텍스트 문서를 인코딩 감지 후 페이지 단위로 렌더링하는 뷰어입니다.
  • ImageViewerActivity: PhotoView와 ExifInterface를 이용해 이미지 확대/축소 및 EXIF 메타데이터 오버레이를 제공합니다.
  • SettingsActivity / home.tokiz.Settings: 런처 전반 설정(APPLICATION_PREFERENCES) 및 리더 전용 설정 화면입니다.

3.2. 주요 Fragment & BottomSheet

  • RssHome / RssViewer / BookmarkPagerFragment: 홈 피드, RSS 기사 뷰어, 북마크 페이저 UI.
  • CompletedFilesFragment / TorrentListFragment / SystemStatusFragment / LearningFragment: 완료 파일 목록, 토렌트 진행 목록, 시스템 상태, 학습/단어장 화면.
  • TokiFragment / RemoteGestureFragment: 텍스트/웹 콘텐츠 리더 및 워치/리모트 제스처 연동 Fragment.
  • AppDrawer / AppDrawerBottomSheet / SearchBottomSheet / WebBottomSheet / VideoPreviewBottomSheet: 앱 서랍, 통합 검색, 인앱 웹 바텀시트, 영상 미리보기 시트.

3.3. Service & BroadcastReceiver

  • ForeGroundService: youtubedl-android(yt-dlp) 및 OkHttp를 활용한 영상/파일 다운로드, 블루투스/미디어 버튼 처리, WorkManager 작업 스케줄링을 담당하는 포그라운드 서비스.
  • TorrentService (workers/TorrentManager.kt): jlibtorrent 기반 토렌트 다운로드 포그라운드 서비스. Wi-Fi 및 충전 상태에 따라 세션을 제어하고, 미리보기용 핵심 피스 우선 다운로드(previewPiecesMap)를 지원합니다.
  • MyWallpaperService: WallpaperService 구현체로, C++ NativeRenderer를 통해 라이브 월페이퍼 표면을 렌더링하고 날씨 비트맵/미디어 전환을 처리합니다.
  • NLService: NotificationListenerService로 외부 앱 알림을 수집·가공하여 Realm DB 및 로그에 기록합니다.
  • WatchGestureService: WearableListenerService로 Wear OS 앱(:lun_launcher)에서 보낸 /gesture/next, /gesture/prev 등의 메시지를 수신합니다.
  • LocationUpdateService: 위치 변경을 수신하고 Geocoder로 주소를 변환해 Realm LocationLog에 저장합니다.
  • 기타 리시버: CallReceiver(통화 상태), SmsReceiver(SMS/WAP Push), PackageEventReceiver(앱 설치/삭제), ContactReceiver, AdminReceiver, BatteryReceiver, HeadsetActionButtonReceiver.

3.4. 미디어·렌더링 네이티브 모듈 (app/src/main/cpp/)

CMakeLists.txt에서 native_renderer 공유 라이브러리로 빌드되며 libavformat, libavcodec, libavutil, libswscale, libswresample, aaudio, jnigraphics를 링크합니다.

  • 미디어 플레이어 엔진 (PlayerEngine.cpp/.h, native_player.cpp, sonic.c, PacketQueue.h):
    • Kotlin NativePlayer와 JNI로 연결됩니다.
    • FFmpeg 기반 비디오/오디오 디코딩, AAudio 네이티브 오디오 출력, sonic 기반 배속 재생, 내장/외부 자막 트랙 추출 및 탐색(seekTo/seekBy)을 처리합니다.
  • 라이브 월페이퍼 렌더러 (Renderer.cpp/.h, native_renderer.cpp, Preloader.cpp/.h, MediaAsset.cpp/.h, AnimationStrategy, TransitionStrategy):
    • Kotlin NativeRenderer와 JNI로 연결됩니다.
    • 미디어 에셋 프리로딩, 전환/애니메이션 전략 적용, Surface 직접 렌더링을 수행합니다.

3.5. 데이터 계층 및 백그라운드 수집기 (workers/, model/)

  • WorkersDb: Realm Kotlin(io.realm.kotlin) 싱글톤/스키마 관리 및 CustMigration을 담당합니다.
  • TaskAggregator & *Getter.kt: 앱 목록(AppInfoGetter), 연락처(ContactInfoGetter), 통화/SMS(RecentCallGetter, RecentSmsGetter), 캘린더(CalendarGetter), 위치(LocationGetter), 날씨(OpenWeatherGetter), 커뮤니티/RSS/유튜브/텔레그램(DCGetter, FmKoreaGetter, ClienGetter, ArcaGetter, RuliWebGetter, RedditGetter, TheQooGetter, DotaxGetter, NewsFeedsGetter, YoutubeGetter, TelegramBotGetter) 데이터를 비동기로 수집해 Realm에 병합합니다.

4. 서브 모듈 요약

  • :gdrive (kr.gdrive.bums.lunatic.utils):
    • GDriveLoginManager: GoogleSignIn과 DriveScopes.DRIVE_APPDATA 권한 요청을 캡슐화합니다.
    • GDriveBackupTask: appDataFolder에 manifest.json 및 백업 대상 JSON 파일들을 업로드하는 코루틴 기반 백업 태스크입니다.
  • :lun_launcher (Wear OS):
    • MainActivity: Wear OS Compose UI 및 센서 리스너를 통해 런처로 제스처 메시지를 전송합니다.
    • MainTileService, MainComplicationService, TileActionReceiver: 워치 페이스 컴플리케이션 및 Wear Tile을 제공합니다.