GE-80: Inventory Management System — Jersey & Equipment Tracking

Summary

A standalone inventory management system designed primarily for tracking youth sports league jerseys across all sports, age groups, colors, and sizes. Architected as a generalized inventory platform capable of managing any league equipment (goals, nets, bases, balls, cones, etc.) with full supplier management, purchase orders, distribution tracking, and season-end return processing.

Epic: GE-80 (18 child features: GE-81 through GE-98) Status: All Idea Origin: No direct SCRUM predecessor — this is a new initiative

---

Child Features

Foundation

Key	Feature	Purpose
GE-81	Project Scaffolding & Shared Auth	Standalone repo, same stack (React/Vite/Express/PostgreSQL), JWT token exchange with G2 Elite
GE-95	User Roles & Permissions	Inventory Admin, Manager, Coach (view-only for their team), Volunteer
GE-98	Settings, Configuration & Multi-Sport Defaults	Org settings, sport-specific size/color defaults with gender awareness

Product & Supplier

Key	Feature	Purpose
GE-82	Product Catalog & Item Definitions	InventoryItem entity: name, category (Jersey/Equipment/Supplies), sport, gender, age group, color, size, SKU, costs, reorder point
GE-83	Supplier Management	Supplier contacts, payment terms, supplier-product relationships, price tracking

Procurement

Key	Feature	Purpose
GE-84	Purchase Order Management	PO lifecycle (Draft → Submitted → Received → Closed), line items, auto-calculate totals, approval workflow
GE-85	Inventory Receiving & Stock Management	Receiving workflow against POs, discrepancy flagging, real-time stock levels, location tracking

Distribution & Returns

Key	Feature	Purpose
GE-86	Jersey Distribution & Assignment Tracking	Track handoffs to coaches/players by sport → gender → age group → team, girls teams get gender-specific sizing
GE-90	Returns, Condition Tracking & Jersey Lifecycle	End-of-season returns, condition grading (New/Good/Fair/Poor/Retired), lifecycle cost tracking, retirement workflow

Intelligence & Alerting

Key	Feature	Purpose
GE-87	Low Stock Alerts & Notification Engine	Configurable reorder points, alert types (low/critical/out/overstock), email/push/in-app notifications
GE-91	Season Planning & Demand Forecasting	Historical analysis, growth projections, demand forecast by sport/age group, pre-season order recommendations

Reporting & Visibility

Key	Feature	Purpose
GE-88	Dashboard & Inventory Overview	Summary cards, interactive charts, stock levels by sport, distribution progress, return rates
GE-89	Reporting & Analytics	Inventory valuation, stock movement, distribution summary, cost per player, supplier performance, seasonal comparison
GE-93	Audit Trail & Activity Log	Immutable log of every inventory action (who, what, when, why, before/after values)

Physical Operations

Key	Feature	Purpose
GE-92	Barcode/QR Code Integration	Generate QR codes per SKU, print labels (Dymo/Zebra), scan to receive/distribute/return/audit
GE-97	Mobile-Responsive UI & Field Operations	Mobile-optimized for receiving at storage, distributing at field, processing returns, quick stock checks

Integration

Key	Feature	Purpose
GE-94	API Integration with G2 Elite	Pull sports, age groups, seasons, teams, rosters, coaches from G2 Elite; sync events for jersey distribution triggers
GE-96	Import/Export & Data Migration	CSV import for initial inventory load, Excel export for all views, import validation with preview

---

Considerations & Gaps

Architecture Decisions Needed

1. Standalone vs integrated? GE-81 specifies a standalone repository with shared auth via JWT token exchange. This is a reasonable approach — inventory management is a distinct domain. However, it means maintaining a separate deployment, database, and codebase. Consider whether this should be a Cloudflare Workers project (aligned with the new architecture) or a traditional Express/PostgreSQL app (aligned with the existing web app).

2. Database strategy. The inventory system needs its own database — it's a different domain with different access patterns. Does each org get their own inventory DB (like the org DB pattern), or is this a shared multi-tenant database with organization_id columns? For inventory, a shared database is likely fine since the data volume is low.

3. Hosting platform. If standalone, where does this run? Options: (a) Cloudflare Workers + D1/Neon — aligned with new architecture, (b) AWS App Runner — aligned with existing web app, (c) Cloudflare Pages + Workers — static frontend + API workers. Given the direction of the platform, Cloudflare is the natural choice.

Feature Gaps

4. No jersey number assignment integration. The existing players table has jerseyNumber. When jerseys are distributed (GE-86), the system should optionally update the player's jersey number in the org DB. This cross-system write isn't mentioned in GE-94 (API Integration).

5. No photo documentation. When inspecting returned jerseys for condition grading (GE-90), it would be valuable to capture photos of damage/wear. No feature addresses this.

6. No cost allocation to teams/sports. The system tracks costs per item but doesn't allocate jersey costs to specific teams or sports budgets. For organizations that charge teams for jerseys or track per-sport equipment budgets, this is a gap.

7. No multi-season jersey reuse tracking. Jerseys often survive multiple seasons. The lifecycle tracking (GE-90) grades condition but doesn't explicitly track "Season 1: assigned to Player A, returned Good → Season 2: assigned to Player B, returned Fair." A full assignment history per physical jersey unit is needed.

8. No deposit/fee tracking. Many leagues charge a jersey deposit that's refunded on return. The system has no concept of player-facing fees tied to distribution.

9. No integration with registration. When a player registers (existing registration system), their jersey size preference could auto-populate inventory demand. GE-91 (demand forecasting) mentions pulling historical registration data but doesn't mention real-time registration → inventory demand sync.

Dependencies

10. GE-94 (API Integration) is critical path. The inventory system needs sports, age groups, teams, and rosters from G2 Elite. Without this integration, all that data must be manually entered — defeating the purpose.

11. GE-81 (Scaffolding) mentions the existing web app stack (React/Vite/Express/PostgreSQL). But the platform is moving to Cloudflare Workers. This needs a decision: build on the old stack for speed, or build on the new stack for alignment?

12. GE-92 (Barcode/QR) needs hardware. Label printing integration requires specific hardware (Dymo, Zebra printers). This feature should be scoped as optional/later — the core system works without it.

Scope Concerns

13. This is a full ERP inventory module. 18 features covering product catalog, supplier management, purchase orders, receiving, distribution, returns, forecasting, barcode scanning, and reporting. This is comparable to systems like Sortly, inFlow, or Cin7 — commercial products with dedicated teams.

14. Gender-aware sizing is a key requirement. GE-86 and GE-98 specifically call out that girls teams (Girls Basketball, Girls Flag Football) need gender-specific sizing options. The product catalog (GE-82) must support gender as a first-class attribute, not an afterthought.

15. Recommended MVP: GE-81 (scaffolding) → GE-82 (product catalog with sizes/colors/sports) → GE-85 (stock management — just tracking quantities) → GE-86 (jersey distribution to teams/players) → GE-90 (season-end returns). This gives Rob the ability to track who has which jerseys, what sizes are in stock, and process returns — the core pain point. Suppliers, POs, forecasting, and barcodes come later.

Overlap with Workforce Scheduler

16. Both GE-61 and GE-80 specify standalone repos with shared auth. Consider establishing a shared authentication and project template pattern once (GE-81) and reusing it for the workforce module. Don't solve this problem twice.

17. Both need mobile field operations. GE-76 (workforce mobile) and GE-97 (inventory mobile) both add functionality to the mobile app. Coordinate the mobile app architecture to accommodate multiple add-on modules without bloating the app.