Stream Cart Mobile

A production‑ready microservices-based live commerce & e‑commerce Flutter application

📖 Table of Contents

🎯 Overview
✨ Feature Matrix
🚀 Current Development Status
🛠️ Recent Updates
🏗️ Architecture
🔧 Tech Stack
📱 Screenshots
🚀 Getting Started
🔨 Development
🧪 Testing
📦 Build & Deploy
🤝 Contributing
📞 Support & Contact
📄 License

🎯 Overview

Stream Cart Mobile is a production‑oriented live commerce + e‑commerce super‑app built with Flutter and powered by a microservices backend. It implements Domain-Driven Design (DDD) + Clean Architecture, enabling clear separation of concerns, scalability, testability, and rapid feature evolution.

🇻🇳 Tóm tắt: Ứng dụng thương mại điện tử & livestream với kiến trúc sạch (DDD, Clean Architecture) hỗ trợ giỏ hàng, đơn hàng, voucher, chat realtime, thông báo đẩy, livestream (LiveKit), SignalR, tìm kiếm, quản lý địa chỉ, biến thể sản phẩm, cửa hàng.

🎯 Core Value

🛒 Unified Commerce: Catalog, variants, vouchers, cart, checkout, orders
🎥 Interactive Live Streaming: LiveKit + realtime chat + pinned products
💬 Real-time Chat & Notifications: SignalR + Firebase Cloud Messaging
⚡ Reactive UX: BLoC state management & granular loading states
🔐 Secure: JWT auth, secure token storage, guarded APIs
🧩 Extensible Domain Model: Modular feature packages & use cases

✅ Current Status (Aug 2025)

✅ Home / Explore (products, categories, shops, banners)
✅ Authentication & Profile (JWT, secure storage)
✅ Product Variants, Cheapest Variant Resolution
✅ Cart (add / update / bulk select / preview / clear)
✅ Checkout Preview & Order Creation Flow (price breakdown)
✅ Order Management (status tabs, detail, timeline, reviews scaffold)
✅ Live Streaming (join, active streams, products, pinned items, messages)
✅ Real-time Chat (rooms, unread count, typing indicators)
✅ Notifications (list, mark read, unread counter, SignalR + FCM + local)
✅ Address Book (CRUD, default selection)
✅ Vouchers (shop vouchers apply / list)
✅ Search (products + search history service)
✅ Theming & Responsive Layout (Material 3 + Google Fonts)
✅ Push Notifications (foreground / background handlers)
✅ Dependency Injection (GetIt) & modular use cases
🚧 Payment Gateway Integration (stubbed payment method selection)
🚧 Stream Analytics / Insights
🚧 Advanced Recommendation Engine

✨ Feature Matrix

🛍️ Commerce Core

Products & Categories (filter, search, variants, cheapest variant resolver)
Shops (listing, product count per shop)
Vouchers (list + apply at checkout preview)
Cart (add/update/remove, multi‑select, preview order, bulk deletion)
Checkout Preview (price breakdown, shipping, voucher, payment method select)
Orders (tabbed status lists, detail, status timeline, price breakdown, review scaffold)
Addresses (CRUD + default selection)

🎥 Live Streaming & Engagement

Join active live streams (LiveKit join token connect)
Products & pinned products per stream (debounced reload)
Live stream chat (separate from standard chat domain)
Viewer stats & real-time events pipeline

💬 Real-time Communication

SignalR abstraction (chat + notifications + typing indicators)
Chat Rooms (user/shop, load messages, search, unread counts)
Typing indicators, join/leave events, reconnection strategy

🔔 Notifications

FCM + local notifications (foreground / background / terminated)
SignalR real-time push (new + updated notification merging)
Pagination & filtering (type, read state), unread counter

👤 User & Auth

JWT Login / Me endpoint, secure storage, automatic token hydration
Role awareness (user / shop contexts prepared)
Profile display & avatar

🧱 Architecture & Quality

DDD Layers (Entities, Repositories, UseCases)
Clean separation (data / domain / presentation)
GetIt DI (ready for Injectable codegen)
Consistent error & loading state modeling
Modular BLoC per feature (auth, cart, chat, order items, notification, livestream, address, voucher, variants, etc.)

🔐 Security & Reliability

Secure token storage (flutter_secure_storage)
Graceful reconnection routines (SignalR, LiveKit probes)
Defensive parsing & failure surfaces (Either / Failures)

