KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

Supplr

★ 16 Open GitHub ↗

Supplr is a modern, modular, and scalable e-commerce application targeting both Android and iOS platforms. Built with Kotlin Multiplatform (KMP) and Jetpack Compose Multiplatform, it allows users to browse products, add to cart, place orders, manage their profiles, and manage their favorite products.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🛒 Supplr - Kotlin Multiplatform E-Commerce App

![Android](https://img.shields.io/badge/Android-✅-green)
![iOS](https://img.shields.io/badge/iOS-✅-blue)
![Kotlin](https://img.shields.io/badge/Kotlin-Multiplatform-orange)
![Jetpack Compose](https://img.shields.io/badge/Jetpack%20Compose-%F0%9F%9A%80-orange)
![Koin](https://img.shields.io/badge/Koin-DI-yellow)
![Open Source](https://img.shields.io/badge/Open%20Source-%E2%9C%94%EF%B8%8F-lightgrey)

---

## 🚀 About the Project

**Supplr** is a modern, modular, and scalable e-commerce application targeting both Android and iOS platforms. Built with Kotlin Multiplatform (KMP) and Jetpack Compose Multiplatform, it allows users to browse products, add to cart, place orders, manage their profiles, and manage their favorite products. Features include **location management**, **Stripe payment integration**, and a comprehensive **admin analytics dashboard** for business insights and product management.

---

## 📦 Features

### 🛒 Customer Features
- 🔥 **Kotlin Multiplatform**: Single codebase for Android & iOS
- 🎨 **Modern UI**: Responsive and animated interface with Jetpack Compose Multiplatform
- 🗂️ **Contact Us**: Customer support and communication
- 🛒 **Cart & Order Management**: Full shopping cart with order tracking
- 👤 **User Profile & Authentication**: Secure user management
- 🏷️ **Category & Product Listing**: Browse products by categories
- 💳 **Checkout & Order Completion**: Seamless payment experience
- ❤️ **Favorites**: Save and manage favorite products
- 🗺️ **Location Management**: Address management with categories (Home, Work, Other)
- 💳 **Stripe Payment Integration**: Real PaymentSheet (Android) / Simulated (iOS)
- 🔔 **Push Notification Support**: Personalized notifications
- 📦 **Order History**: View and track all past orders with detailed status
- ⭐ **Product Reviews**: Rate products, write reviews with photos, helpful/unhelpful voting
- 🎁 **Coupon & Discounts**: Apply coupon codes at checkout (percentage, fixed, free shipping)
- 👤 **Profile Settings**: Communication preferences, security settings, account management
- 🔐 **Security Features**: Two-factor authentication, password change, account deletion
- 🎮 **Gamification**: Leaderboard rankings and Spin Wheel for daily prizes

### 📊 Admin Features
- 🛠️ **Admin Panel**: Comprehensive product and analytics management
- 📈 **Analytics Dashboard**: Real-time business insights with interactive charts
- 📊 **Revenue Analytics**: Daily revenue tracking with enhanced line charts
- 🏆 **Top Products**: Best-selling products analysis
- 👥 **User Statistics**: User growth and engagement metrics
- 📅 **Date Range Filtering**: Flexible time period analysis
- 🔄 **Real-time Data**: Auto-refreshing dashboard with pull-to-refresh
- 🎨 **Interactive Charts**: Custom Canvas-based charts with animations
- 📱 **Responsive Design**: Optimized for all screen sizes
- 🔐 **Secure Access**: Role-based authentication and Firestore security rules
- 🛠️ **Order Management**: View all orders, update status, cancel orders (except delivered)

### 🏗️ Technical Features
- 🔐 **Firebase Authentication & Firestore**
- 🏗️ **Dependency Injection with Koin**
- 🌐 **Networking with Ktor**
- 🖼️ **Image Loading with Coil** - Platform-specific caching (25% memory, 100MB disk)
- 🧪 **Comprehensive Unit Testing** - 50+ tests with Turbine, Coroutines Test
- 📄 **Cursor-based Pagination** - Efficient Firestore data fetching with `startAfter()`
- ♾️ **Infinite Scroll** - Automatic page loading with LazyColumn scroll detection
- ⚡ **Code Splitting** - Module-based lazy loading for faster startup performance

---

## 🏗️ Project & Module Structure

```
- composeApp/      : Main multiplatform entry point and general UI.
- iosApp/          : iOS app entry (integrated with SwiftUI).
- feature/
    - auth/              : Authentication (login, register).
    - cart/              : Cart management.
    - home/              : Home screen and navigation.
    - profile/           : User profile management, settings, security features.
    - admin_panel/       : 📊 Admin analytics dashboard with charts and insights.
    - manage_product/    : Admin add, edit, delete products.
    - product_details/   : Product details.
    - products_overview/ : Home screen new & discounted product listing.
    - payment_completed/ : Order completed screen and post-order.
    - categories/        : Category management.
    - contact_us/        : Contact with Us.
    - favorites/         : Favorites screen and logic.
    - locations/         : User address management with categories.
    - checkout/          : Payment processing with Stripe integration.
    - order_history/     : 📦 Customer order history and tracking.
    - gamification/      : 🎮 Gamification with Leaderboard and Spin Wheel.
- data/            : Data layer, repositories, and services.
- shared/          : Shared domain models, utils, constants.
- di/              : Dependency injection modules (Koin).
- navigation/      : Navigation graph and routing.
```

---

## 🧩 Architecture

- **Clean Architecture**: Data → Domain → Presentation layers
- **Feature-based modules**: Independent development and testing
- **Centralized DI with Koin**: All ViewModels and repositories managed centrally
- **Testability**: Mockable repository interfaces and ViewModels
- **Analytics Architecture**: Dedicated analytics layer with real-time data processing

---

## 🛠️ Tech Stack

### Core Technologies
- **Kotlin Multiplatform (KMP)**
- **Jetpack Compose Multiplatform**
- **Koin** (Dependency Injection)
- **Firebase** (Auth, Firestore, Storage, Push Notification)
- **Ktor** (HTTP Client & Stripe API Integration)
- **Stripe SDK** (Android: PaymentSheet, iOS: Simulated Payment Flow)

### UI & Analytics
- **Material3** (Modern UI components)
- **Custom Canvas Charts** (Analytics visualizations)
- **Coil** (Image Loading)
- **Navigation Compose**
- **MessageBar KMP**
- **Animated Components** (Enhanced user experience)

### Data & Storage
- **Coroutines & Flow**
- **Multiplatform Settings**
- **Firebase Firestore** (with comprehensive security rules)
- **Real-time Data Synchronization**

---

## 📱 Screenshots

### Android

### IOS

## 🎉 Recent Updates

### 🧪 Unit Testing Infrastructure (Latest)
- **Comprehensive Test Suite** - 50+ unit tests across domain, repository, and ViewModel layers
- **Testing Libraries** - kotlin-test, kotlinx-coroutines-test, Turbine
- **Domain Tests** - RequestState, Product, Customer, CartItem, PaginatedResult
- **Fake Repositories** - FakeFavoritesRepository, FakeProductRepository for isolated testing
- **ViewModel Tests** - FavoritesViewModel with StateFlow and callback verification
- **Run Tests** - `./gradlew :shared:testDebugUnitTest :data:testDebugUnitTest`

### 🎮 Gamification System
- **Leaderboard** - View top shoppers and compete with other customers
- **User Rankings** - Track your position among all users
- **Spin Wheel** - Daily spin for amazing prizes and discounts
- **Prize Rewards** - Earn coupons, discounts, and special offers
- **Animated UI** - Smooth animations and engaging user experience
- **Real-time Updates** - Live leaderboard data from Firestore

### ⚡ Code Splitting & Performance (Latest)
- **Module-based Lazy Loading** - Feature modules load on-demand for faster startup
- **ModuleLoader Utility** - Centralized module loading with `ModuleType` enum
- **Lazy Module Types** - Admin, Secondary, and Gamification modules
- **Navigation Integration** - Automatic module loading before screen navigation
- **Startup Optimization** - Only core and auth modules loaded at app start

### 🚀 Lazy Loading & Image Caching
- **Cursor-based Pagination** - Firestore `startAfter()` and `limit()` for efficient data fetching
- **PaginatedResult<T>** - Generic data class with `items`, `lastDocumentId`, `hasNextPage`
- **PaginationState** - UI state management (Idle, Loading, LoadingMore, EndReached, Error)
- **Infinite Scroll** - LazyColumn scroll detection with automatic page fetching
- **CachedAsyncImage** - Reusable composable with shimmer placeholder and error handling
- **Platform-specific ImageLoader** - Android/iOS image loader with expect/actual pattern
- **Memory Cache** - 25% of available memory for optimal performance
- **Disk Cache** - 100MB in app cache directory for offline access
- **Applied to** - CategorySearchScreen, ProductCard, HomeProductCard

### 🎁 Coupon and Discount Code System
- **Coupon Code Input** - Apply coupons at checkout
- **Multiple Coupon Types** - Percentage, Fixed Amount, Free Shipping
- **Real-time Validation** - Expiration, usage limit, minimum order checks
- **Discount Display** - Strikethrough original price, show savings
- **Order Integration** - Coupon tracked in order with discount details
- **Usage Tracking** - Automatic usage count increment on order
- **Firestore Collection** - `coupons` collection for coupon management

### 👤 Profile Enhancements (Latest)
- **Settings Screen** - Centralized settings with communication preferences
- **Communication Preferences** - Email, push notification, SMS notification toggles
- **Password Change** - Secure password update with current password verification
- **Two-Factor Authentication** - Enable/disable 2FA for enhanced security
- **Account Deletion** - Permanent account deletion with password confirmation
- **Birth Date** - User birth date for personalized discounts
- **Profile Photo** - Profile photo URL management
- **Drawer Navigation** - Settings accessible from navigation drawer

### ⭐ Product Review System
- **Star Ratings** - Users can rate products with 1-5 stars
- **Written Reviews** - Detailed review comments with 500 character limit
- **📷 Photo Upload** - Attach photos to reviews (Firebase Storage)
- **👍👎 Helpful Voting** - Vote on review helpfulness with atomic counters
- **Real-time Updates** - Average rating and count update instantly
- **Separate Review Page** - Dedicated `AddReviewScreen` for writing reviews
- **Photo Gallery** - `ReviewPhotosGallery` component for displaying review images
- **Vote Tracking** - `review_votes` Firestore collection for vote management
- **User Restrictions** - Cannot vote on own reviews, one vote per review

### 🛠️ Admin Order Management & Order History
- **Admin Order Management** - View and manage all customer orders
- **Order Status Updates** - Progress orders through PENDING → CONFIRMED → PREPARING → SHIPPED → DELIVERED
- **Order Cancellation** - Cancel orders (except delivered/cancelled)
- **Order Detail View** - Comprehensive order details with status timeline
- **Customer Order History** - Users can view their order history and track status
- **Real-time Updates** - Live order status synchronization
- **Status Timeline** - Visual order progress tracking
- **Modern UI** - Consistent design with existing admin panel

### 📊 Analytics Dashboard
- **Interactive Revenue Charts** with custom Canvas drawing
- **Real-time Business Metrics** (revenue, orders, average order value)
- **Enhanced Line Charts** with grid lines, axes, and point connections
- **Top-selling Products Analysis** with visual indicators
- **User Statistics Tracking** with growth metrics
- **Date Range Filtering** (Today, Last 7 Days, Last 30 Days)
- **Animated Components** with staggered loading effects
- **Loading States** with shimmer effects
- **Error Handling** with retry mechanisms
- **Responsive Design** for all screen sizes

### 🗺️ Location Management
- **User-friendly address management** with add/edit functionality
- **Categorized locations:** Home 🏠, Work 🏢, Other 📍
- **Integrated into custom drawer** for easy access
- **Firebase Firestore storage** with user-specific security rules

### 💳 Stripe Payment Integration
- **Multi-platform payment processing** 
- **Android:** Real Stripe PaymentSheet for native payment experience
- **iOS:** Realistic simulated payment flow with same UX
- **Dynamic API key management** from shared constants
- **Complete order management** with payment tracking
- **"Pay with Card" 💳 and "Pay on Delivery" 🚚** options

### ❤️ Enhanced User Experience
- **Advanced review system** - Star ratings, photos, and helpful voting
- **Favorites management** with instant updates
- **Responsive design** for all screen sizes
- **Bottom sheet experiences** consistent across platforms

---

## 🚀 Installation & Running

### Requirements

- **JDK 17+**
- **Android Studio Giraffe or newer**
- **Xcode 14+ (for iOS)**

### Clone the Project

```sh
git clone https://github.com/kaaneneskpc/Supplr.git
cd Supplr
```

### Run for Android

```sh
./gradlew :composeApp:installDebug
```

### Run for iOS

1. Open `iosApp/iosApp.xcodeproj` in Xcode.
2. Configure as needed and run.

---

## 🔐 Security & Firebase Rules

### Admin Panel Security
- **Role-based Authentication**: Admin access controlled via email verification
- **Firestore Security Rules**: Comprehensive rules for analytics, dashboard data, and admin logs
- **Data Isolation**: User-specific data access with proper authorization
- **Audit Trail**: Admin actions logged with timestamps and details

### Supported Collections
- `analytics/` - Analytics data (admin-only read/write)
- `admin_dashboard/` - Dashboard configuration (admin-only)
- `user_stats/` - User statistics (admin-only read)
- `sales_analytics/` - Sales data (admin-only)
- `product_analytics/` - Product performance (admin-only)
- `admin_logs/` - Audit trail (admin-only read, create-only)

---

## 🧑‍💻 Contributing

Contributions are welcome! 🎉 Fork, create a new branch, and submit your changes as a PR.

### Contribution Steps

1. Fork 🍴
2. Create a new branch 🚀 (`git checkout -b feature-name`)
3. Commit your changes 🎯 (`git commit -m 'Description'`)
4. Push the branch 📤 (`git push origin feature-name`)
5. Open a Pull Request 🔥

### Areas for Contribution
- **Analytics Enhancements**: New chart types, advanced metrics
- **UI/UX Improvements**: Better animations, responsive design
- **Performance Optimizations**: Chart rendering, data loading
- **Testing**: Unit tests, UI tests for admin features
- **Documentation**: Code documentation, user guides

---

## 📝 License

This project is open source and available under the [MIT License](LICENSE).

---

## 📚 Resources & Inspiration

- [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html)
- [Jetpack Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/)
- [Koin DI](https://insert-koin.io/)
- [Firebase](https://firebase.google.com/)
- [Ktor](https://ktor.io/)
- [Coil](https://coil-kt.github.io/coil/)
- [Canvas Drawing in Compose](https://developer.android.com/jetpack/compose/graphics/draw/overview)

---

> **Note:** For more details and architectural explanations, see the [PRD document](./prd.md).

---

## Contact

**Kaan Enes Kapıcı**
- LinkedIn: [Kaan Enes Kapıcı](https://www.linkedin.com/in/kaaneneskpc/)
- GitHub: [@kaaneneskpc](https://github.com/kaaneneskpc)
- Email: kaaneneskpc1@gmail.com

💡 **Open to feedback and collaboration!** If you're interested in modern mobile architecture, analytics dashboards, or multiplatform development, feel free to connect. 🚀

Supplr

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README