Data Model
MaxShipping uses Cloud Firestore as its primary database on project max-inventory-scanner-b0b53. There are 23 collections in production.
Core Collections
Packages
The central collection — every package in the system.
| Field | Type | Description |
|---|---|---|
| packageID | string | Document ID / unique package identifier |
| clientID | string | Reference to Clients collection |
| trackingNumber | string | Tracking number (may be cleaned/normalized) |
| rawTrackingNumber | string | Original tracking number as scanned |
| status | string | Current pipeline stage |
| logistic | string | Shipping provider (e.g. “Amazon US Logistics”, “FedEx”, “UPS”) |
| isMissing | boolean | Flagged as missing |
| isMainPackage | boolean | Whether this is a main (consolidated) package |
| containerID | string | Container this package is loaded into |
| itemID | map | Item reference with itemID and itemCost sub-fields |
| charges | map | Charge IDs mapped to quantities (e.g. {chargeID: quantity}) |
| dimensions | map | {height, length, width} measurements |
| consolidatedInto | string | If consolidated, the parent package ID |
| containsPackages | array/null | If consolidated parent, list of child package IDs |
| scanHistory | array | List of scan entries (see below) |
| lastScanned | timestamp | Most recent scan timestamp |
scanHistory entry:
| Field | Type | Description |
|---|---|---|
| userRole | string | “Receiving”, “Check In”, “Client Pickup”, etc. |
| user | string | User document ID who performed the scan |
| timestamp | timestamp | When the scan occurred |
| note | string | Optional note |
| problem | string/null | Problem flag (“No Name”, “No Address”, “Damaged”, etc.) |
| photo | string/null | Photo evidence URL |
Status values: received, unprocessed, checkIn, inTransit, unloaded, clientPickUp, CONSOLIDATED
Clients
Client directory with full contact and Square integration data.
| Field | Type | Description |
|---|---|---|
| clientID | string | Document ID |
| firstName | string | First name |
| lastName | string | Last name |
| name | string | Full display name (firstName + lastName) |
| emailAddress | string | Contact email |
| phoneNumber | string | Phone number (E.164 format, e.g. “+2038889299”) |
| referenceId | string | Numeric client reference ID (e.g. “2245”) |
| showID | string | Display ID (usually matches referenceId) |
| squareCustomerId | string | Square payment platform customer ID |
| location | string | Client location (Roatan, Utila, La Ceiba, Guanaja, Barbareta, etc.) |
| discountCode | string | Default discount code name (e.g. “Roatan”) |
| companyName | string/null | Company name if applicable |
| birthday | string/null | Client birthday |
| city | string/null | City |
| clientNote | string/null | Internal notes about client |
| creationSource | string | How account was created (e.g. “Max Shipping Website”) |
| origin | string | Origin source |
| emailSubscriptionStatus | string/null | Email subscription preference |
| needsAdminReview | boolean | Flagged for admin review |
Invoices
Billing documents linking packages to payments.
| Field | Type | Description |
|---|---|---|
| invoiceID | string | Document ID |
| clientID | string | Reference to Clients |
| containerID | string | Reference to Containers |
| squareCustomerId | string | Square customer ID for payment |
| status | string | “APPROVED”, “UNAPPROVED” |
| approveIsTicked | boolean | Whether approve checkbox is checked |
| packages | array | List of package line items (see below) |
| discounts | array | Applied discount entries |
| subTotal | number | Pre-tax total |
| tax | number | Tax amount (15%) |
| totalCost | number | Final total (subTotal + tax) |
| paid | boolean | Whether payment is complete |
| invoiceSent | boolean | Whether email was dispatched |
| automaticallySent | number | Auto-send status: 0=pending, 1=auto-sent, 2=failed, 3=manual-sent, 4=manual-failed |
| isAllUnloaded | boolean | Whether all packages in invoice are unloaded |
| sentToSquareAt | timestamp | When invoice was sent to Square |
| timestamp | timestamp | Invoice creation time |
| message | string/null | Optional message |
packages[] entry:
| Field | Type | Description |
|---|---|---|
| packageId | string | Package document ID |
| packageStatus | string | Current status of this package |
| trackingNumber | string | Tracking number |
| item | string | Item description (dimensions or name) |
| itemID | string | Item document ID |
| cost | number | Line item cost |
| charges | array | Applied charges with chargeName, chargeID, quantity, unitCost, totalChargeCost, chargeTokenID, chargeDescription |
| note | string | Note (“-” if none) |
| problem | string | Problem flag (“-” if none) |
| photo | string | Photo URL (“-” if none) |
| containsPackagesCount | number | Number of sub-packages |
| containsPackages | array | Sub-package IDs |
| isTaxable | boolean | Whether tax applies |
| itemTokenID | string | Square catalog token ID |
| packageDescription | string | Description of consolidated contents |
Containers
Shipping containers grouping packages for transport.
| Field | Type | Description |
|---|---|---|
| containerName | string | Display name (e.g. “Container - 01/27/2026”) |
| containerCreatedAt | timestamp | When container was created |
| isBackedUp | boolean | Whether archived to secondary DB |
| invoices | array | Nested array of invoice summaries |
invoices[] entry:
| Field | Type | Description |
|---|---|---|
| invoiceID | string | Invoice document ID |
| packages | array | List of {packageID, status} entries |
Catalog Collections
Items
Product catalog for pricing packages.
| Field | Type | Description |
|---|---|---|
| itemID | string | Document ID |
| itemName | string | Display name (e.g. “70 Inch TV”, “Small Box”) |
| itemCost | number | Price |
| categoryID | string | Reference to Categories collection |
| tokenID | string | Square catalog object ID |
Categories
Item categories with tax configuration.
| Field | Type | Description |
|---|---|---|
| categoryID | string | Document ID |
| categoryName | string | Display name (e.g. “Paint”, “Appliances”) |
| isTaxable | boolean | Whether items in this category are taxed |
| isDefault | boolean | Whether this is a default category |
| tokenID | string | Square catalog token ID |
Charges
Additional fees applied to packages.
| Field | Type | Description |
|---|---|---|
| chargeID | string | Document ID |
| chargeName | string | Display name (e.g. “Forklift charge ($100)”, “Miscellaneous fee ($10)”) |
| chargeCost | number | Cost per unit |
| tokenID | string | Square catalog token ID |
Discounts
Discount codes applied to invoices.
| Field | Type | Description |
|---|---|---|
| discountID | string | Document ID |
| discountName | string | Display name (e.g. “Business”, “Utila Discount To Offset Ferry Shipping”) |
| discountValue | number | Discount amount (0.1 = 10%, 0.25 = 25%, 1.0 = 100%) |
| isPercentage | boolean | Whether discountValue is a percentage |
User & Auth Collections
User
User accounts for staff and admins.
| Field | Type | Description |
|---|---|---|
| userID | string | Document ID |
| name | string | Display name |
| username | string | Login username |
| password | string | Login password |
| userRole | string | Role (e.g. “admin”) |
| isSuperAdmin | boolean | Super admin flag |
| isLoggedIn | boolean | Currently logged in |
| activeDeviceId | string | Current device UUID |
| lastActiveAt | timestamp | Last activity timestamp |
| deviceLoggedInAt | timestamp | When current device session started |
| lastLogoutAt | timestamp | Last logout timestamp |
Password
App-level shared password.
| Field | Type | Description |
|---|---|---|
| password | string | Shared app password |
Single document collection.
UserLogs
Session tracking for user login/logout.
| Field | Type | Description |
|---|---|---|
| userID | string | Reference to User collection |
| loginTime | timestamp | Session start |
| logoutTime | timestamp | Session end |
| isActive | boolean | Whether session is still active |
activeDevices
Tracks which devices are currently logged in.
| Field | Type | Description |
|---|---|---|
| userId | string | Reference to User collection |
| deviceId | string | UUID of the device |
| loggedInAt | timestamp | When device logged in |
Permission Collections
webPermissions
Action-based access control for the web app.
| Field | Type | Description |
|---|---|---|
| action | string | Permission action name |
| allowedUsers | array | User document IDs granted this permission |
Known actions: view_approve_or_send_invoices, edit_permissions, view_tracking_number_qr, mark_package_as_missing, edit_client, and more.
AppPermissions
Action-based access control for the scanner app.
| Field | Type | Description |
|---|---|---|
| action | string | Permission action name (e.g. “Add Charges”, “Change Price”) |
| userIDs | array | User document IDs granted this permission |
Note: Uses userIDs (not allowedUsers like webPermissions).
System Collections
Temp
Temporary system state.
| Document | Fields | Description |
|---|---|---|
timer |
isPasswordExpired (boolean) |
Password expiry timer for no-password periods |
systemVars
System-wide configuration and auto-incrementing counters.
| Document | Fields | Description |
|---|---|---|
labelCounter |
lastNumber (number) |
Auto-incrementing label counter (e.g. 24088) |
usefulInformation |
lastRefId, lastRefId3-lastRefId9 (numbers), series mappings |
Reference ID counters per series and series-to-series mapping |
ProcessedOperations
Idempotency tracking to prevent duplicate invoice processing.
| Field | Type | Description |
|---|---|---|
| invoiceID | string | Invoice that was processed |
| processedAt | timestamp | When processing completed |
Document ID is the operation UUID.
PubSubQueue
Deduplication for PubSub invoice processing.
| Field | Type | Description |
|---|---|---|
| operationID | string | UUID of the PubSub operation |
| enqueuedAt | timestamp | When message was enqueued |
Document ID matches the invoice ID.
squareAPILog
Audit log for Square API calls.
| Field | Type | Description |
|---|---|---|
| orderData | map | Full Square order request payload (line items, taxes, discounts) |
| invoiceData | map | Full Square invoice request payload (recipient, payment terms, custom fields) |
Document ID matches the invoice ID.
webLogs
Activity and action logging.
| Field | Type | Description |
|---|---|---|
| action | string | Action type (e.g. “checked_in_package”) |
| message | string | Human-readable description |
| timestamp | timestamp | When action occurred |
| userID | string | User who performed the action |
| trackingNumber | string | Related tracking number (if applicable) |
| isFromApp | boolean | Whether action came from the scanner app |
| isBadScan | boolean | Whether this is a bad scan alert (triggers badScanAlert function) |
checkResults
Daily automated data quality check results.
| Field | Type | Description |
|---|---|---|
| issues | array | List of detected issues |
| runDate | string | Date string (e.g. “2025-01-27”) |
| updatedAt | timestamp | When check completed |
Document ID format: {type}-{date} (e.g. “clients-2025-01-27”).
userDailyData
Aggregated user activity per day. Written by dailyDataReport scheduled function.
UserAppVersion
Tracks which app version each user is running.
| Field | Type | Description |
|---|---|---|
| userID | string | Reference to User collection |
| version | string | App version (e.g. “1.2.5”) |