csgo-matches/README.md

CS:GO Matches

CSGO Matches is a modern Android app that displays upcoming and live Counter-Strike: Global Offensive matches using the PandaScore API. 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

🚀 Getting Started

✅ Prerequisites

• Android Studio Giraffe or newer
• JDK 17 or higher
• Git installed

📥 Clone the Repository

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):

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

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.