🏪 Convenience Store - Multi-User Management System

A secure, multi-tenant web application for convenience store management with Firebase backend, featuring invoice generation, customer management, product tracking, and comprehensive security controls.

---

🔐 SECURITY FIRST

This application has been hardened against data breaches, unauthorized access, and credential leaks. See:

• 📋 ZERO_DATA_BREACH_CHECKLIST.md - Complete security verification
• 🔒 SECURITY_AUDIT_REPORT.md - Detailed audit findings
• 🛡️ web/SECURITY.md - Security implementation guide

---

✨ Features

🧾 Invoice Management

• Professional invoice generation with store branding
• Automatic profit/margin calculations
• Invoice printing with QR codes
• Payment tracking (paid/pending/overdue)
• Invoice history and search

👥 Customer Management

• Customer profiles with contact details
• Purchase history tracking
• Credit balance management
• Customer activity highlights
• Search and filtering

📦 Product Management

• Product catalog with pricing
• Stock level tracking
• Category organization
• Tax rate management per category
• Low stock alerts

📊 Dashboard Analytics

• Real-time sales metrics
• Revenue and profit tracking
• Top customers and products
• Pending invoice count
• Recent activity feed

🔒 Security & Authentication

• Email/password authentication
• Email verification required
• User-specific data isolation
• Input sanitization (XSS/SQL injection protection)
• Rate limiting
• Secure Firestore rules

---

🚀 Quick Start

Prerequisites

• Node.js 16+ and npm
• Firebase account (console.firebase.google.com)
• Git

1. Clone Repository

git clone <your-repo-url>
cd convinence_store/web

2. Install Dependencies

npm install

3. Configure Firebase

A. Create Firebase Project

1. Go to Firebase Console
2. Create new project (or use existing)
3. Enable Authentication → Email/Password
4. Enable Firestore Database
5. Get your Firebase config:
   • Project Settings → General → Your apps → SDK setup

B. Set Environment Variables

# Copy example env file
cp .env.example .env.local

# Edit .env.local with your Firebase credentials
nano .env.local

Add your Firebase credentials:

REACT_APP_FIREBASE_API_KEY=your_api_key_here
REACT_APP_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
REACT_APP_FIREBASE_PROJECT_ID=your-project-id
REACT_APP_FIREBASE_STORAGE_BUCKET=your-project.storage.app
REACT_APP_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
REACT_APP_FIREBASE_APP_ID=1:your_app_id:web:your_app_id
REACT_APP_FIREBASE_MEASUREMENT_ID=G-YOUR_MEASUREMENT_ID

⚠️ NEVER commit .env.local to version control! (Already blocked by .gitignore)

C. Deploy Firestore Security Rules

# Install Firebase CLI
npm install -g firebase-tools

# Login to Firebase
firebase login

# Initialize Firebase (if not already)
firebase init firestore

# Deploy security rules
firebase deploy --only firestore:rules

4. Run Development Server

npm start

App will open at http://localhost:3000

5. Create Your First Account

1. Click "Sign Up"
2. Enter email and password
3. Verify email (check inbox/spam)
4. Complete store profile setup
5. Start managing your store!

---

🏗️ Project Structure

