ShopSathi (শপসাথী) 🛒🇧🇩

Grocery Price Intelligence, Historical Transparency & AI Forecasting Engine for Bangladesh
"Discounts are loud. History is honest."

---

📖 Overview

ShopSathi is an offline-first, high-performance grocery price intelligence and market transparency mobile application built for Bangladeshi shoppers. By tracking, indexing, and normalizing SKU data across 8 major supermarket chains in Dhaka and nationwide, ShopSathi exposes genuine price histories, unmasks deceptive discount claims, forecasts market trends, and delivers instant per-unit price comparisons across competing grocery retailers.

Powered by an embedded vectorized DuckDB analytics engine operating directly on compressed .parquet files, ShopSathi performs complex multi-variable aggregation, time-series forecasting, and cross-store candidate matching over 110,000+ products and 15.7M price points in under 50ms—completely on-device without requiring continuous cloud connectivity.

---

📸 Visual Showcase & Feature Walkthrough

1. Launch, Editorial Masthead & Supermarket Catalog

🚀 Offline Parquet Engine Bootstrap	🏠 Editorial Home & Market Summary	🏬 Supermarket Catalog Hub
Embedded DuckDB Parquet initialization with sub-second bootstrap	Editorial hero masthead, live store counters, and daily staple trends	All-Time Low (ATL) records and 8 supermarket catalog entry points

---

2. Search, Smart Categorization & Taxonomy Tree

🔍 Deep Search & Unit Normalization	🗂️ Browse Categories Catalog	🌳 Multi-Select Taxonomy Hierarchy
Instant search by keyword, store, unit (kg/L/pc), and price trends	Dual-mode catalog (Taxonomy vs By Store) with per-unit price ledger	Expandable taxonomy tree with multi-select checkboxes & live counts

---

3. Market Intelligence, GenAI Forecasting & Navigation

🤖 Ask Sathi AI (Market Forecasting)	📊 Market Pulse & Commodity Basket	☰ Navigation Drawer & Customization
7D/30D price forecasting, supply chain factors & interactive item cards	Commodity Basket Price Index area chart & store price share ranking	Quick access drawer with macro pulse, store catalog links & theme dots

---

4. Superstore View & Engine Settings

🏪 Supermarket Store Catalog	⚙️ Settings, Sync & Typography
Shwapno store view with brand filters, sort controls, and ATL tag	Daily sync manager, custom AI API keys, typeface & font scaling

---

✨ Core Features & Technical Highlights

1. 🤖 Multi-Model GenAI Cascade & Price Forecasting

• Multi-Tier Cascade Architecture: Tries active AI endpoints sequentially (gemini-flash-lite-latest → gemini-2.5-flash → groq → openrouter → custom openai-compatible) with zero user disruption.
• Statistical Fallback Engine: If no API key is configured or offline, falls back to a deterministic multi-factor statistical model combining velocity, historical variance, and seasonal volatility.
• Actionable Structured Insights: Produces clean, bulleted market summaries:
  • 📊 Market Snapshot: Current price dispersion across retailers and cheapest supermarket.
  • 🔮 7-Day & 30-Day Forecast: Directional predictions (Rising/Stable/Falling) with target price brackets.
  • 🚚 Key Supply Chain Factors: Transportation, seasonal harvest yields, and import tariffs.
  • 🛒 Shopper Strategy: Immediate buy recommendations vs wait strategies.
• Interactive Referenced Item Cards: Chat responses automatically parse and render tappable product cards with live store logos, current prices, normalized rates, and direct product detail navigation.

2. ⚡ Embedded Vectorized DuckDB Analytics Engine

• In-Process Columnar OLAP: Directly executes vectorized SQL against compressed .parquet datasets stored locally on the device.
• Ultra-Fast Sub-50ms Execution: Full-text searching, store-level filtering, percentile calculation, and cross-store aggregation across 110k+ items without server roundtrips.
• Incremental & Automated Daily Sync: Background delta synchronization keeps catalog records up to date automatically.

3. 🏬 8-Chain Supermarket Coverage & Normalization

• Full Coverage of Major Supermarkets:
  • 🔴 Shwapno (স্বপ্ন)
  • 🟡 Chaldal (চালডাল)
  • 🟢 Meena Bazar (মীনা বাজার)
  • 🟣 Othoba (অথবা)
  • 🔵 Metromart (মেট্রোমার্ট)
  • 🟢 Unimart (ইউনিমার্ট)
  • 🩵 ShotejBazar (সতেজবাজার)
  • 🩷 Foodi (ফুডি)
• Per-Unit Rate Normalization: Standardizes diverse packaging into comparable units (৳/kg, ৳/L, ৳/piece), exposing true value across dissimilar product pack sizes.

4. 🔥 Strict Mathematical All-Time Low (ATL) Detection

• Zero Fake Drop Protection: Strictly rejects 0% flat-line "promotions".
• Rigorous Multi-Point Thresholds:
  • Requires $\ge 2$ distinct recorded price changes.
  • Peak historical price must be at least $5%$ higher than minimum.
  • Absolute drop must be $\ge ৳1.00$.
  • Current price must reside within $0.1%$ of the all-time recorded lowest price.

5. 📈 Continuous Bézier Timeline Charts

