{"id":20849751,"url":"https://github.com/mahmoodhamdi/tstore","last_synced_at":"2025-12-24T08:43:24.873Z","repository":{"id":224109742,"uuid":"762054189","full_name":"mahmoodhamdi/TStore","owner":"mahmoodhamdi","description":"A full-featured Flutter eCommerce app with Firebase integration. Built using clean architecture, SOLID principles, design patterns, and modern UI for an optimal user experience.","archived":false,"fork":false,"pushed_at":"2025-02-12T15:35:01.000Z","size":102504,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-12T16:35:51.998Z","etag":null,"topics":["authentication","cicd","clean-architecture","clean-code","dart","ecommerce","fastlane","firebase","firebase-auth","firebase-database","firebase-distribution","flutter","flutter-examples","flutter-ui","github-actions","mvvm-architecture","open-source","repository-pattern","ui"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mahmoodhamdi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-23T01:50:46.000Z","updated_at":"2025-02-12T15:35:07.000Z","dependencies_parsed_at":"2025-02-12T16:38:16.506Z","dependency_job_id":null,"html_url":"https://github.com/mahmoodhamdi/TStore","commit_stats":null,"previous_names":["mahmoodhamdi/tstore"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoodhamdi%2FTStore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoodhamdi%2FTStore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoodhamdi%2FTStore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahmoodhamdi%2FTStore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mahmoodhamdi","download_url":"https://codeload.github.com/mahmoodhamdi/TStore/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243213981,"owners_count":20254902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","cicd","clean-architecture","clean-code","dart","ecommerce","fastlane","firebase","firebase-auth","firebase-database","firebase-distribution","flutter","flutter-examples","flutter-ui","github-actions","mvvm-architecture","open-source","repository-pattern","ui"],"created_at":"2024-11-18T03:06:34.446Z","updated_at":"2025-12-24T08:43:24.865Z","avatar_url":"https://github.com/mahmoodhamdi.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TStore - Flutter E-Commerce App\n\n[![Flutter](https://img.shields.io/badge/Flutter-3.38.4-blue.svg)](https://flutter.dev)\n[![Dart](https://img.shields.io/badge/Dart-3.10.3-blue.svg)](https://dart.dev)\n[![Supabase](https://img.shields.io/badge/Supabase-Backend-green.svg)](https://supabase.com)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![wakatime](https://wakatime.com/badge/user/018c9017-daf8-45c1-be71-8b16fd238022/project/018e3724-1bcf-41fe-86c2-770c411d1f5f.svg)](https://wakatime.com/badge/user/018c9017-daf8-45c1-be71-8b16fd238022/project/018e3724-1bcf-41fe-86c2-770c411d1f5f)\n\nA full-featured e-commerce mobile application built with Flutter and Supabase, following Clean Architecture principles and SOLID design patterns. This project serves as a production-ready template for building scalable Flutter applications.\n\n## Screenshots\n\n\u003c!-- Add your screenshots here --\u003e\n| Home | Products | Product Details |\n|------|----------|-----------------|\n| ![Home](screenshots/home.png) | ![Products](screenshots/products.png) | ![Details](screenshots/details.png) |\n\n## Features\n\n### Implemented\n- [x] User Authentication (Email/Password)\n- [x] OAuth Support (Google, Facebook, Apple - Ready)\n- [x] Password Recovery Flow\n- [x] OnBoarding Screens\n- [x] Home Screen with Dynamic Banner Carousel\n- [x] Product Listing (Grid/List View)\n- [x] Product Search \u0026 Filtering\n- [x] Product Sorting (Price, Rating, etc.)\n- [x] Product Details with Variations\n- [x] Categories \u0026 Brands\n- [x] Wishlist Management\n- [x] Shopping Cart\n- [x] Order Management\n- [x] User Profile Management\n- [x] Address Management\n- [x] Product Reviews \u0026 Ratings\n- [x] Real-time Chat Support\n- [x] Notifications System\n- [x] Coupon System\n- [x] Light/Dark Theme Support\n- [x] Shimmer Loading Effects\n- [x] Responsive Design\n\n### Planned\n- [ ] Push Notifications (FCM)\n- [ ] Payment Integration (Stripe)\n- [ ] Multi-language Support (i18n)\n- [ ] Analytics Dashboard\n\n## Architecture\n\nThis project follows **Clean Architecture** with three main layers:\n\n```\nlib/\n├── core/                          # Shared functionality\n│   ├── common/                    # Shared widgets \u0026 view models\n│   ├── cubits/                    # App-wide state management\n│   ├── supabase/                  # Supabase client \u0026 services\n│   ├── utils/                     # Constants, helpers, themes\n│   └── dependency_injection/      # Service locator (GetIt)\n│\n└── features/                      # Feature modules\n    ├── auth/                      # Authentication feature\n    │   ├── data/                  # Data sources, models, repos\n    │   ├── domain/                # Entities, repos, use cases\n    │   └── presentation/          # UI, cubits, widgets\n    │\n    ├── shop/                      # Shop feature (Products, Categories, Brands)\n    │   ├── data/\n    │   ├── domain/\n    │   └── presentation/\n    │\n    ├── cart/                      # Shopping Cart\n    ├── wishlist/                  # Wishlist\n    ├── orders/                    # Order Management\n    ├── reviews/                   # Product Reviews\n    ├── chat/                      # Real-time Chat\n    ├── notifications/             # Notifications\n    │\n    └── personalization/           # User Profile \u0026 Settings\n        ├── data/\n        ├── domain/\n        └── presentation/\n```\n\n### Key Design Patterns\n- **Repository Pattern** - Abstracts data sources\n- **Use Case Pattern** - Single responsibility for business logic\n- **BLoC/Cubit Pattern** - Predictable state management\n- **Dependency Injection** - Using GetIt for loose coupling\n\n## Tech Stack\n\n| Category | Technology |\n|----------|------------|\n| Framework | Flutter 3.38.4 |\n| Language | Dart 3.10.3 |\n| Backend | Supabase (PostgreSQL) |\n| Authentication | Supabase Auth |\n| Database | Supabase Database |\n| Storage | Supabase Storage |\n| Realtime | Supabase Realtime |\n| State Management | flutter_bloc 9.1.1 |\n| Dependency Injection | get_it 9.2.0 |\n| Error Handling | dartz 0.10.1 |\n| Image Caching | cached_network_image 3.4.1 |\n| Environment | flutter_dotenv 5.2.1 |\n\n## Getting Started\n\n### Prerequisites\n- Flutter SDK 3.38.4 or higher\n- Dart SDK 3.10.3 or higher\n- Android Studio / VS Code\n- Supabase Account (free tier available)\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/mahmoodhamdi/TStore.git\n   cd TStore\n   ```\n\n2. **Install dependencies**\n   ```bash\n   flutter pub get\n   ```\n\n3. **Setup Supabase**\n\n   a. Create a Supabase project at [Supabase Dashboard](https://supabase.com/dashboard)\n\n   b. Run the database schema:\n      - Go to SQL Editor in Supabase Dashboard\n      - Copy contents of `supabase_schema.sql` and run it\n      - Copy contents of `supabase_sample_data.sql` and run it (optional - adds sample data)\n\n   c. Create Storage Buckets:\n      - Go to Storage in Supabase Dashboard\n      - Create buckets: `avatars`, `products`, `reviews`, `chat`\n      - Set each bucket to public (for image access)\n\n4. **Environment Variables**\n\n   Create a `.env` file in the root directory:\n   ```env\n   SUPABASE_URL=https://your-project.supabase.co\n   SUPABASE_ANON_KEY=your-anon-key\n   ```\n\n   Find these values in: Supabase Dashboard \u003e Settings \u003e API\n\n5. **Run the app**\n   ```bash\n   # Development\n   flutter run -t lib/main_development.dart\n\n   # Production\n   flutter run -t lib/main_production.dart\n   ```\n\n## Project Structure\n\n```\nTStore/\n├── android/                 # Android native code\n├── ios/                     # iOS native code\n├── lib/\n│   ├── core/               # Core functionality\n│   │   ├── supabase/       # Supabase services\n│   │   └── ...\n│   ├── features/           # Feature modules\n│   ├── main_development.dart\n│   ├── main_production.dart\n│   └── t_store.dart        # App entry point\n├── test/                   # Unit \u0026 widget tests\n├── assets/\n│   ├── fonts/              # Custom fonts\n│   ├── images/             # Image assets\n│   ├── icons/              # Icon assets\n│   └── logos/              # Logo assets\n├── supabase_schema.sql     # Database schema\n├── supabase_sample_data.sql # Sample data with real images\n├── pubspec.yaml\n└── README.md\n```\n\n## Commands\n\n```bash\n# Get dependencies\nflutter pub get\n\n# Run development build\nflutter run -t lib/main_development.dart\n\n# Run production build\nflutter run -t lib/main_production.dart\n\n# Build APK\nflutter build apk -t lib/main_production.dart\n\n# Build App Bundle\nflutter build appbundle -t lib/main_production.dart\n\n# Run all tests\nflutter test\n\n# Run tests with coverage\nflutter test --coverage\n\n# Run specific test file\nflutter test test/unit/auth/auth_cubit_test.dart\n\n# Run all unit tests\nflutter test test/unit/\n\n# Run all integration tests\nflutter test test/integration/\n\n# Analyze code\nflutter analyze\n\n# Generate launcher icons\nflutter pub run flutter_launcher_icons\n\n# Generate splash screen\nflutter pub run flutter_native_splash:create\n```\n\n## Testing\n\nThe project includes comprehensive unit and integration tests covering all features.\n\n### Test Structure\n\n```\ntest/\n├── unit/\n│   ├── auth/\n│   │   ├── auth_cubit_test.dart        # 16 tests\n│   │   ├── auth_repository_test.dart   # 17 tests\n│   │   └── auth_usecases_test.dart     # 12 tests\n│   ├── shop/\n│   │   ├── products_cubit_test.dart    # 15 tests\n│   │   └── shop_usecases_test.dart     # 17 tests\n│   ├── cart/\n│   │   └── cart_cubit_test.dart        # 23 tests\n│   ├── wishlist/\n│   │   └── wishlist_cubit_test.dart    # 20 tests\n│   ├── orders/\n│   │   └── orders_cubit_test.dart      # 16 tests\n│   ├── reviews/\n│   │   └── reviews_cubit_test.dart     # 16 tests\n│   ├── chat/\n│   │   └── chat_cubit_test.dart        # 17 tests\n│   ├── notifications/\n│   │   └── notifications_cubit_test.dart # 17 tests\n│   └── personalization/\n│       └── personalization_cubit_test.dart # 22 tests\n│\n├── integration/\n│   └── auth_flow_test.dart             # 11 tests\n│\n└── widget_test.dart\n```\n\n### Test Statistics\n\n| Category | Tests | Coverage |\n|----------|-------|----------|\n| Auth Unit Tests | 45 | Cubit, Repository, UseCases |\n| Shop Unit Tests | 32 | Cubit, UseCases, Entity helpers |\n| Cart Unit Tests | 23 | Cubit, Entity calculations |\n| Wishlist Unit Tests | 20 | Cubit, State management |\n| Orders Unit Tests | 16 | Cubit, Entity helpers |\n| Reviews Unit Tests | 16 | Cubit, Entity helpers, Stats |\n| Chat Unit Tests | 17 | Cubit, Entity, Message types |\n| Notifications Unit Tests | 17 | Cubit, Entity, Actions |\n| Personalization Unit Tests | 22 | Profile, Addresses Cubits |\n| Integration Tests | 11 | Complete auth flow |\n| **Total** | **219** | - |\n\n### Running Tests\n\n```bash\n# Run all tests\nflutter test\n\n# Run with verbose output\nflutter test --reporter expanded\n\n# Run specific feature tests\nflutter test test/unit/auth/\nflutter test test/unit/shop/\nflutter test test/unit/cart/\nflutter test test/unit/wishlist/\nflutter test test/unit/orders/\n\n# Run integration tests\nflutter test test/integration/\n\n# Generate coverage report\nflutter test --coverage\ngenhtml coverage/lcov.info -o coverage/html\nopen coverage/html/index.html  # macOS\nstart coverage/html/index.html # Windows\n```\n\n### Test Dependencies\n\n```yaml\ndev_dependencies:\n  flutter_test:\n    sdk: flutter\n  mocktail: ^1.0.4      # For mocking\n  bloc_test: ^10.0.0    # For Cubit testing\n```\n\n## Database Schema\n\nThe app uses Supabase (PostgreSQL) with the following tables:\n\n| Table | Description |\n|-------|-------------|\n| profiles | User profiles (linked to auth.users) |\n| categories | Product categories |\n| brands | Product brands |\n| products | Product catalog |\n| wishlist | User wishlists |\n| cart_items | Shopping cart items |\n| orders | User orders |\n| order_items | Order line items |\n| reviews | Product reviews |\n| addresses | User addresses |\n| banners | Promotional banners |\n| chat_messages | Support chat messages |\n| notifications | User notifications |\n| coupons | Discount coupons |\n\n## Sample Data\n\nThe `supabase_sample_data.sql` includes:\n- 5 Categories (Electronics, Clothes, Shoes, Furniture, Accessories)\n- 5 Brands\n- 29 Products with real images\n- 5 Promotional Banners\n- 3 Discount Coupons (WELCOME10, SAVE20, FLASH25)\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) first.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Code Style\n- Follow [Effective Dart](https://dart.dev/guides/language/effective-dart)\n- Use meaningful variable and function names\n- Write unit tests for new features\n- Update documentation as needed\n\n## Roadmap\n\n### v1.1.0 (Current)\n- [x] Supabase migration (completed)\n- [x] Unit tests coverage (219 tests)\n- [x] Integration tests (auth flow)\n- [ ] Performance optimizations\n\n### v1.2.0\n- [ ] Push notifications\n- [ ] Payment integration (Stripe)\n- [ ] Order tracking\n\n### v2.0.0\n- [ ] Multi-language support (i18n)\n- [ ] Admin dashboard\n- [ ] Analytics\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Mahmoud Hamdy**\n- LinkedIn: [@mahmoud-hamdy-alashwah](https://www.linkedin.com/in/mahmoud-hamdy-alashwah/)\n- GitHub: [@mahmoodhamdi](https://github.com/mahmoodhamdi)\n- Email: hmdy7486@gmail.com\n\n## Acknowledgments\n\n- [Flutter Team](https://flutter.dev) for the amazing framework\n- [Supabase Team](https://supabase.com) for the open-source backend\n- [Bloc Library](https://bloclibrary.dev) for state management\n- [Platzi Fake Store API](https://fakeapi.platzi.com/) for sample product images\n- All contributors who helped improve this project\n\n---\n\nIf you find this project helpful, please give it a star!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoodhamdi%2Ftstore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmahmoodhamdi%2Ftstore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoodhamdi%2Ftstore/lists"}