convinence_store/
├── .env.example              # Environment variable template
├── .gitignore                # Git ignore rules (SECURITY CRITICAL)
├── SECURITY_AUDIT_REPORT.md  # Security audit findings
├── ZERO_DATA_BREACH_CHECKLIST.md  # Security verification
├── web/                      # React web application
│   ├── .env.local            # Firebase credentials (GITIGNORED)
│   ├── firestore.rules       # Firestore security rules
│   ├── SECURITY.md           # Security documentation
│   ├── public/
│   │   └── index.html
│   └── src/
│       ├── auth/             # Authentication flows
│       │   ├── AuthContext.js       # Auth state management
│       │   ├── Login.js             # Login page
│       │   ├── Signup.js            # Signup page
│       │   ├── EmailVerification.js # Email verification
│       │   ├── ProfileSetup.js      # Store profile setup
│       │   ├── ProtectedRoute.js    # Route guard
│       │   └── ProfileGuard.js      # Profile completion guard
│       ├── pages/            # Main application pages
│       │   ├── Dashboard.js         # Analytics dashboard
│       │   ├── Invoices.js          # Invoice list
│       │   ├── CreateInvoice.js     # Invoice creation
│       │   ├── PendingInvoices.js   # Pending payments
│       │   ├── Customers.js         # Customer list
│       │   ├── CustomerHistory.js   # Customer details
│       │   ├── Products.js          # Product catalog
│       │   └── Profile.js           # User profile
│       ├── components/       # Reusable components
│       │   ├── Header.js            # Navigation header
│       │   └── CurrencySelector.js  # Currency switcher
│       ├── shared/
│       │   ├── config/
│       │   │   └── firebaseConfig.js  # Firebase setup
│       │   └── services/     # Business logic
│       │       ├── authService.js       # Authentication
│       │       ├── customerService.js   # Customer CRUD
│       │       ├── productService.js    # Product CRUD
│       │       ├── invoiceService.js    # Invoice CRUD
│       │       ├── categoryService.js   # Category CRUD
│       │       └── dataManagementService.js  # Data cleanup
│       ├── utils/            # Utility functions
│       │   ├── securityUtils.js      # Security helpers
│       │   ├── invoicePrintUtils.js  # Invoice printing
│       │   ├── currencyUtils.js      # Currency formatting
│       │   ├── migrationUtils.js     # Data migration
│       │   └── serviceTestUtils.js   # Testing utilities
│       ├── styles/
│       │   ├── global.css            # Global styles
│       │   └── design-system.css     # Design tokens
│       ├── App.js            # Root component
│       └── index.js          # Entry point
└── shared/                   # Shared code (mobile/web)
    ├── config/
    │   └── firebaseConfig.js
    └── services/

---

🛡️ Security Features

✅ Implemented

1. Credential Protection

   • All secrets in .env.local (gitignored)
   • No hardcoded API keys
   • Runtime config validation

2. Firestore Security

   • User-specific data collections
   • Authentication required for all operations
   • Email verification enforced
   • Cross-user access blocked

3. Input Validation

   • XSS protection (DOMPurify)
   • SQL injection prevention (Firestore SDK)
   • Email/phone validation
   • Rate limiting

4. Authentication

   • Email/password login
   • Email verification required
   • Profile setup enforced
   • Protected routes

5. Data Isolation

   • User-specific Firestore paths
   • No shared collections
   • Query scoping by user ID

📋 Security Checklist

Before deploying to production:

• .env.local created with Firebase credentials
• Firestore rules deployed (firebase deploy --only firestore:rules)
• Email verification enabled in Firebase Console
• Environment variables set in hosting platform
• Build artifacts not committed to git
• Security audit report reviewed

See ZERO_DATA_BREACH_CHECKLIST.md for complete verification steps.

---

🚀 Deployment

⚠️ CRITICAL: Always Build Before Deploying

Run this automated script before any deployment:

cd web
./pre-deploy.sh

This ensures:

• ✅ Environment variables are configured
• ✅ Dependencies are installed
• ✅ Production build is created (npm run build)
• ✅ Build is optimized and ready

Or build manually:

cd web
npm run build

📖 See QUICK-DEPLOY-GUIDE.md for detailed deployment instructions

---

Live Production URL 🌐

🔗 https://web-p4jrkb90h-9bishals-projects.vercel.app

The app is successfully deployed and running on Vercel!

Vercel Deployment

✅ Project Setup Complete

• Project: web
• Status: ● Ready (Production)
• Platform: Vercel

Quick Deploy Steps

1. Build First ⚠️

   cd web
   npm run build

2. Install Vercel CLI (if not already installed)

   npm install -g vercel

3. Set Environment Variables (in Vercel Dashboard)

   • Go to Project Settings
   • Add all REACT_APP_FIREBASE_* variables from .env.local

4. Deploy to Production

   cd web
   vercel --prod

