A robust, production-ready inventory management system built with React, TypeScript, and Supabase. Designed for construction sites and warehouse management with multi-user support, offline capabilities, and real-time synchronization.
All configuration values in this repo (Supabase URLs, keys, sheet IDs) are placeholders — create your own free Supabase project and fill in your own credentials to run it.
- Real-Time Sync: Changes appear instantly across all devices with throttled updates
- Multi-User: Role-based access (Admin/User) with 15-20+ concurrent user support
- Category Management: Organize items into folders
- Transaction Tracking: IN/OUT/WIP with full history and pagination
- Location Tracking: Track where materials are used
- Cost Tracking: Optional amount and bill number fields
- Contractor Management: Track materials given to contractors with balance sheets
- Mobile-First PWA: Installable app that works offline
- High-Performance Stock Lookups: O(1) queries via trigger-maintained
stock_summarytable - Connection Quality Monitoring: Visual indicators for network health
- Automatic Retry: Exponential backoff for failed requests
- Offline Stock Validation: Prevents negative stock even offline
- Conflict Resolution UI: Resolve sync conflicts with a dialog
- Error Boundary: Graceful error handling with recovery options
- Session Expiry Warning: Notification before 30-day session expires
- Filter Persistence: History filters saved across sessions
- Searchable Dropdowns: Search items in transaction form
- Chunked CSV Export: Handle large exports without memory issues
- Node.js 18+
- Supabase account (free tier works)
- Vercel/Netlify account (for deployment)
git clone <your-repo-url>
cd Inventory-Mandu
npm install- Go to supabase.com and create a new project
- Wait for the database to be ready (~2 minutes)
- Go to SQL Editor → New Query
- Copy the contents of
supabase/schema.sqland run it - Go to Settings → API and copy:
- Project URL
anonpublic key
Create .env.local in the project root:
VITE_SUPABASE_URL=https://your-project-id.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-herenpm run devDefault Login:
- Admin:
admin/admin123 - User:
mandu/mandu123
If you're upgrading from v3.x, run the migration SQL:
- Go to Supabase SQL Editor
- Copy contents of
supabase/MIGRATION_v4.sql - Run the query
- Verify with:
SELECT * FROM stock_summary LIMIT 10;
This creates the stock_summary table with triggers for instant stock lookups.
- Push code to GitHub
- Go to vercel.com → Import Project
- Select your repository
- Add Environment Variables:
VITE_SUPABASE_URLVITE_SUPABASE_ANON_KEY
- Deploy!
- Open your app URL in Safari
- Tap Share button (square with arrow)
- Tap "Add to Home Screen"
- Tap "Add"
- Open your app URL in Chrome
- Tap the install banner, or Menu → "Install app"
- Tap "Install"
Inventory-Mandu/
├── App.tsx # Main app with state management
├── types.ts # TypeScript types
├── index.tsx # Entry point with providers
├── lib/
│ ├── supabase.ts # Supabase client & connection monitoring
│ ├── database.types.ts # Database types & converters
│ └── db.ts # Database operations with caching
├── components/
│ ├── Dashboard.tsx # Main inventory view
│ ├── TransactionForm.tsx # Stock IN/OUT/WIP form
│ ├── ItemManager.tsx # Catalog view
│ ├── HistoryLog.tsx # Transaction history with filters
│ ├── LoginPage.tsx # Authentication
│ ├── AdminPanel.tsx # Admin settings
│ ├── SearchableSelect.tsx # Searchable dropdown component
│ ├── SyncConflictDialog.tsx # Conflict resolution UI
│ ├── ErrorBoundary.tsx # Error handling wrapper
│ └── ...
├── public/
│ ├── sw.js # Service worker with API caching
│ └── manifest.json # PWA manifest
├── supabase/
│ ├── schema.sql # Full database schema
│ └── MIGRATION_v4.sql # Upgrade migration
└── package.json
Stock levels are calculated via a trigger-maintained stock_summary table:
-- O(1) lookup instead of O(n) aggregation
SELECT current_quantity, wip_quantity FROM stock_summary WHERE item_id = ?Triggers automatically update stock on every INSERT/UPDATE/DELETE on transactions.
User Action → Supabase → Throttled Subscription (2-3s) → Incremental Updates → UI
- Items/Transactions: 2 second throttle with incremental merging
- Categories/Contractors: 3 second throttle
Online: App → Supabase API (with retry) → Cache
Offline: App → localStorage + Pending Queue → Sync when online
- Service worker caches API responses for 5 minutes
- Pending operations queue syncs when connection restored
- Offline stock validation prevents negative stock
| Role | Permissions |
|---|---|
| Admin | Manage users, edit all transactions, manage categories/contractors |
| User | Add/use stock, view all data, edit own transactions |
| Metric | Capacity |
|---|---|
| Items | 10,000+ |
| Transactions | 100,000+ per year |
| Concurrent Users | 15-20+ on slow WiFi |
| Stock Lookup | O(1) via triggers |
| Pagination | 50 items per page |
| Quality | Latency | Indicator |
|---|---|---|
| Excellent | <300ms | Green |
| Good | <800ms | Green |
| Slow | <2000ms | Amber |
| Poor | >2000ms | Red |
| Offline | N/A | Red + "Offline Mode" |
- Another user may have taken stock. The app shows actual available quantity.
- Click the conflict indicator to resolve. Choose to retry or dismiss each conflict.
- Click "Renew" to extend your session for another 30 days.
- Verify Supabase URL is correct
- Check that tables have realtime enabled (run schema.sql)
- Check if Supabase project is paused (free tier pauses after 1 week inactivity)
- Check for pending operations in the status bar
npm run dev # Start dev server
npm run build # Build for production
npm run preview # Preview production build
npm run lint # Type checkMIT License
v4.0.0 - Production-ready with high-performance stock tracking and enhanced reliability.