Kopitiam Digital Waiter - Real-Time Sales Tracker for Kopitiam Owners

📋 Project Overview & Problem Statement

Challenge: Small Malaysian Kopitiam operators typically track daily sales manually using pen and paper or basic spreadsheets. This approach is error-prone, time-consuming, and provides no real-time insight into which items are selling, when peak hours occur, or how revenue trends over time.

Solution: Kopitiam Digital Waiter is a lightweight, mobile-friendly web application that lets Kopitiam owners record sales in seconds, monitor item performance, and view daily analytics — all from any browser, with no complex setup required.

Key Benefits

Instant Sales Recording: Tap to record sales with a +/- quantity selector — no typing required
Live Dashboard: See today's revenue, items sold, and transaction count update in real time
Item Performance Ranking: Know which dishes and drinks are your best sellers at a glance
Analytics: Visualize peak selling hours and daily revenue trends over the past 7 days
Smart Tips: AI-generated contextual tips remind owners to prepare for rush hours
Milestone Alerts: Get notified when a menu item crosses a sales milestone today

🖥️ Application Features

📊 Dashboard

At-a-glance view of today's total revenue (RM), items sold, and transactions. Includes milestone alerts and an AI-powered quick tip based on current sales activity.

📋 Sales Logbook

Interactive menu grid with +/- quantity controls. Tap the green button to record a sale. Shows live top-selling items and today's running sales total in the header bar.

📈 Item Performance

Horizontal progress bar chart ranking all menu items by total quantity sold. Top 3 items highlighted in emerald; remaining in grey. Shows "X sold" for each item.

📉 Sales Analytics

Two charts: an Area Chart showing busy hours (total order volume by hour) and a Bar Chart showing daily revenue trends for the last 7 days. Powered by Recharts.

Full Menu (23 Items)

🤖 AI Integration & Intelligence

💡 AI Quick Tips (Gemini AI)

Powered by Google Gemini AI, the dashboard generates context-aware tips for the owner. If sales are live today, it references the top-selling item. Otherwise it uses historical best-seller data to suggest preparation priorities.

🔔 Milestone Alerts

The server automatically detects when a menu item crosses significant sales milestones during the day (e.g. 10+ orders) and surfaces a congratulatory alert on the dashboard.

📊 Data-Seeded Insights

The app seeds from a real Kopitiam dataset (CSV) on first launch, giving owners instant analytics from day one without needing to enter historical data manually.

⏱️ Peak Hours Detection

The analytics engine automatically groups all historical sales by hour using SQLite queries, surfacing which hours of the day see the highest order volumes — no manual analysis needed.

🛠️ Technical Architecture & Implementation

Frontend Stack

React 19 TypeScript 5.8 Vite 6 Tailwind CSS 4 Recharts Framer Motion Lucide React Icons

Backend Stack

Node.js Express.js TypeScript (tsx) better-sqlite3 csv-parse Google Gemini AI

Deployment & Infrastructure

Google Cloud Run Docker Vite Build (SPA) Express Static Serving

System Architecture

Single-Server Architecture: Express serves both the REST API and the compiled React SPA from the same process
SQLite Database: Lightweight embedded database storing all sales records with datetime, item, quantity, and totals
CSV Seeding: On first run, the server reads Kopitiam_dataset.csv and populates the database with historical sales data
REST API: Four endpoints — /api/menu, /api/sales (POST), /api/stats/today, /api/stats/performance, /api/stats/analytics
Vite Dev Mode: In development, Express uses Vite middleware for hot module replacement (HMR)

📖 Development Setup & Installation Guide

Prerequisites

Node.js 18+ with npm
Gemini API Key from Google AI Studio

Quick Start Installation

# Clone the repository
git clone https://github.com/lyven81/ai-project.git
cd ai-project/projects/kopitiam-digital-waiter

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Add your GEMINI_API_KEY to .env.local

# Run the app in development mode
npm run dev
            

Environment Configuration

# Required API Configuration
GEMINI_API_KEY=your_gemini_api_key_here
            

Available Scripts

npm run dev — Start development server with Vite HMR
npm run build — Build the React SPA to dist/
npm run start — Run production server (requires built dist)
npm run lint — TypeScript type checking

🚀 Deployment on Google Cloud Run

# Build and deploy to Cloud Run
gcloud run deploy kopitiam-digital-waiter \
  --source . \
  --platform managed \
  --region us-west1 \
  --set-env-vars GEMINI_API_KEY=your_api_key
            

Production Notes

In production mode, Express serves the compiled dist/ folder and handles all API routes
SQLite database is ephemeral on Cloud Run — for persistent storage, consider mounting a volume or using Cloud SQL
The app is fully containerizable via Docker for any cloud provider

📊 Key Metrics

23

Menu Items Pre-Loaded

4

Dashboard Tabs

5

REST API Endpoints

Real-Time

Dashboard Updates

Business Value

Operational Efficiency: Replaces pen-and-paper logbooks with a tap-to-record digital system
Inventory Planning: Item performance data helps owners anticipate ingredient needs before peak hours
Revenue Visibility: Real-time revenue tracking provides instant financial awareness throughout the day
Data-Driven Decisions: Busy hour analytics help optimize staffing and ingredient preparation schedules
Zero Learning Curve: Designed for non-technical Kopitiam owners with a simple, icon-based interface

☕ Kopitiam Digital Waiter