tv-maniac - GitLite

KO | EN

gitlite — search

#javascript #python #typescript #llm #android #deep-learning #macos #nodejs #windows #cli #vue #pytorch #openai #ios

tv-maniac

(★ 364)

Tv-Maniac is a personalized entertainment tracking and recommendation Multiplatform app (Android & iOS) for tracking TV Shows using TMDB API.

파일 탐색기

최종 버전 다운로드 (.zip)

파일 수가 많아 일부만 표시됩니다. 전체 파일은 위 다운로드 버튼으로 확인해 주세요.

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - baseline-profile.yml
  - beta-release.yml
  - ci.yml
  - compare-screenshot.yml
  - ios-binary-size.yml
  - nightly-integration-tests.yml
  - release-android.yml
  - release-ios.yml
  - store-screenshot.yml
  - weekly-dev-build-android.yml
  - weekly-dev-build-ios.yml
- pull_request_template.md
- release.yml
- renovate.json
- - codeStyleConfig.xml
  - Project.xml
- - project.xml
- icon.svg
- build.gradle.kts
- README.md
- - releaseRuntimeClasspath.txt
- benchmark-rules.pro
- build.gradle.kts
- lint-baseline.xml
- proguard-rules.pro
- README.md
- AndroidDetailLight.png
- AndroidHomeLight.png
- AnroidDetailDark.png
- AnroidHomeDark.png
- EpisodeListDark.png
- EpisodeListLight.png
- FirebaseAppDistribution.svg
- iOSDetailDark.png
- iOSDetailLight.png
- iOSHomeDark.png
- iOSHomeLight.png
- TvManiacBanner.png
- build.gradle.kts
- README.md
- - build.gradle.kts
  - README.md
- - build.gradle.kts
  - README.md
- - build.gradle.kts
  - README.md
- - build.gradle.kts
  - README.md
- - build.gradle.kts
  - README.md
.editorconfig
.geminiignore
.gitignore
.ruby-version
.swiftformat
.swiftlint.yml
Brewfile
build.gradle.kts
CHANGELOG.md
cliff.toml
compose-stability.conf
CONTRIBUTING.md
Gemfile
Gemfile.lock
GEMINI.md
LICENSE
Mintfile
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/thomaskioko/tv-maniac

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd tv-maniac

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Gradle (Java/Kotlin)

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
JDK (Java) Java/Kotlin 프로젝트를 빌드/실행하려면 필요합니다.
Gradle 레포에 포함된 gradlew(Gradle Wrapper)를 쓰면 Gradle을 따로 설치할 필요가 없습니다.

./gradlew :app:assembleDebug

Gradle로 빌드를 진행합니다.

✅ BUILD SUCCESSFUL 메시지가 뜨면 성공입니다. build/ 폴더에 결과물이 생성됩니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Ruby

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Ruby bundle 명령어를 쓰려면 Ruby가 필요합니다.

bundle install

Gemfile에 명시된 루비 라이브러리를 설치합니다.

✅ bundle install이 에러 없이 끝나면 README에 안내된 실행 명령어(예: rails server)로 마저 실행해보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
<img src="art/TvManiacBanner.png" width="100%" />
</p>

# TvManiac

