📱 Crypto Portfolio Tracker - KMP

A production-ready Kotlin Multiplatform (KMP) application demonstrating modern mobile development practices with Clean Architecture, MVI pattern, and Compose Multiplatform. Track your cryptocurrency portfolio across Android, iOS, and Desktop platforms with a single shared codebase.

✨ Features

🎯 Core Functionality

• 📊 Real-time Crypto Tracking - Live cryptocurrency prices and market data
• 💼 Portfolio Management - Buy/sell cryptocurrencies with balance tracking
• 📈 Performance Analytics - Track your gains/losses with visual charts
• 🔄 Offline Support - Local database with Room for offline access
• 🎨 Material Design 3 - Modern UI with dynamic theming

🛠️ Technical Features

• 🔐 Secure API Key Management - Build-time injection with environment variants
• 🏗️ Clean Architecture - Separation of concerns with domain/data/presentation layers
• 🎭 MVI Pattern - Unidirectional data flow for predictable state management
• ⚠️ Type-safe Error Handling - Comprehensive Result<T, DataError> pattern with HTTP, network, and business errors
• 🔄 Type-safe Navigation - Compose Navigation 2.8+ with serialization
• 💉 Dependency Injection - Koin for KMP
• 🧪 Testable - Unit tests with Turbine and AssertK

🏗️ Architecture

📐 Clean Architecture Layers

┌─────────────────────────────────────────────┐
│         Presentation Layer (UI)              │
│  • Compose Multiplatform UI                  │
│  • MVI ViewModels                            │
│  • Navigation & State Management             │
├─────────────────────────────────────────────┤
│          Domain Layer (Business)             │
│  • Use Cases / Interactors                   │
│  • Domain Models                             │
│  • Repository Interfaces                     │
├─────────────────────────────────────────────┤
│           Data Layer (Sources)               │
│  • Repository Implementations                │
│  • Remote Data Sources (Ktor)               │
│  • Local Data Sources (Room)                │
│  • DTOs & Mappers                            │
└─────────────────────────────────────────────┘

🎭 MVI Pattern

┌──────────────┐
│   UI State   │ ◄─────┐
└──────────────┘       │
       │               │
       │ renders       │ updates
       ▼               │
┌──────────────┐       │
│     View     │       │
└──────────────┘       │
       │               │
       │ sends         │
       ▼               │
┌──────────────┐       │
│   Intent     │       │
└──────────────┘       │
       │               │
       │ processes     │
       ▼               │
┌──────────────┐       │
│  ViewModel   │───────┘
└──────────────┘

⚠️ Error Handling Architecture

Type-safe error handling with Result<T, DataError>:

┌─────────────────────────────────────────────────────────────┐
│                       DataError                              │
├─────────────────────────────────────────────────────────────┤
│  Remote (enum)         │  Local (enum)    │  Business       │
│  ─────────────────     │  ────────────    │  (sealed class) │
│  • UNAUTHORIZED        │  • DISK_FULL     │  • InvalidCreds │
│  • FORBIDDEN           │  • NOT_FOUND     │  • KycRequired  │
│  • NOT_FOUND           │  • INSUFFICIENT  │  • LimitReached │
│  • NO_INTERNET         │  • UNKNOWN       │  • SessionExpired│
│  • REQUEST_TIMEOUT     │                  │  • Unknown(code)│
│  • SERVER_ERROR        │                  │                 │
│  • SERIALIZATION       │                  │                 │
└─────────────────────────────────────────────────────────────┘

📚 Read more: Network & Error Handling

🚀 Tech Stack

Core

• Kotlin Multiplatform - Share code across platforms
• Compose Multiplatform - Declarative UI framework
• Kotlin Coroutines - Asynchronous programming

Networking & Data

• Ktor Client - HTTP networking
• Kotlinx Serialization - JSON serialization
• Room Database - Local persistence with KMP support

Architecture & DI

• Koin - Dependency injection for KMP
• Lifecycle ViewModel - State management
• Navigation Compose - Type-safe navigation

UI & Design

• Material Design 3 - Modern design system
• Coil 3 - Image loading for Compose
• Custom Design Tokens - Consistent theming

Build & Security

• Gradle Build Variants - Dev/Staging/Prod environments
• ProGuard/R8 - Code obfuscation & shrinking
• Detekt - Static code analysis
• ktlint - Code style enforcement & formatting

📦 Project Structure

