Introduction
The SushiGo inventory system is designed to manage stock across multiple locations within operating units (branches and events). It provides complete traceability of all movements, supports multiple units of measure with conversions, and maintains weighted average costing for profitability analysis.The inventory system is built for scalability—from a single branch to multiple locations, and from permanent stores to temporary event inventories.
Architecture Overview
Core Entities
The inventory system is built around these key entities:Items & Variants
Master catalog of products, supplies, and assets with multiple variants per item
Inventory Locations
Physical or logical zones within each operating unit (MAIN, KITCHEN, BAR, etc.)
Stock Records
Current quantities per variant per location with on_hand, reserved, and available
Stock Movements
Complete audit trail of all inventory transactions with reason codes
Inventory Hierarchy
Operating Unit Level
Operational context within a branch:
BRANCH_MAIN- Permanent branch inventoryEVENT_TEMP- Temporary event inventory
Item Types
SushiGo supports three item types, each with specific characteristics:INSUMO (Supply/Input)
Raw materials and supplies used in production or service.- Supports multiple unit conversions (e.g., kg → g, box → unit)
- Track lot numbers and serial numbers (optional)
- Perishable flag for expiration tracking
PRODUCTO (Finished Product)
Finished goods ready for sale to customers.- Base unit only (1:1 conversion)
- Sale price tracking
- Can be manufactured from INSUMOs
ACTIVO (Asset)
Physical assets used in operations (furniture, equipment, tools).- Base unit only (1:1 conversion)
- Serial number tracking recommended
- Depreciation tracking (future)
Stock Tracking
Stock States
Each variant at each location has three quantity fields:Physical quantity present at the location
Quantity reserved for pending orders or transfers
Computed field:
on_hand - reserved (available for sale/transfer)Cost Tracking
Weighted average cost per base unit, updated on each receipt
Most recent purchase cost (tracked at variant level)
Movement Reasons
All stock changes are recorded asStockMovement records with a reason code:
| Reason | Direction | Description |
|---|---|---|
OPENING_BALANCE | IN | Initial stock registration |
TRANSFER | BOTH | Inter-location or inter-branch transfer |
RETURN | BOTH | Return from customer or location |
SALE | OUT | Sale to customer (decreases stock) |
CONSUMPTION | OUT | Internal consumption (meals, samples, spoilage) |
ADJUSTMENT | IN/OUT | Manual adjustment (count variance) |
COUNT_VARIANCE | IN/OUT | Adjustment from physical count |
Design Principles
Complete Traceability
Every movement records user, timestamp, reason, and optional reference
Multi-UOM Support
Convert between units automatically (kg ↔ g, box ↔ unit)
Location Segregation
Each location maintains separate stock with transfer tracking
Weighted Costing
Automatic cost updates for profitability analysis
Key Workflows
1. Opening Balance Registration
2. Stock Out (Sale or Consumption)
3. Inter-Location Transfer
Data Model Reference
Item Fields
| Field | Type | Required | Description |
|---|---|---|---|
sku | string(100) | Yes | Unique SKU code (auto-uppercase) |
name | string(255) | Yes | Item name |
description | text | No | Detailed description |
type | enum | Yes | INSUMO, PRODUCTO, or ACTIVO |
is_stocked | boolean | No | Track in inventory (default: true) |
is_perishable | boolean | No | Has expiration date (default: false) |
is_active | boolean | No | Active status (default: true) |
ItemVariant Fields
| Field | Type | Required | Description |
|---|---|---|---|
item_id | integer | Yes | Parent item ID |
uom_id | integer | Yes | Base unit of measure |
code | string(100) | Yes | Unique variant code |
barcode | string(50) | No | Product barcode (EAN/UPC) |
name | string(255) | Yes | Variant name |
track_lot | boolean | No | Track lot numbers (default: false) |
track_serial | boolean | No | Track serial numbers (default: false) |
sale_price | decimal(4) | No | Default sale price |
min_stock | decimal(4) | No | Minimum stock level |
max_stock | decimal(4) | No | Maximum stock level |
Stock Fields
| Field | Type | Description |
|---|---|---|
inventory_location_id | integer | Location where stock is held |
item_variant_id | integer | Variant being tracked |
on_hand | decimal(4) | Physical quantity on hand |
reserved | decimal(4) | Quantity reserved |
available | decimal(4) | Computed: on_hand - reserved |
weighted_avg_cost | decimal(4) | Current average cost per unit |
StockMovement Fields
| Field | Type | Description |
|---|---|---|
from_location_id | integer | Source location (null for entries) |
to_location_id | integer | Target location (null for exits) |
item_variant_id | integer | Variant being moved |
user_id | integer | User who created movement |
qty | decimal(4) | Quantity in base UOM |
reason | enum | Movement reason code |
status | enum | DRAFT, POSTED, or REVERSED |
reference | string(100) | External reference number |
notes | text | Additional notes |
meta | jsonb | Original qty/uom, cost, etc. |
posted_at | timestamp | When movement was posted |
Next Steps
Items & Variants
Create and manage items and their variants
Inventory Locations
Configure locations within operating units
Stock Movements
Record opening balances, transfers, and adjustments
Unit Conversions
Set up unit of measure conversions