🛠 Developer Experience

Build runner ready (retrofit, json_serializable, hive, injectable)
Search history service persisted locally
Clear feature folder conventions

🚀 Backlog / Planned

Payment gateway integration (online methods)
Advanced analytics (viewer retention, conversion funnels)
Recommendation / personalization engine
In‑stream purchase overlay & scheduled pinning
Moderation tools & reporting flows
Multi-language i18n expansion

🚀 Current Development Status (August 2025)

✅ Recently Completed (Highlights)

Full cart lifecycle (bulk selection + preview + voucher application)
Order listing, detail, status timeline & price breakdown
Live streaming join/connect flow (LiveKit + join token handshake)
Real-time chat (typing, unread counts, reconnection, search)
Unified notifications (SignalR + FCM + local)
Product variants + cheapest variant / availability use cases
Shop vouchers & shop listing components
Address management & checkout integration

🔄 Active Work

Payment gateway integration layer
Stream analytics & engagement metrics

📋 Next (Planned)

Recommendation & personalization services
Advanced moderation & reporting in streams
Multi-language i18n expansion
Full test coverage ramp-up (unit + widget + integration)

🛠️ Recent Updates (Aug 2025)

🔧 Fixes

Reconnection improvements (SignalR & LiveKit lifecycle aware)
Debounced product reload in live streams (API efficiency)
Notification pagination + unread counter sync issues resolved
Variant price resolution & null safety hardening

🆕 Additions

Order domain (detail, status timeline, review scaffold)
Live stream chat + pinned products + viewer stats events
Vouchers (list + apply) & address integration in checkout preview
Bulk cart operations & selected items preview order path
Search history persistence service
Local + push notification orchestration service

🎨 UX Enhancements

Consistent skeleton shimmer loading states
Payment + status badge components
Improved empty / error / retry states across lists
Unified typography (Be Vietnam Pro via Google Fonts)

🏗️ Architecture

Stream Cart Mobile follows Clean Architecture + DDD with feature‑oriented modularity:

lib/
├── 🎯 core/                    # Config, constants, env, DI, routing, network, services
├── 📊 data/                    # Datasources (remote/local), models, repos impl
├── 🏢 domain/                  # Entities, repositories (contracts), use cases
└── 🎨 presentation/            # BLoCs, pages, widgets, themes

Additional Feature Domains Present:

cart/, order_item/, notification/, chat/, livestream/, address/, voucher/, product_variants/, shop/, search/

🧩 Key Services

SignalRService – unified hub connection & callbacks (chat, notifications)
LiveKitService – media session, room events, probing & metrics
FirebaseNotificationService – FCM + local notification orchestration
SearchHistoryService – persistent recent searches

🔄 Real-time Flow

SignalR events → Bloc events → UI state updates (chat, notifications, typing, viewer stats) LiveKit room events → LiveStreamBloc (participants, probing, pinned products sync)

🔗 API Integration Status (Live)