• Historical Anchor: Charts normalize and render price histories anchored back to February 2026 with uniform monthly checkpoints.
• Interactive Scrub Cursor: Custom canvas painters provide scrub tooltips, ATH/ATL highlight rings, and high/low bounding bounds.
• Data Parity: Product card sparklines and full-screen detail charts share 100% identical data models and trajectories.

6. 🎨 Responsive Editorial Design & Typography

• Overflow-Proof Responsive Layouts: Clean flex-box distribution engineered to render flawlessly across all standard smartphone screen sizes and font scales.
• Theme Palette: Pure White (Paper), Noir (OLED Dark), Terminal Green, Sepia, Royal Indigo, and Rose Sunset.
• Typography & Font Scaling: Seamless switching between Plus Jakarta Sans, Inter, Outfit, JetBrains Mono, and Space Mono with customizable DPI font scaling.

---

🏗️ Architecture & Codebase Map

ShopSathi/
├── app/
│   ├── lib/
│   │   ├── core/           # Design tokens, formatters, CustomPainters, receipt widgets
│   │   │   ├── format.dart     # Currency formatting (৳), date parsers, string normalization
│   │   │   ├── palette.dart    # Theme tokens (Paper, Ink, Accent, Good, Bad, Line)
│   │   │   ├── gge1.dart       # Encryption utilities (AES-256-GCM / PBKDF2)
│   │   │   └── widgets.dart    # StoreLogo, Sparkline, Card, Tag, PaginationBar
│   │   ├── data/           # Data layer, models, DuckDB repository & AI Service
│   │   │   ├── ai_service.dart # Multi-model GenAI cascade & statistical forecast engine
│   │   │   ├── catalog.dart    # Supermarket definitions & category emoji mappings
│   │   │   ├── downloader.dart # Mirror downloader & integrity verifier
│   │   │   ├── models.dart     # Product, PricePoint, CategorySummary, Forecast models
│   │   │   └── repo.dart       # Vectorized DuckDB Parquet repository queries
│   │   ├── state/          # Riverpod state management & persistent providers
│   │   │   └── app_state.dart  # Navigation, comparison basket, AI config, sync state
│   │   └── ui/             # Screen presentations & layouts
│   │       ├── shell.dart      # Root navigation bar, drawer & global modal handlers
│   │       ├── screens/
│   │       │   ├── home.dart       # Editorial masthead, hero banner, ATL shelf, drops feed
│   │       │   ├── categories.dart # Taxonomy catalog, store filters & category tree drawer
│   │       │   ├── search.dart     # Deep search with multi-param filter chips & grid
│   │       │   ├── product.dart    # Detailed price chart, AI forecast card, competitor table
│   │       │   ├── store.dart      # Supermarket store catalog view & brand filters
│   │       │   ├── compare.dart    # Multi-product comparison graph & difference matrix
│   │       │   ├── chat.dart       # Ask Sathi AI chat interface with interactive item cards
│   │       │   ├── dashboard.dart  # Market Pulse, basket price index & store share rankings
│   │       │   ├── explore_feed.dart # Dedicated full-screen feed for drops and ATL records
│   │       │   ├── settings.dart   # Daily sync, AI API key manager, themes & typography
│   │       │   └── splash.dart     # Launch splash screen & offline engine bootstrap
│   │   └── main.dart       # App entrypoint, Riverpod ProviderScope & theme setup
│   └── test/               # Unit, repository, and widget test suite

Technology Matrix

Component	Technology	Role / Implementation
Framework	Flutter 3.24+ / Dart 3.5+	Native cross-platform performance
Database Engine	Embedded DuckDB	In-process columnar OLAP querying on local Parquet files
AI Intelligence	Google Gemini / Groq / OpenAI	Dynamic multi-model cascade with statistical fallback
State Management	Flutter Riverpod 2.6+	Compile-safe reactive state & dependency injection
Cryptography	PointyCastle / Crypto	AES-256-GCM authenticated encryption for archives
Typography	Google Fonts	Editorial Serif & Plus Jakarta Sans / JetBrains Mono
Image Caching	CachedNetworkImage	In-memory & on-disk disk LRU caching with shimmer

---

🚀 Getting Started

Prerequisites

• Flutter SDK (>= 3.24.0)
• Android Studio or VS Code with Flutter extensions
• Android device or emulator running API 24+

Installation & Run

1. Clone the repository:

   git clone https://github.com/ranehal/ShopSathi-flutter.git
   cd ShopSathi-flutter/app

2. Fetch dependencies:

   flutter pub get

3. Run on connected device or desktop:

   # Run on connected Android phone / emulator
   flutter run
   
   # Or run on Windows Desktop
   flutter run -d windows

4. Execute Static Analysis & Tests:

   flutter analyze
   flutter test

Building Release APK

flutter build apk --release

The optimized release APK will be located at: build/app/outputs/flutter-apk/app-release.apk

---

🔒 Security & Local Privacy

• 100% On-Device Queries: Search queries, comparison lists, and bookmarks never leave your phone.
• Client-Side Encrypted Archives: Full historical price archives use AES-256-GCM encryption with PBKDF2 key derivation.
• Bring-Your-Own-Key (BYOK) AI: Users can optionally supply their own API keys stored safely inside local SharedPreferences without intermediary proxy servers.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

_{Crafted with ❤️ by Ragib Ahnaf Nehal for Bangladeshi grocery shoppers.
ভালোবাসা অবিরাম — NEHAL 💖}