NovaCommerce

A Flutter + Firebase commerce app showcasing end‑to‑end shopping flows with a clean, scalable architecture: product discovery, variants, cart, checkout, orders, authentication, and an optional AI assistant layer.

Scope: Payments and logistics integrations are intentionally out of scope.

---

Contents

• Features
• Screenshots
• Tech Stack
• Project Structure
• Getting Started
• Firebase Setup
• Emulators
• Demo Mode
• License

---

Features

Core commerce

• Product catalog with pagination and featured products
• Product variants (size/color) with stock validation
• Cart with quantity management and persistence
• Wishlist with local + remote sync
• Checkout with transactional stock decrement
• Orders list + order details

Authentication

• Email/password sign-in
• Google sign-in
• Anonymous (guest) sessions with upgrade to authenticated accounts

Backend & data

• Firestore for products, orders, and user data
• Firestore transactions for atomic checkout and stock updates
• Offline persistence enabled for Firestore
• Emulator support for local development

UX & performance

• Responsive layout (flutter_screenutil)
• Cached images (cached_network_image)
• Skeleton loaders for perceived performance
• Consistent, user-friendly error handling

AI assistant (optional)

• “Nova AI” chat assistant for product-related queries
• Repository is modular (supports real or fake implementations)

---

Screenshots

---

Tech Stack

• Flutter / Dart
• Material 3
• Riverpod
• GoRouter
• Firebase Auth + Firestore
• cached_network_image
• flutter_screenutil

---

Project Structure

High-level layout:

lib/
  main.dart
  app.dart
  core/          # routing, theme, shared widgets, config, error mapping
  domain/        # entities + repository interfaces
  data/          # repository implementations + datasources
  features/      # home, product, cart, checkout, wishlist, orders, auth, ai_assistant, profile

---

Getting Started

Prerequisites

• Flutter SDK (3.x)
• Dart SDK (3.x)

Install dependencies:

flutter pub get

Run quality checks:

dart format .
flutter analyze
flutter test

Run the app:

flutter run

---

Firebase Setup

This app uses client-side Firebase configuration (no server-side secrets are included in this repository).

Option A — Use your own Firebase project (recommended)

1. Create a Firebase project.
2. Enable Authentication providers (Anonymous / Email-Password / Google).
3. Create Firestore collections:
   • products
   • orders
4. From the repo root, run:

flutterfire configure

This generates:

• android/app/google-services.json
• ios/Runner/GoogleService-Info.plist
• lib/firebase_options.dart

Tip: If your product query orders by createdAt, make sure product docs contain createdAt and any flags you filter on (e.g. featured: true).

---

Emulators (optional)

Start emulators:

firebase emulators:start --only firestore,auth

Run app using emulators (examples):

iOS Simulator

flutter run \
  --dart-define=USE_FIRESTORE_EMULATOR=true \
  --dart-define=FIRESTORE_HOST=localhost \
  --dart-define=FIRESTORE_PORT=8080 \
  --dart-define=AUTH_PORT=9099

Android Emulator

flutter run \
  --dart-define=USE_FIRESTORE_EMULATOR=true \
  --dart-define=FIRESTORE_HOST=10.0.2.2 \
  --dart-define=FIRESTORE_PORT=8080 \
  --dart-define=AUTH_PORT=9099

Notes:

• On Android Emulator, 10.0.2.2 routes to your host machine.
• On a physical device, use your machine’s LAN IP (e.g., 192.168.x.x).

---

Demo Mode

Run with in-memory repositories (no Firebase required):

flutter run --dart-define=USE_FAKE_REPOS=true

---

License

This repository is provided for review and evaluation purposes only. It is not open-source and may not be reused, redistributed, or deployed without explicit written permission.

See LICENSE.