✅ Auth: /api/auth/login, /api/auth/me
✅ Categories: /api/categorys
✅ Products: /api/products, /api/products/search
✅ Product Variants: /api/product-variants/*
✅ Cart: /api/cart/*
✅ Orders: /api/orders/*
✅ Vouchers: /api/vouchers/*, /api/shop-vouchers/*
✅ Live Streams: /api/livestreams/* + LiveKit signaling
✅ Notifications: /api/notifications/* + SignalR hub
✅ Chat: /api/chat/* + SignalR hub
✅ Addresses: /api/addresses/*
🚧 Payments: (gateway integration pending)

🔧 Tech Stack

🎨 Framework

Flutter 3.7.2+, Dart 3.7.2+

🏛️ State Management

flutter_bloc (feature BLoCs) + equatable

🌐 Networking & Realtime

dio, retrofit, json_serializable, signalr_core, livekit_client

💾 Storage

flutter_secure_storage, shared_preferences, hive / hive_flutter

🔧 Dependency Injection

get_it (ready for injectable code generation)

🛠 Codegen & Dev

build_runner, retrofit_generator, json_serializable, hive_generator, injectable_generator

🔒 Security & Utils

crypto, flutter_dotenv, dartz, intl

🎨 UI & Navigation

Material 3, Google Fonts (Be Vietnam Pro), cached_network_image, shimmer, flutter_svg, flutter_slidable
Custom routing (AppRouter + observer)

🔔 Notifications & Messaging

firebase_core, firebase_messaging, flutter_local_notifications

📱 Screenshots

Screenshots (updated set incoming). The app currently features:

🏠 Home - Catalog + categories + banners + search
👤 Profile - Authenticated user info
🛒 Cart & Checkout Preview - Voucher + price breakdown
📦 Orders - Status tabs & detail timeline
🎥 Live Stream - Realtime video + chat + pinned products
💬 Chat - Realtime rooms & typing indicators
🔔 Notifications - Realtime + push hybrid

Run on Web: flutter run -d web

🚀 Getting Started

📋 Prerequisites

Ensure you have:

✅ Flutter SDK 3.7.2+ (includes Dart)
✅ Android Studio or VS Code with Flutter extension
✅ Git
✅ Firebase project (for push notifications) – optional for core features

🔧 Installation

Clone repository

git clone https://github.com/yourusername/stream-cart-mobile.git
cd stream-cart-mobile/stream_cart_mobile

Install dependencies
```
flutter pub get
```

(Optional) Create .env

echo "API_BASE_URL=https://brightpa.me" > .env
echo "ENVIRONMENT=development" >> .env

Run the app
```
flutter run -d web
# or
flutter run
```

Default API base points to production: https://brightpa.me.

⚙️ Environment (Optional)

API_BASE_URL=https://brightpa.me
API_TIMEOUT=30000
ENVIRONMENT=development
ENABLE_DEBUG_LOGGING=true

Core API (subset):

Auth: /api/auth/login, /api/auth/me
Catalog: /api/products, /api/products/search, /api/categorys
Cart: /api/cart/* | Orders: /api/orders/* | Vouchers: /api/vouchers/*
Live Streams, Chat & Notifications: REST + SignalR hubs + LiveKit server

Auth Flow: Provide valid backend credentials (no demo account bundled).

🔨 Development

Run

flutter run -d web
flutter run            # auto device detection
flutter run -d android # specify platform

Debug Options

flutter run --dart-define=ENVIRONMENT=development

Code Generation

Run when adding retrofit APIs / json models / hive adapters / injectable config:

flutter pub run build_runner build --delete-conflicting-outputs
flutter pub run build_runner watch

Code Quality

flutter format .
flutter analyze
dart fix --apply

🧪 Testing

Run Tests

flutter test
flutter test --coverage

Structure (Planned Expansion)

test/
├── unit/          # Domain, use cases, blocs
├── widget/        # Widget tests (goldens planned)
└── integration/   # End-to-end flows

Current: Core flows manually tested; automated coverage ramp-up in progress.

📦 Build & Deploy

Android

flutter build apk --release
flutter build appbundle --release
flutter build apk --release --obfuscate --split-debug-info=build/debug-info/

iOS (macOS only)

flutter build ios --release
flutter build ipa --release

Web

flutter build web --release

Desktop (Dev)

flutter run -d windows

Deployment (High Level)

Android: Sign, upload AAB to Play Console
iOS: Archive in Xcode, distribute via App Store Connect
Web: Host /build/web on static hosting / CDN

🤝 Contributing

Fork repository
Create feature branch:
```
git checkout -b feature/amazing-feature
```
Implement & test

Ensure quality:

flutter analyze
flutter test
flutter format .

Commit & push:

git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

Open Pull Request

Standards

Effective Dart style
Tests for new logic (where reasonable)
Clear commit messages (conventional preferred)

📞 Support & Contact

📧 Email: bolicious123@gmail.com
💬 Issues: GitHub Issues
📖 Wiki: Project documentation (work in progress)
🌐 Demo: flutter run -d web

🎯 Project Status

Stage: Active Development (Core Feature‑Complete)
API: Production microservices connected
Real-time Stack: SignalR + LiveKit + FCM operational
Platforms: ✅ Web ✅ Android ✅ iOS ✅ Windows (dev)
Last Updated: Aug 2025

📄 License

Licensed under the MIT License – see LICENSE.

Made with ❤️ using Flutter

🔥 Core Features Production‑Ready

⭐ Star this repo if it helps you!

Quick Start: git clone → cd stream_cart_mobile → flutter pub get → flutter run -d web

Name		Name	Last commit message	Last commit date
stream_cart_mobile		stream_cart_mobile
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation