📊 Ecommerce Analyst

Private analyst for mid-size Malaysian e-commerce sellers

Python / Pandas Chart.js Vanilla JS Gemini 2.5 (live v1.5) GitHub Pages

📋 Project Overview & Problem Statement

Challenge: Mid-size Malaysian e-commerce sellers (solo or 2–5 person teams, RM30K–RM300K/month GMV) are the busiest people in their business — packing, customer service, ads, fulfillment, all at once. Freelance e-commerce consultants cost RM3K–10K/project, raise confidentiality concerns (often serving competitors), and speak in jargon. Platform-native dashboards show revenue but not net margin after discounts, returns, and shipping. The seller watches sales grow while profit silently erodes.

Solution: Ecommerce Analyst is a private analyst-in-a-box that lives inside the seller's own instance. It answers plain-language questions about their transaction data and delivers a proactive Monday morning brief — without sharing data with any human consultant, at a cost below any part-time hire.

Key Benefits

🖥️ Application Features

💬 Ask Anything

Free-form chat grounded in the seller's transaction CSV. Questions like "what's eating my margin?", "is my 15% Raya discount profitable?", "which state is losing me money?" — answered in plain language with specific numbers.

📅 Monday Morning Brief

Auto-generated every Monday 7am: 3 wins, 3 worries, and 1 decision to make this week. The seller reads it over coffee; clickable findings open the chat to drill deeper.

⚡ 6 Common Questions, One Click

Preset buttons for the most common seller questions: profit by category, state shipping economics, returns by SKU, discount ROI, top customer cohort, delivery performance. Zero typing needed.

📤 CSV Upload with Smart Remap

Drop the seller's platform transaction export. App auto-detects columns, remaps regions to Malaysian states, drops platform-only columns the seller has no visibility into.

📂 Answer History & Export

Every Q&A and Monday brief is saved and searchable. Export as PDF to share with accountants, partners, or family members running the business.

📱 Mobile-First Layout

Two-panel design optimized for the seller's phone. Works between packing runs at 11pm without a desktop, without a data analyst, without a consultant.

Analysis Coverage (Categories)

Electronics
Fashion
Home
Grocery
Sports
Beauty
Toys

🤖 AI Integration & Intelligence

🧠 Grounded Q&A (Gemini 2.5 Flash)

The live version uses Gemini 2.5 Flash to convert plain-language seller questions into pandas queries against the CSV, then translates the numeric result back into a one-paragraph answer in Malay-flavored English.

📝 Weekly Brief Synthesis

Every Monday 7am, the scheduler pulls the last 7 days of data and the LLM writes a scannable brief — 3 wins, 3 worries, 1 decision. Each finding is grounded in a specific number from the data.

🔒 Privacy-First Prompting

The system prompt enforces confidentiality: no platform names mentioned, no data leaves the seller's instance, no cross-client pattern references. The analyst serves only the seller it's deployed for.

📊 Static Pre-Computed Demo

This portfolio demo pre-computes 6 quick-action answers + one Monday brief + 5 example asks from the full 34,500-row dataset. No live LLM call needed — demonstrates the output shape without any API cost.

🛠️ Technical Architecture & Implementation

Frontend Stack

Vanilla HTML Chart.js 4 Poppins Font Inline CSS Responsive Mobile-First

Backend Stack (Live v1.5)

FastAPI Python 3.11 Pandas SQLite Gemini 2.5 Flash Claude Haiku 4.5 (fallback)

Deployment & Infrastructure

GitHub Pages (static demo) Google Cloud Run (live v1.5) Cloud Run Cron (weekly brief) Docker

System Architecture

📖 Development Setup & Installation Guide

Prerequisites

Quick Start (Static Demo)

# Clone the repository git clone https://github.com/lyven81/ai-project.git cd ai-project/projects/ecommerce-analyst # Prep the data (localize regions, drop platform columns, regenerate delivery times) python data_prep.py # Pre-compute all demo answers python precompute_answers.py # Open the self-contained demo open demo.html

Environment Configuration (Live Version)

# Required API Configuration GEMINI_API_KEY=your_gemini_api_key_here ANTHROPIC_API_KEY=your_anthropic_api_key_here # optional fallback

Available Scripts

🚀 Deployment on Google Cloud Run (Live v1.5)

# Build and deploy to Cloud Run gcloud run deploy ecommerce-analyst \ --source . \ --platform managed \ --region asia-southeast1 \ --set-env-vars GEMINI_API_KEY=your_api_key

Production Notes

📊 Key Metrics

34,500
Transactions Analyzed
16
Malaysian States Covered
7
Product Categories
6
One-Click Analyses

Business Value