GithubCruise Android App

A user-friendly GitHub app for anyone, allowing smooth navigation of users and repositories.

This project brings together modern tools and best practices in Android development to create a robust and user-friendly app. It uses libraries like Retrofit for networking, Hilt for dependency injection, and Jetpack Compose for building sleek interfaces. The app features various screens, including a dynamic splash screen, a user list with essential details, and a detailed view of user repositories. Pagination is smoothly implemented to handle large data sets effectively. Thorough testing with JUnit and other tools ensures code quality. The project also focuses on localization, ViewModel usage, and efficient UI state management. Detailed guides for setup, execution, and deployment are included, along with comprehensive API documentation. Lastly, a TODO list outlines planned improvements for future updates.

Check out demo screen shots and videos here

Details demo-screenshots-video

• Short Size Video https://github.com/dinkar1708/GithubCruise/assets/14831652/08b8def1-3dff-4dc0-9326-53ee7a78f284

Table of Contents

1. Setup
2. Guide to Run Code
3. API Used
4. Features
5. Run Configuration Guide
6. Testing Guide
7. Coding Guide
8. Release Guide
9. APIs
10. FAQ
11. DO/DON'T
12. TODOs

Setup

Prerequisites

• JAVA & Android SDK installed - Current tested java SDK 17
• Android Studio
• Emulator / Physical device for testing

Installation

1. Clone the repository

   git clone https://github.com/dinkar1708/GithubCruise

2. Open the project in Android Studio
3. Make sure you have the version of Android Studio and JDK specified in Prerequisites section.
4. Build the project
5. Run the project on an emulator or a physical device

Guide to Run Code

Run Debug version

• Select release and run. Screenshot is below

Run Release version

• Select release and run. Screenshot is below

Special features

Light theme & Dark Theme support

• My app offers both light and dark theme options, providing users with a comfortable viewing experience in any lighting condition.
• Easily switch between light and dark themes in the app settings to suit your preference.
• See the screenshots below to get a glimpse of how my app looks in both light and dark themes.

Localization - Japanese and English language supported

• My app supports localization in both Japanese and English languages, catering to a diverse user base.
• Seamlessly switch between languages within the app settings to enjoy content in your preferred language.
• Check out the screenshots below to see how my app adapts to different language settings.

Developed to run on all devices, regardless of size

• My app is designed to provide a seamless experience on both small and large devices, ensuring optimal usability across a wide range of screen sizes.
• Whether you're using a compact smartphone or a large tablet, my app adapts effortlessly to your device's display, delivering a consistent and intuitive user experience.

Screen rotation support My app supports screen rotation and preserves user search data nicely.

---

Features

スプラッシュス覧画面

スクリーンショットは以下の通りです。

Feature: Splash

• Display the gradient background.
• Display an animated text.
• After 3 seconds go to user list screen.

Additional:

• NA

---

### ユーザー一覧画面

スクリーンショットは以下の通りです。

Feature: Search Users

• Display the user list as a list.
• Elements required for each line:
  • Icon image
  • User name
• Selecting each line moves to the user repository screen.
• Display a search string input column at the top of the screen, fixed at the top.
• Display a list of users below the input field based on the input string.

Additional:

• Used pagination.
• Display score of the user.

---

ユーザーリポジトリ画面

スクリーンショットは以下の通りです。

Feature: User repository and details

1. Displays detailed user information at the top of the list.
   • Elements required:
     • Icon image
     • User Name
     • Full name
     • Number of followers
     • Number of following
2. List repositories of users who are not forking repositories below
   • Elements required:
     • Repository name
     • Repository language
     • Number of stars
     • Description
   • Tap a line in the repository list to display the repository URL in WebView Additional:

• Filter repositories by fork status using the switch button.

---

リポジトリの詳細

スクリーンショットは以下の通りです。

Feature: User repository in web view

1. Display the user repository inside the app's web view.

Additional:

• NA.

---

Run Configuration Guide

Follow screen shot of android studion and run

