🎯 Grosense - AI-Powered Shopkeeper Management System

🚀 Quick Start (Ready to Use!)

Your complete FastAPI + Expo React Native system is ready! Follow these 3 simple steps:

Step 1️⃣: Configure Backend URL

1. Find your computer's IP address:

   ipconfig  # Windows

   Look for IPv4 Address (e.g., 192.168.1.100)

2. Update Expo/grosence/api/config.js:

   const API_BASE = "http://192.168.1.100:8000";  // Use YOUR IP

Step 2️⃣: Start Backend

cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

✅ Backend running at: http://localhost:8000 📚 API Docs at: http://localhost:8000/docs

Step 3️⃣: Start Frontend

cd Expo/grosence
npx expo start

Then:

• Press a for Android
• Press i for iOS
• Scan QR code with Expo Go app

---

✨ What You Have

Backend (FastAPI)

✅ Complete REST API with:

• JWT authentication (login/signup)
• Products CRUD with auto-generated barcodes
• Sales transactions with automatic stock updates
• Push notifications support
• AI-ready database schema
• Full API documentation at /docs

Frontend (Expo React Native)

✅ Beautiful Mobile App with:

• 🏠 Dashboard - Real-time stats, alerts, quick actions
• 📦 Products - Add/edit/delete products, search, barcode system
• 💰 Sales - Shopping cart, multi-item transactions, stock validation
• 🎨 Modern UI - Styled with NativeWind (Tailwind CSS)
• 🔐 Secure Auth - JWT token management, auto-login

---

📱 Complete Features

Authentication

• User registration with shop name
• Secure login with JWT tokens
• Auto-login on app restart
• Password validation
• Email validation

Dashboard

• Total products count
• Low stock alerts
• Today's sales count
• Today's revenue
• Quick action buttons
• Pull to refresh

Product Management

• Add products with details
• Auto-generate unique barcodes (UUID)
• Edit product information
• Delete products
• Search products by name/category
• View stock levels
• Low stock indicators
• Category management

Sales System

• Create multi-item sales
• Barcode-based product lookup
• Shopping cart functionality
• Quantity & discount support
• Payment method selection (Cash/Card/UPI)
• Automatic stock deduction
• Stock validation before sale
• Transaction history
• Revenue tracking

---

🏗️ Architecture

┌─────────────────────────────────────────┐
│    Expo React Native Frontend          │
│  (iOS, Android, Web)                    │
│  - NativeWind (Tailwind CSS)            │
│  - Expo Router Navigation               │
│  - JWT Authentication                   │
└──────────────┬──────────────────────────┘
               │ REST API
               │ (axios + JWT tokens)
               ▼
┌─────────────────────────────────────────┐
│       FastAPI Backend                   │
│  - SQLAlchemy ORM                       │
│  - SQLite Database                      │
│  - JWT Security                         │
│  - Auto Stock Updates                   │
└─────────────────────────────────────────┘

---

📂 File Structure

grosence/
├── 📖 COMPLETE_SETUP_GUIDE.md       ← Start here!
├── 🧪 test_integration.bat/sh       ← Test scripts
│
├── backend/                          ← FastAPI Backend
│   ├── app/
│   │   ├── main.py                  ← FastAPI app
│   │   ├── models.py                ← 9 database models
│   │   ├── schemas.py               ← Pydantic schemas
│   │   ├── deps.py                  ← Auth dependencies
│   │   ├── routers/
│   │   │   ├── auth.py              ← Login/Register
│   │   │   ├── product.py           ← Products CRUD
│   │   │   ├── sales.py             ← Sales transactions
│   │   │   └── notifications.py     ← Push notifications
│   │   ├── core/
│   │   │   ├── config.py            ← Environment config
│   │   │   └── db.py                ← Database setup
│   │   ├── utils/
│   │   │   ├── security.py          ← JWT & password hashing
│   │   │   ├── barcode.py           ← Barcode generation
│   │   │   └── notifications.py     ← Expo push
│   │   └── services/
│   │       └── ai_stub.py           ← AI hooks (future)
│   ├── .env                         ← Configuration
│   ├── requirements.txt             ← Python packages
│   └── grosense.db                  ← SQLite database
│
└── Expo/grosence/                   ← React Native Frontend
    ├── app/
    │   ├── _layout.jsx              ← Root + AuthProvider
    │   ├── index.jsx                ← Auto-navigation
    │   ├── onboarding.jsx           ← Welcome screen
    │   ├── (auth)/
    │   │   ├── login.jsx            ← Login screen
    │   │   └── signup.jsx           ← Registration
    │   └── (tabs)/
    │       ├── _layout.jsx          ← Bottom tabs
    │       ├── home.jsx             ← Dashboard
    │       ├── products.jsx         ← Product management
    │       └── sales.jsx            ← Sales system
    ├── api/
    │   ├── config.js                ← ⚠️ UPDATE THIS!
    │   ├── api.js                   ← Axios client
    │   ├── auth.js                  ← Auth APIs
    │   └── products.js              ← Product/Sales APIs
    ├── components/
    │   ├── UI.jsx                   ← Reusable components
    │   └── ProductCard.jsx          ← Cards
    ├── contexts/
    │   └── AuthContext.jsx          ← Global auth state
    ├── hooks/
    │   ├── useProducts.js           ← Products hook
    │   └── useSales.js              ← Sales hook
    └── package.json                 ← Dependencies

