Troubleshooting & Scripts
Relevant source files
The following files were used as context for generating this wiki page:
The DRX project utilizes a robust suite of shell scripts and TypeScript utilities to manage system health, automate deployments, and provide user-facing troubleshooting guidance. These tools cover database schema verification, automated versioning, data synchronization with external help centers, and integrated help documentation for common operational issues.
This system ensures that developers can maintain environment parity through structured deployment workflows while providing end-users with self-service solutions for Point of Sale (POS) and inventory management challenges.
Deployment and Infrastructure Scripts
The project uses specialized scripts to automate the deployment and verification of core systems, specifically for the Inventory Intake module. These scripts handle database migrations, schema verification, and build testing.
Automated Deployment Workflow
The deploy-inventory-intake.sh script manages the rollout of the inventory intake cost tracking system. It follows a structured 4-step process:
- Migration Application: Applies SQL migrations (e.g.,
20251207000001_inventory_intake_cost_tracking.sql) using the Supabase CLI. - Schema Verification: Prompts manual verification of critical tables like
inventory_intakesandcost_history. - Build Validation: Executes
npm run buildto ensure code integrity. - Summary: Provides a checklist of deployed backend APIs and frontend UI updates.
Sources: deploy-inventory-intake.sh:11-73
Database and Schema Testing
The test-inventory-intake.sh script provides a comprehensive test suite for database integrity and cost calculation logic.
The diagram shows the multi-phase testing strategy used to ensure financial and structural accuracy in the inventory system.
Sources: test-inventory-intake.sh:42-132
Version Management
DRX adheres to a strict versioning protocol where a VERSION file at the repository root serves as the single source of truth. The scripts/version.ts utility automates the process of bumping versions across the entire stack.
Version Analysis and Bumping
The script analyzes the [Unreleased] section of CHANGELOG.md to determine the appropriate Semantic Versioning (SemVer) bump type:
- Major: Triggered by keywords like "Removed", "Changed...breaking", or "BREAKING".
- Minor: Triggered by "Added" features.
- Patch: Default for bug fixes or "Fixed" items.
Sources: scripts/version.ts:75-103
Synchronization Targets
When a version is bumped via npx tsx scripts/version.ts bump, the following files are updated automatically:
| Target | Description |
|---|---|
VERSION | Root file source of truth |
package.json | Project manifest version |
CHANGELOG.md | Updates [Unreleased] to specific version and date |
| UI Components | Updates version strings in sidebar.tsx, admin/page.tsx, etc. |
Sources: scripts/version.ts:133-181, CHANGELOG.md:46-51
Help Center & Documentation Sync
The project implements an automated pipeline to sync local help documentation with external platforms like Featurebase.
Help Data Structure
Documentation is defined in scripts/help-center-data.ts using the HelpArticle interface. Each article contains metadata for categorization and role-based filtering.
- Categories:
getting-started,pos,inventory,products,customers,credit,roles,privacy. - Roles:
owner,manager,staff.
Sources: scripts/help-center-data.ts:1-11
Sync Logic
The scripts/sync-help-center.ts utility performs the following operations:
- Collection Mapping: Maps local category tags to Featurebase collections (e.g.,
pos-> "POS & Sales"). - Upsert Mechanism: Checks if an article title exists; if so, it performs a
PATCHrequest to update, otherwise aPOSTto create. - Authentication: Uses
FEATUREBASE_API_KEYfrom.env.local.
Sources: scripts/sync-help-center.ts:88-145
Operational Troubleshooting
The application includes a dedicated Help Page (app/(app)/help/page.tsx) that provides immediate troubleshooting steps for common staff issues.
Common Issues & Solutions
| Issue | Cause | Solution |
|---|---|---|
| Sale Failed: "Insufficient Stock" | Attempting to sell more than available. | Check inventory; add stock via Intake. |
| Customer Creation Failed | Missing phone or email. | Ensure at least one contact method is provided. |
| Dashboard Shows Zero Sales | Incorrect date filter or no data. | Verify date range filter or perform test sale. |
| Error During Checkout | Network or database issue. | Check internet; cart is preserved for retry. |
Sources: app/(app)/help/page.tsx:162-205
POS and Inventory Troubleshooting Flow
This diagram illustrates the logic for the most frequent POS error regarding stock availability.
Sources: app/(app)/help/page.tsx:164-173
Summary
The Troubleshooting & Scripts system in DRX provides a comprehensive framework for maintaining operational stability. By combining automated database testing (test-inventory-intake.sh), strict versioning (version.ts), and synchronized documentation (sync-help-center.ts), the project ensures that both developers and end-users have the tools necessary to resolve conflicts and maintain a reliable point-of-sale environment.