Run debug version

• Config details

        release {
            manifestPlaceholders += mapOf("app_name" to "GithubCruise")
            buildConfigField("boolean", "DEBUG", "false")
            buildConfigField("String", "API_BASE_URL", "\"https://release.api.github.com\"")
            buildConfigField("String", "API_VERSION", "\"2022-11-28\"")
            // un comment it to run release build to test only using android studio
//            signingConfig = signingConfigs.getByName("debug")
        }

• Screen shot

Run release version

• Config details

        debug {
            manifestPlaceholders += mapOf("app_name" to "DebugGithubCruise")
            buildConfigField("boolean", "DEBUG", "true")
            buildConfigField("String", "API_BASE_URL", "\"https://api.github.com\"")
            buildConfigField("String", "API_VERSION", "\"2022-11-28\"")
            applicationIdSuffix = ".debug"
            versionNameSuffix = "debug"
        }

• Screen shot

Testing Guide

Write test case

• General - https://developer.android.com/training/testing
• Guide for unit test case - https://developer.android.com/training/testing/local-tests
• Guide for ui test case - https://developer.android.com/training/testing/instrumented-tests/ui-tests

Run test case

How to run test cases from UI

How to run test cases using command Arnav is my son name hahaha

Coding Guide

Test Case Document

• Testing Kotlin Coroutines
• Inject Scope
• General Guide:
  • Local Tests
  • Testing Flows

Coding

• Effortless Maintenance with MVVM Design Pattern Our app employs the MVVM (Model-View-ViewModel) design pattern, ensuring easy addition of new features and bug fixes without disrupting existing functionality.With MVVM, the codebase remains organized and easy to understand, streamlining development and maintenance tasks.By leveraging the latest libraries and Android SDK platform features, our app delivers a user-friendly experience on all devices, big or small. Check out the screenshots below to see how our app seamlessly integrates MVVM architecture for smooth functionality and hassle-free maintenance.

• MVVM - https://developer.android.com/codelabs/basic-android-kotlin-compose-viewmodel-and-state#7

• Localization

• Use ViewModel at Screen Level

• UI State

• UI State (StateFlow)

• Current Navigation Controller:

  • JetNews Navigation Graph
  • TodoApp Navigation Graph
  • Run Release Build:
    • In build.gradle, uncomment the following to run release build for testing only:

      // signingConfig = signingConfigs.getByName("debug")

• My app offers seamless UI development with a live preview feature, enabling rapid iterations and easy adjustments. With this functionality, developers can effortlessly write and modify UI components in seconds, streamlining the development process. Check out the screenshots below to see how my app simplifies UI development.

• ViewModel Test Guide

• Typography Guide

  • Material 3 Typography Overview

App navigation

• Follow official documentation Android Navigation

Package used

App Dependencies

• Timber: A logging utility that simplifies and enhances logging in Android applications.

Architecture Components

• Material 3: Implements the latest Material Design principles for a modern UI experience.
• Retrofit: A robust HTTP client for making API requests in a type-safe manner.
• Retrofit Converter (Moshi): Converts JSON responses into Kotlin objects efficiently using Moshi.
• Logging Interceptor: Helps in logging HTTP request and response data for debugging purposes.
• Moshi Kotlin: A JSON parsing library tailored for Kotlin, making JSON parsing a breeze.
• MockK: A mocking library specifically designed for Kotlin, aiding in unit testing.
• Coil: An image loading library optimized for Kotlin Coroutines and seamlessly integrated with Jetpack Compose.

Dependency Injection

• Hilt: A dependency injection framework that streamlines dependency injection setup in Android apps.
  • Hilt Android Core: Core components of the Hilt library for Android.
  • Hilt Navigation Compose: Integration of Hilt with Jetpack Compose's navigation system.
  • Hilt Compiler: Annotation processor required for using Hilt in your project.

Jetpack Compose