5. Deploy Preview (for testing)

   cd web
   vercel

Netlify

1. Build First ⚠️

   cd web
   npm run build

2. Build Command (in Netlify Dashboard)

   npm run build
   

3. Publish Directory

   build
   

4. Environment Variables (in Netlify Dashboard)

   • Site Settings → Build & Deploy → Environment
   • Add all REACT_APP_FIREBASE_* variables

5. Deploy

   npm install -g netlify-cli
   netlify deploy --prod --dir=build

Firebase Hosting

1. Build First ⚠️

   cd web
   npm run build

2. Initialize

   firebase init hosting

3. Set Environment Variables

   • Ensure .env.local exists before building
   • Variables are baked into build

4. Deploy

   cd web
   npm run build
   firebase deploy --only hosting

Post-Deployment: Firebase Configuration

🚨 CRITICAL: After deploying, add your domain to Firebase:

1. Go to Firebase Console
2. Select your project
3. Navigate to Authentication → Settings → Authorized domains
4. Click Add domain
5. Add your production URL:
   • For Vercel: your-app.vercel.app
   • For Netlify: your-app.netlify.app
   • Custom domain: yourdomain.com

Without this step, users will see authentication errors!

📖 For complete deployment guide, see:

• QUICK-DEPLOY-GUIDE.md
• PRODUCTION-DEPLOYMENT-CHECKLIST.md

---

🧪 Testing

Run Tests

# Unit tests
npm test

# Test Firestore services
node src/utils/serviceTestUtils.js

# Test data migration
node src/utils/migrationUtils.js

Security Testing

# Check for hardcoded secrets
grep -r "AIzaSy" --exclude-dir=node_modules --exclude="*.env*" .

# Verify gitignore
git check-ignore .env.local

# Test Firestore rules
# Use Firebase Console → Firestore → Rules → Rules Playground

---

📚 Documentation

• SECURITY.md - Security implementation guide
• SECURITY_AUDIT_REPORT.md - Audit findings
• ZERO_DATA_BREACH_CHECKLIST.md - Security verification
• MULTI_USER_IMPLEMENTATION.md - Multi-tenancy guide

---

🐛 Troubleshooting

Firebase Not Initialized

Error: Firebase configuration is incomplete!

Solution:

• Ensure .env.local exists in web/ directory
• Verify all REACT_APP_FIREBASE_* variables are set
• Restart development server

Permission Denied (Firestore)

Error: Missing or insufficient permissions.

Solution:

• Deploy Firestore rules: firebase deploy --only firestore:rules
• Verify email is verified (check Firebase Console → Authentication)
• Ensure user has completed profile setup

Build Fails

Error: Cannot find module 'firebase'

Solution:

rm -rf node_modules package-lock.json
npm install

---

🤝 Contributing

1. Fork repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Security Note: Never commit .env.local or build artifacts!

---

📄 License

This project is proprietary and confidential.

---

🆘 Support

Security Issues

🚨 DO NOT open public issues for security vulnerabilities!

Email: [[email protected]]

Bug Reports

Open an issue on GitHub with:

• Steps to reproduce
• Expected vs actual behavior
• Screenshots (if applicable)
• Browser/OS information

---

🎯 Roadmap

Completed ✅

• Multi-user authentication
• User-specific data isolation
• Invoice management
• Customer tracking
• Product catalog
• Category management
• Dashboard analytics
• Security hardening

In Progress 🚧

• Mobile app (React Native)
• Advanced reporting
• Multi-store support
• Barcode scanning

Planned 📋

• Inventory forecasting
• Automated reordering
• Supplier management
• Employee management
• POS integration

---

📊 Tech Stack

• Frontend: React 18
• Backend: Firebase (Firestore, Auth)
• Styling: CSS3 with custom design system
• Security: DOMPurify, rate limiting, input validation
• Deployment: Vercel / Netlify / Firebase Hosting

---

Version: 2.0
Last Updated: November 19, 2025
Security Status: 🟢 Production-Ready