diff --git a/README.md b/README.md
index ad54e9a..8fead4b 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,121 @@
 
 ![Unit tests](https://git.leomurca.xyz/leomurca/csgo-matches/actions/workflows/unit-tests.yml/badge.svg)
 
-**CS:GO Matches** is an Android app that displays Counter-Strike: Global Offensive (CS:GO) matches 
-from multiple global tournaments. It shows real-time and upcoming matches starting from the current 
-date, with detailed information on teams, players, and match times.
\ No newline at end of file
+**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) |
+
+## 🚀 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
+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.
\ No newline at end of file
diff --git a/docs/details.png b/docs/details.png
new file mode 100644
index 0000000..09f9035
Binary files /dev/null and b/docs/details.png differ
diff --git a/docs/home.png b/docs/home.png
new file mode 100644
index 0000000..d7e92f4
Binary files /dev/null and b/docs/home.png differ
diff --git a/docs/splash.png b/docs/splash.png
new file mode 100644
index 0000000..cf935eb
Binary files /dev/null and b/docs/splash.png differ