• Compose BOM: Manages versioning of Jetpack Compose libraries effectively.
• Activity Compose: Enables integration of Compose with Android's activity lifecycle.
• Compose Compiler: Enhances Compose development by providing a dedicated compiler plugin.
• Compose Foundation Core: Provides fundamental building blocks for creating Compose UIs.
• Compose UI Tooling Preview: Tools for previewing and debugging Compose UIs during development.
• Navigation Compose: Navigation library tailored for Jetpack Compose applications.
• Lifecycle Runtime Compose: Seamless integration of Jetpack Compose with Android's lifecycle.
• ViewModel Compose: Simplifies ViewModel integration in Jetpack Compose applications.

Debug Dependencies

• Compose UI Tooling Core: Core tools for Compose development, including preview and inspection capabilities.
• Compose UI Test Manifest: Manifest file required for testing Compose UI components in debug builds.

Testing Dependencies

• JUnit 4: A widely-used testing framework for writing and executing unit tests in Java applications.
• Kotlin Coroutines Test: Test utilities for verifying the behavior of Kotlin Coroutines.
• Android Test Implementation: Dependencies required for writing and running Android-specific unit tests.

Guide to inspect network performance

From bottom click app inspection while the app is running

Select from left side to see network details. See below picture

Setting Author template

Release Guide

Guide CI/CD For detailed guidance

• Github actions is used and it is passed details is written in this pr. #12
• Refer to: GitHub Actions Quickstart Github Actions (CI/CD)

How to Use This Repository's .yml File:

• Simply copy and paste the build.yml file into your repository under .github/workflows/build.yml, ensuring to specify the correct version of the Flutter SDK, and it will automatically start building.

APIs

API Used in the project

GitHub API:

• Base URL: https://api.github.com/

API Details documentation

User List API

• Doc: https://docs.github.com/en/rest/search/search?apiVersion=2022-11-28#search-users
• URL: https://api.github.com/search/users?q="dinkar1708"(with pagination // https://api.github.com/search/users?q=dinkar1708&page=1&per_page=1) User profile
• Doc: https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-a-user
• URL: https://api.github.com/users/dinkar1708 User repositories
• Doc: - https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-repositories-for-a-user
• URL: https://api.github.com/users/dinkar1708/repos?q=page=1&per_page=2

FAQ

• Supported 99.6% of market devices by using minimum 21 api level

• API pagination guide - Using Pagination in the REST API

• Find documentation -

• Run debug and release on same device together. See screen shots

DO/DON'T

TODO

• Fix app display name for debug and release apps.

• Implement search functionality for users on keyboard press events in the user list page, utilizing debounce and throttling techniques for efficient handling of input.

• Write UI test - https://developer.android.com/training/testing/instrumented-tests/ui-tests.

• Implement caching and refresh strategy for repository list page; add refresh button for manual API update; modify toggle to filter data from cache when on.

• Test the app on various screen sizes, including both small and large devices, to ensure optimal performance and UI compatibility. Address any UI bugs that may arise during testing.

• Conduct thorough testing on Android tablets to identify and rectify any remaining issues or bugs specific to tablet devices.

• Localization in ViewModel

  • Change string error messages to int and use them like:

    xxx.setValue(R.string.labelString)

• Fix app icons

  • fix rounded icon

• User Repositories API Pagination support When utilizing pagination in the user repositories API, it's essential to determine the total count of API results for effective navigation. Follow these steps to discover how to retrieve the total count:

  Step 1

  Access the following API endpoint:

  https://api.github.com/users/dinkar1708/repos?q=page=1&per_page=2
  

  This endpoint will return 2 results. However, it doesn't provide information about the total count of results.

  Step 2

  To obtain the total count, use the following API endpoint:

  https://api.github.com/users/dinkar1708/repos
  

  This endpoint will return 28 results, indicating that there is data available. By comparing the results from Step 1 and Step 2, you can discern the total count. Knowing the total count facilitates proper utilization of pagination.

• Verify Code Coverage

  • Code Coverage Guide

• Advance Screen Navigation

  • Try a common controller: Common Controller Example