Inventory API
Enterprise-grade, cloud-native backend service
The Inventory API is the operational backbone powering a sophisticated retail and wholesale commerce platform for food and beverage operations. It seamlessly integrates iOS retail, iOS wholesale, and admin applications into a unified system — serving multiple independent businesses with full tenant isolation, real-time inventory tracking, and a sophisticated customer engagement engine.
highlights
Production-Ready Multi-Tenant Architecture
PostgreSQL Row-Level Security enforced on 35 tables ensures complete data isolation at the database level — not just application layer. Each tenant operates independently with its own customer base, inventory, pricing, and rate limits.
Sophisticated Loyalty & Engagement Engine
A 4-tier loyalty program (Scoops → Silver → Gold → Diamond) with 12 achievement categories, streak bonuses with grace logic, 10 coupon types including viral referral chains, and 5 promotion types with auto-evaluation.
Bank-Grade Idempotency & Audit
24-hour idempotency key cache prevents duplicate charges from mobile retries. Persistent audit logs track every mutation with actor, timestamp, and entity type for compliance and forensics.
Full Observability Stack
OpenTelemetry distributed tracing, structured JSON logging with tenant/request context, Sentry error capture, and health endpoints — built in from day one, not retrofitted.
features
Order & Payment Processing
- Full order lifecycle with 8 status timestamps and audit trail
- Stripe integration with idempotency keys — exactly-once payment processing
- Bulk order item operations with atomic validation
- Curbside pickup workflow with real-time arrival announcements
- Delivery route optimization with stop sequencing
Inventory & Product Management
- Real-time stock tracking across multiple suppliers and locations
- Bulk restock workflow with all-or-nothing atomic transactions
- Product variants with independent pricing, SKU, and images
- Soft archiving preserves historical transaction integrity
- Cost-per-unit and supplier linkage for procurement analytics
Customer Engagement & Loyalty
- 4-tier loyalty system with automatic promotion based on 12-month point windows
- 12 achievement categories including category diversity, streaks, and birthdays
- Streak bonuses with grace logic — miss one week without losing progress
- 10 coupon types including viral referral chains with share tokens
- Promotion engine with 5 types × 3 scopes and auto-apply best-qualifying offer
Security & Compliance
- JWT authentication with 30-day expiry and per-token revocation
- Row-Level Security on 35 tables — no app-layer bugs can leak cross-tenant data
- Three session types: Customer (wholesale), User (retail), Anonymous (guest)
- Per-tenant rate limiting tiers (Free / Standard / Premium)
- OWASP Top 10 coverage including BOLA, injection, XSS, CSRF mitigations
Operations & Developer Experience
- 143 endpoints across 32 router modules with OpenAPI documentation
- 349 automated tests across unit, integration, and smoke categories
- ~98% type-hint coverage enabling static analysis and safe refactoring
- Single idempotent database migration script — fully re-runnable
- Replit Autoscale deployment with horizontal scaling support