![Check](https://github.com/thomaskioko/tv-maniac/actions/workflows/ci.yml/badge.svg)
![kmp](https://img.shields.io/badge/multiplatform-%237F52FF.svg?style=for-the-badge&logo=kotlin&logoColor=white)
![compose](https://img.shields.io/badge/jetpack_compose-2bab6b.svg?style=for-the-badge&logo=android&logoColor=white)
![swiftui](https://img.shields.io/badge/swiftui-%23000000.svg?style=for-the-badge&logo=swift&logoColor=white)

[![Download APK](https://img.shields.io/github/v/release/thomaskioko/tv-maniac?label=Download%20APK&logo=android&style=for-the-badge)](https://github.com/thomaskioko/tv-maniac/releases/latest)
[![Join Beta](https://img.shields.io/badge/Join%20Beta-Google%20Play-01875f?style=for-the-badge&logo=googleplay&logoColor=white)](https://play.google.com/apps/testing/com.thomaskioko.tvmaniac)

**TvManiac** is a personalized entertainment tracking and recommendation Multiplatform app (Android & iOS) for tracking TV Shows. By utilizing [TMDB](https://developer.themoviedb.org/docs), [Trakt](https://trakt.tv) and [Simkl](https://simkl.com), you can discover shows, manage your watchlist, track watch progress, and get personalized recommendations.

| Android | iOS |
|---|---|
| <video src="https://github.com/user-attachments/assets/90ec7924-7d50-40a4-bb0b-89d79aa9bbcd" width=350/> | <video src="https://github.com/user-attachments/assets/69f101b7-e100-4775-9893-6687e455560c" width=350/> |

> **Under Heavy Development**
>
> This is my playground for learning Kotlin Multiplatform. With that said, I'm sure it's filled with bugs crawling everywhere, and I'm probably doing a couple of things wrong. So a lot is changing, but that shouldn't stop you from checking it out.

## Install

Download the latest APK from [GitHub Releases](https://github.com/thomaskioko/tv-maniac/releases).

Join the open beta on [Google Play](https://play.google.com/store/apps/details?id=com.thomaskioko.tvmaniac&hl=en_US) or stay up to date with dev builds via Firebase:

[<img width=400 src="art/FirebaseAppDistribution.svg"/>](https://appdistribution.firebase.dev/i/564c934cc970634b)

---

## Getting Started

### Requirements

- [Zulu Java 21](https://www.azul.com/downloads/?package=jdk#zulu)
- Latest [Android Studio](https://developer.android.com/studio/preview)
- [KMM Plugin](https://kotlinlang.org/docs/multiplatform-mobile-setup.html)

### API Keys

The app requires TMDB, Trakt, and Simkl API credentials. See [docs/setup.md](docs/setup.md) for detailed instructions.

The setup script below creates `local.properties` from the template. Fill in your keys:

```properties
TMDB_API_KEY=your_tmdb_api_key
TRAKT_CLIENT_ID=your_trakt_client_id
TRAKT_CLIENT_SECRET=your_trakt_client_secret
TRAKT_REDIRECT_URI=tvmaniac://auth/trakt
SIMKL_CLIENT_ID=your_simkl_client_id
SIMKL_CLIENT_SECRET=your_simkl_client_secret
SIMKL_REDIRECT_URI=tvmaniac://auth/simkl
```

### Setup & Build

One command sets up everything. It is idempotent and platform-aware: full setup including iOS on macOS, Android-only on Linux/Windows (iOS needs a Mac).

```bash
./scripts/setup.sh
```

See [docs/setup.md](docs/setup.md) for what it installs and the manual steps.

**Android:**
```bash
./gradlew :app:assembleDebug
```

**iOS (macOS only):**
Open `ios/tv-maniac.xcodeproj` in Xcode and run.

---

## Architecture

The project follows Clean Architecture with a modular design organized by feature and layer. Business logic and state management live in shared KMP code, while Android (Compose) and iOS (SwiftUI) contain only UI rendering.

For detailed documentation:

- [Modularization](docs/architecture/modularization.md)
- [Presentation Layer](docs/architecture/presentation-layer.md)
- [Data Layer](docs/architecture/data-layer.md)
- [Navigation](docs/architecture/navigation.md)
- [Dependency Injection](docs/architecture/dependency-injection.md)
- [Integration Testing](docs/architecture/integration-testing.md)

---

## Key Concepts

A few foundational libraries and patterns drive the architecture.

- **[Decompose](https://arkivanov.github.io/Decompose/)**. Shared navigation and lifecycle for KMP. The navigation stack, child components, and back handling all live in shared Kotlin code. Android (Compose) and iOS (SwiftUI) only render the active child. See [Navigation](docs/architecture/navigation.md).
- **[Metro](https://zacsweers.github.io/metro/latest/)**. Compile time dependency injection. There is no KSP processor and no runtime reflection. Modules expose interfaces from `api/` packages, implementations are bound with `@ContributesBinding`, and the full graph is assembled at the app entry point. See [Dependency Injection](docs/architecture/dependency-injection.md).
- **[Store pattern](https://store.mobilenativefoundation.org/)**. One fetch and cache pipeline per data type. A `Store` combines a `Fetcher` (network), a `SourceOfTruth` (SQLDelight DAO), and a `Validator` (cache freshness via `RequestManager`). Presenters never call the network or DAO directly. See [Data Layer](docs/architecture/data-layer.md).
- **Interactor and SubjectInteractor**. Thin orchestration in the domain layer. An `Interactor` runs a one shot action (mark watched, sign in). A `SubjectInteractor` exposes a continuous `Flow` of data (observe show details). Presenters compose these into screen state. See [Presentation Layer](docs/architecture/presentation-layer.md).

---

## Tech Stack

Architectural choices (Decompose, Metro, Store) are described in [Key Concepts](#key-concepts) above. The libraries below cover the rest of the shared and platform stack.

**Shared (KMP)**
- [Kotlin Coroutines](https://github.com/Kotlin/kotlinx.coroutines) - Concurrency
- [Ktor](https://ktor.io/) - Networking
- [SQLDelight](https://github.com/cashapp/sqldelight) - Local database
- [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) - JSON serialization
- [Multiplatform Paging](https://github.com/cashapp/multiplatform-paging) - Pagination

**Android**
- [Jetpack Compose](https://developer.android.com/jetpack/compose) - UI toolkit
- [Coil](https://coil-kt.github.io/coil/) - Image loading
- [AppAuth](https://openid.github.io/AppAuth-Android/) - OAuth authentication

**iOS**
- [SwiftUI](https://developer.apple.com/xcode/swiftui/) - UI framework
- [Nuke](https://github.com/kean/Nuke) - Image loading
- [OAuthSwift](https://github.com/OAuthSwift/OAuthSwift) - OAuth authentication

---

## Gradle Convention Plugins

Build configurations are managed by [app-gradle-plugins](https://github.com/thomaskioko/app-gradle-plugins), a set of custom Gradle convention plugins published to Maven Central. They handle Android/KMP module setup, versioning, release automation, and R8 optimization. For a deep dive into how they work, see [Publishing Gradle Convention Plugins](https://thomaskioko.me/posts/publishing_gradle_plugins/).

---

## References & Inspiration

- [Design Inspiration](https://dribbble.com/shots/7591814-HBO-Max-Companion-App-Animation)
- [Tivi](https://github.com/chrisbanes/tivi)
- [Compose Samples](https://github.com/android/compose-samples)

## License

```
Copyright 2021 Thomas Kioko

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```