---

🔧 Testing Integration

Option 1: Quick Test (Windows)

test_integration.bat

Option 2: Manual Test

1. Test Backend:

   curl http://localhost:8000/health
   # Should return: {"status":"ok"}

2. Test API Docs: Open: http://localhost:8000/docs

3. Test Registration:

   • Open app → Sign Up
   • Fill in details
   • Should redirect to Dashboard

4. Test Products:

   • Add a product
   • View in Products tab
   • Edit/Delete product

5. Test Sales:

   • Create new sale
   • Enter product barcode
   • Complete transaction
   • Check stock decreased

---

🎨 UI Preview

Color Scheme

• Primary: Blue #3B82F6
• Success: Green #10B981
• Warning: Red #EF4444
• Info: Yellow #F59E0B

Screens

1. Onboarding → Feature showcase
2. Login/Signup → Authentication
3. Dashboard → Stats & quick actions
4. Products → Grid view with search
5. Sales → Cart-based system

---

🔐 Security Features

✅ Password hashing with bcrypt ✅ JWT token authentication ✅ Secure token storage (AsyncStorage) ✅ Request/response interceptors ✅ Auto-logout on 401 ✅ Input validation (frontend + backend) ✅ SQL injection protection (SQLAlchemy ORM)

---

📊 Database Schema

9 Complete Models:

1. Shopkeeper - User accounts
2. Supplier - Product suppliers
3. Product - Inventory items
4. SalesTransaction - Sale headers
5. SalesRecord - Sale line items
6. StockEvent - Inventory audit log
7. AIPrediction - ML predictions (future)
8. AIInsight - AI recommendations (future)
9. ExpoPushToken - Push notifications

---

🚀 Deployment (Production)

Backend

1. Switch to PostgreSQL
2. Deploy to: Railway, Heroku, DigitalOcean
3. Use environment variables
4. Enable HTTPS

Frontend

1. Build with: eas build
2. Submit to App Store / Play Store
3. Update API_BASE to production URL

---

🐛 Troubleshooting

"Cannot connect to backend"

• ✓ Backend running on 0.0.0.0:8000
• ✓ Updated api/config.js with correct IP
• ✓ Same WiFi network
• ✓ Firewall allows port 8000

"Login failed"

• ✓ Check backend terminal for errors
• ✓ Register account first
• ✓ Check email/password

"Products not loading"

• ✓ Token is valid (try re-login)
• ✓ Check backend /products/ endpoint
• ✓ Check React Native Debugger

---

📚 Documentation

• Setup Guide: COMPLETE_SETUP_GUIDE.md
• Backend Details: backend/IMPLEMENTATION_SUMMARY.md
• Frontend Details: Expo/grosence/FRONTEND_GUIDE.md
• API Docs: http://localhost:8000/docs

---

🎯 Next Steps (Optional Enhancements)

• Camera barcode scanner (expo-barcode-scanner)
• Push notifications integration
• Offline mode with local database
• Sales charts & analytics
• Export reports (PDF/CSV)
• Dark mode
• Multi-language support
• AI predictions implementation

---

💡 Tips

1. Development: Use http://YOUR_IP:8000 (not localhost)
2. Testing: Use Expo Go app on real device
3. Debugging: Enable Remote JS Debugging in Expo
4. Backend Logs: Watch terminal for API errors
5. Frontend Logs: Check React Native Debugger console

---

✅ Checklist

Before you start:

• Python 3.8+ installed
• Node.js 14+ installed
• Expo Go app on your phone
• Both devices on same WiFi
• Port 8000 not in use

Setup:

• Updated api/config.js with your IP
• Started backend server
• Started Expo app
• Scanned QR code

Testing:

• Registered new account
• Logged in successfully
• Added a product
• Created a sale
• Verified stock updated

---

🎉 You're All Set!

Your Grosense AI-Powered Shopkeeper Management System is ready to use!

Need help? Check the detailed guides or open an issue.

Happy selling! 🚀

---

Built with ❤️ by Likhith M N FastAPI + Expo + SQLAlchemy + NativeWind + JWT