Coins/
├── composeApp/                          # Main application module
│   ├── src/
│   │   ├── commonMain/                  # Shared code (all platforms)
│   │   │   └── kotlin/org/poc/app/
│   │   │       ├── core/                # Core utilities & config
│   │   │       │   ├── config/          # App configuration & BuildConfig
│   │   │       │   ├── data/            # Core data (database, network)
│   │   │       │   │   ├── network/     # HTTP client, error handling
│   │   │       │   │   └── datasource/  # Data source interfaces
│   │   │       │   ├── domain/          # Core domain models (Result, DataError)
│   │   │       │   └── presentation/    # MVI base classes
│   │   │       ├── feature/             # Feature modules
│   │   │       │   ├── coins/           # Crypto list feature
│   │   │       │   ├── portfolio/       # Portfolio feature
│   │   │       │   └── trade/           # Buy/Sell feature
│   │   │       ├── navigation/          # App navigation
│   │   │       └── ui/                  # Design system
│   │   │           ├── components/      # Reusable UI components
│   │   │           ├── foundation/      # Colors, typography, spacing
│   │   │           └── theme/           # Theme configuration
│   │   ├── androidMain/                 # Android-specific code
│   │   ├── iosMain/                     # iOS-specific code
│   │   └── desktopMain/                 # Desktop-specific code
│   ├── build.gradle.kts                 # Build configuration
│   └── proguard-rules.pro              # ProGuard rules
├── iosApp/                              # iOS Xcode project
├── docs/
│   └── NETWORK_AND_ERROR_HANDLING.md   # Error handling architecture
├── config/
│   └── detekt/detekt.yml               # Code quality config
├── local.properties.example             # Template for API keys
├── API_KEYS_SETUP.md                   # API key security guide
├── BUILD_VARIANTS.md                   # Build variants documentation
└── README.md                           # This file

🛠️ Setup & Installation

Prerequisites

• JDK 17+ - Java Development Kit
• Android Studio Ladybug+ - Latest stable version
• Xcode 15+ (for iOS) - macOS only
• Gradle 8.14+ - Build tool

1️⃣ Clone the Repository

git clone https://github.com/hossam9k/Coins.git
cd Coins

2️⃣ Configure API Keys

# Copy the example file
cp local.properties.example local.properties

# Edit and add your API keys
# Get free API keys from: https://coincap.io/
nano local.properties

local.properties:

# Development
DEV_COINCAP_API_KEY=your_dev_key_here
DEV_API_BASE_URL=https://api.coincap.io/v2

# Staging
STAGING_COINCAP_API_KEY=your_staging_key_here
STAGING_API_BASE_URL=https://api.coincap.io/v2

# Production
PROD_COINCAP_API_KEY=your_prod_key_here
PROD_API_BASE_URL=https://api.coincap.io/v2

📚 Read more: API_KEYS_SETUP.md

3️⃣ Build & Run

Android

# Development build
./gradlew :composeApp:assembleDevDebug

# Install to device
./gradlew :composeApp:installDevDebug

iOS (macOS only)

# Build iOS framework
./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64

# Open Xcode project
open iosApp/iosApp.xcodeproj

Desktop

# Run desktop app
./gradlew :composeApp:run

📚 Read more: BUILD_VARIANTS.md

🎯 Build Variants

The project supports three environment variants:

Variant	App ID	Debug	Analytics	Use Case
dev	org.poc.app.dev	✅	❌	Local development
staging	org.poc.app.staging	❌	✅	QA testing
prod	org.poc.app	❌	✅	Production

# Build different variants
./gradlew :composeApp:assembleDevDebug
./gradlew :composeApp:assembleStagingDebug
./gradlew :composeApp:assembleProdRelease

🧪 Testing

Run Unit Tests

./gradlew test

Run Android Instrumentation Tests

./gradlew :composeApp:connectedDevDebugAndroidTest

Code Quality Analysis

# Run Detekt static analysis
./gradlew detekt

# Run ktlint code style check
./gradlew ktlintCheck

# Auto-format code with ktlint
./gradlew ktlintFormat

📱 Screenshots

Coming soon...

🔐 Security & Code Quality

Security Features

• ✅ No Hardcoded Secrets - API keys in gitignored local.properties
• ✅ Build-time Injection - Keys embedded during compilation
• ✅ ProGuard Obfuscation - Code obfuscation in release builds
• ✅ Environment Separation - Different keys per environment
• ✅ CI/CD Ready - Environment variable support

Code Quality

• ✅ Detekt - Static code analysis with custom rules
• ✅ ktlint - Automated code formatting & style enforcement
• ✅ Compose Function Naming - Proper @Composable conventions
• ✅ Explicit Imports - No wildcard imports for clarity
• ✅ Consistent Naming - SCREAMING_SNAKE_CASE for constants

📚 Documentation

• 📖 API Keys Security Setup
• 📖 Build Variants Guide
• 📖 Network & Error Handling
• 📖 Architecture Documentation (coming soon)
• 📖 Contributing Guide (coming soon)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• CoinCap API - Cryptocurrency data provider
• Kotlin Multiplatform
• Compose Multiplatform
• Material Design 3

📞 Contact

Hossam Atef - @hossam9k

Project Link: https://github.com/hossam9k/Coins