# CS:GO Matches

![Logo](/docs/logo.png)

![Unit tests](https://git.leomurca.xyz/leomurca/csgo-matches/actions/workflows/unit-tests.yml/badge.svg)

**CSGO Matches** is a modern Android app that displays upcoming and live Counter-Strike: 
Global Offensive matches using the [PandaScore API](https://www.pandascore.co/). The app is built 
with Jetpack Compose, MVVM, and a layered architecture that blends principles from Clean 
Architecture and Layered Architecture for simplicity, scalability, and testability.

## 📸 Screenshots

| Splash Screen                    | Match List                     | Match Details                     |
|----------------------------------|--------------------------------|-----------------------------------|
| ![Screenshot](./docs/splash.png) | ![Screenshot](./docs/home.png) | ![Screenshot](./docs/details.png) |

## ✨ Features

- 🔄 Real-time list of upcoming and live CSGO matches
- 🕒 Localized match time formatting (Hoje, Amanhã, weekday in pt-BR)
- 🎮 Team information and match time display
- 📱 Built with Jetpack Compose and Material 3
- 🔍 MVVM architecture for reactive UI state handling
- 🧱 Clean + Layered architecture for maintainability
- 🔃 **Pagination support** to load more matches as you scroll
- 🔁 **Pull-to-refresh** on the home screen to manually refresh data
- ✅ Unit tested with MockK and JUnit
- ⚙️ CI pipeline to automatically run tests on push to main

## 🚀 Getting Started

### ✅ Prerequisites
- Android Studio Giraffe or newer
- JDK 17 or higher
- Git installed

### 📥 Clone the Repository

```bash
git clone https://git.leomurca.xyz/leomurca/csgo-matches.git
cd csgo-matches
```

### 🔑 Configure API Access
This project integrates with the PandaScore API, and requires two secrets to run:

| Gradle Property | Description                      | Example                           |
|-----------------|----------------------------------|-----------------------------------|
| `API_BASE_URL`  | Base URL of the API              | `https://api.pandascore.co/csgo/` |
| `ACCESS_TOKEN`  | Your PandaScore API access token | `YOUR_API_KEY`                    |

You must define these two properties in your local Gradle environment.

Add the following lines to your global Gradle properties (`gradle.properties`):

```bash
API_BASE_URL=https://api.pandascore.co/csgo/
ACCESS_TOKEN=your_actual_token_here
```
### ▶️ Run the App
- Open the project in Android Studio
- Wait for Gradle sync to complete
- Connect an Android device or launch an emulator
- Click Run

## 🧱 Architecture Overview

The architecture follows a hybrid approach:

- 🧩 MVVM (Model–View–ViewModel): Used to manage UI state with Compose and ViewModels.
- 🧱 Layered Architecture: Presentation, domain, and data layers clearly separated.
- 🧼 Clean Architecture-inspired: The domain layer defines interfaces and models decoupled 
from frameworks (but no strict use case boundaries to avoid overengineering for this scope).

## 📐 Layer Breakdown

| Layer                 | Responsibilities                                                                 |
|-----------------------|----------------------------------------------------------------------------------|
| **UI (Presentation)** | Jetpack Compose UI, screen states, navigation, and ViewModels                    |
| **Domain**            | App’s business logic: pure models and repository interfaces                      |
| **Data**              | Implements repository interfaces, handles API calls, interceptors, DTOs, mappers |
| **DI**                | Centralized dependency injection configuration using Hilt                        |
| **Utils**             | Shared extension functions, helpers, and formatting logic                        |

## 📂 Folder Structure

```bash
xyz.leomurca.csgomatches/
├── data/                  # Data layer: API, DTOs, mappers, remote implementations
│   ├── mapper/            # DTO ↔ Domain model transformations
│   ├── model/             # API response models (DTOs)
│   ├── remote/            # Retrofit services, interceptors
│   ├── repository/        # Implements domain repositories
│   └── source/            # Data source abstractions
│
├── domain/                # Core business logic
│   ├── model/             # Domain-level models (pure Kotlin)
│   └── repository/        # Repository interfaces (contracts for data access)
│
├── ui/                    # Compose UI and ViewModel layer
│   ├── components/        # Reusable UI components (buttons, cards)
│   ├── navigation/        # Navigation graph
│   ├── screens/           # Individual screen UIs and ViewModels
│   └── theme/             # Material theme, colors, typography
│
├── di/                    # Hilt dependency injection modules
│   ├── DispatchersModule.kt
│   └── NetworkModule.kt
│
├── utils/                 # Helper functions and extensions
│
├── CSGOApplication.kt     # Custom Application class (Hilt entry point)
└── MainActivity.kt        # Main app entry point with Compose navigation
```

## ⚙️ Tech Stack
- Language: Kotlin
- UI: Jetpack Compose
- Architecture: MVVM + Layered/Clean mix
- Networking: Retrofit + OkHttp
- DI: Hilt
- Async: Kotlin Coroutines + Flow
- Testing: JUnit, MockK

## ✅ Testing & CI
The project includes targeted unit tests focused on key areas like data mapping, repository 
behavior, and time formatting logic.

**Test coverage includes:**
- Mapping from API models to domain models
- Remote data fetching logic
- Repository integration
- Date/time formatting for localized match display

To ensure quality, a Forgejo Actions CI pipeline runs automatically on every push to main, 
executing unit tests in a Docker-based Android environment.

This setup guarantees early detection of regressions and helps maintain stability as the 
project evolves.