Cursor rule

1---
2description: Development workflow automation and best practices for POS System
3---
4 
5# Development Workflow Guide
6 
7## Quick Start Commands
8 
9### Primary Development Workflow
10Use [Makefile](mdc:Makefile) for all development operations:
11 
12```bash
13# Essential commands for daily development
14make help         # Show all available commands
15make dev          # Start development environment with hot reloading
16make up           # Start Docker containers in background
17make down         # Stop all containers
18make status       # Check system status
19```
20 
21### Database Management Workflow
22```bash
23# Database operations (all interactive and safe)
24make create-admin # Create super admin user
25make backup       # Backup entire system (database + files)
26make restore      # Restore from backup (interactive menu)
27make db-reset     # Reset to fresh state with seed data
28make db-shell     # Access PostgreSQL shell
29make remove-data  # DESTRUCTIVE: Remove all data (multiple confirmations)
30```
31 
32## Development Environment Setup
33 
34### First Time Setup
351. Clone repository and navigate to project root
362. Ensure Docker Desktop is running
373. Run `make dev` - automatically creates `.env` file if missing
384. Access applications:
39   - Frontend: http://localhost:3000
40   - Backend API: http://localhost:8080
41   - Database: localhost:5432
42 
43### Daily Development Workflow
44```bash
45# Start development session
46make dev          # Starts all services with hot reloading
47 
48# During development
49make logs         # View all service logs
50make logs-backend # View only backend logs
51make logs-frontend# View only frontend logs
52 
53# End development session
54make down         # Stop all containers
55```
56 
57## Database Development Workflow
58 
59### Working with Database
601. **Fresh Start**: `make db-reset` - Clean database with seed data
612. **Backup Before Changes**: `make backup` - Create safety backup
623. **Make Changes**: Edit schema files or use application
634. **Test Changes**: Verify functionality
645. **Create Admin**: `make create-admin` - Add admin users as needed
65 
66### Database Schema Changes
671. Edit [database/init/01_schema.sql](mdc:database/init/01_schema.sql)
682. Edit [database/init/02_seed_data.sql](mdc:database/init/02_seed_data.sql) if needed
693. Run `make db-reset` to apply changes
704. Test with fresh data
71 
72### Emergency Recovery
73- All destructive operations create emergency backups
74- Use `make restore` to recover from any backup
75- Emergency backups are automatically created in `backups/` directory
76 
77## Production Deployment Workflow
78 
79### Production Build
80```bash
81# Build and start production environment
82make prod         # Starts production containers
83 
84# Production utilities
85make logs         # Monitor production logs
86make backup       # Create production backup
87make clean        # Clean up resources (with confirmations)
88```
89 
90### Production Database Management
91- Use same `make backup` and `make restore` commands
92- Emergency backups created before any destructive operations
93- All operations require explicit confirmations
94 
95## Safety Features
96 
97### Multiple Confirmation Layers
98All potentially destructive operations require specific confirmations:
99- `make remove-data` requires typing "DELETE ALL DATA"
100- `make restore` requires typing "RESTORE"  
101- `make clean` requires typing "YES"
102 
103### Automatic Backups
104- Emergency backups created before destructive operations
105- Backup rotation (keeps last 10 backups)
106- Comprehensive backup manifests with metadata
107- Multiple backup formats (SQL, tar.gz, complete bundles)
108 
109### Container Health Checking
110- All database operations verify container is running
111- Automatic fallback between dev/prod container names
112- Clear error messages with resolution suggestions
113 
114## Advanced Development Features
115 
116### Testing and Quality
117```bash
118make test         # Run all tests
119make lint         # Run linting checks
120make format       # Format code
121make deps         # Update dependencies
122```
123 
124### System Monitoring
125```bash
126make status       # Comprehensive system status
127make logs         # Real-time log monitoring
128```
129 
130### Cleanup and Maintenance
131```bash
132make clean        # Remove unused Docker resources
133make rebuild      # Force rebuild all images
134make restart      # Restart all services
135```
136 
137## Helper Scripts Reference
138 
139### Script Locations
140All helper scripts are in [scripts/](mdc:scripts/) directory:
141 
142- **[create-admin.sh](mdc:scripts/create-admin.sh)** - Interactive admin user creation
143- **[backup.sh](mdc:scripts/backup.sh)** - Complete system backup
144- **[restore.sh](mdc:scripts/restore.sh)** - Interactive backup restoration  
145- **[remove-data.sh](mdc:scripts/remove-data.sh)** - Safe data removal
146- **[db-reset.sh](mdc:scripts/db-reset.sh)** - Database reset with verification
147 
148### Script Features
149- **Colored Output** - Clear visual feedback with status indicators
150- **Input Validation** - Prevents invalid operations
151- **Error Handling** - Comprehensive error checking and recovery
152- **Safety Confirmations** - Multiple confirmation layers for safety
153- **Progress Reporting** - Step-by-step operation feedback
154 
155## Integration with Development Tools
156 
157### File Organization
158- **Makefile Commands** - Organized by category with clear descriptions
159- **Docker Integration** - Seamless container management
160- **Environment Management** - Automatic `.env` file creation
161- **Backup Management** - Automated backup rotation and cleanup
162 
163### IDE Integration
164- All commands work from terminal in any IDE
165- Makefile provides tab completion for commands
166- Scripts provide clear error messages and next steps
167- Comprehensive help system with `make help`
168 
169## Best Practices
170 
171### Development Session
1721. **Always start with** `make status` to check current state
1732. **Use** `make backup` before major changes
1743. **Monitor with** `make logs` during development
1754. **Clean up with** `make down` when finished
176 
177### Database Work
1781. **Create backups** before schema changes
1792. **Use** `make db-reset` for clean testing environment  
1803. **Verify changes** with `make status`
1814. **Keep emergency backups** for safety
182 
183### Production Deployment
1841. **Always backup** production before changes
1852. **Test locally** with `make prod`
1863. **Monitor deployment** with `make logs`
1874. **Verify functionality** with `make status`
188 
189## Troubleshooting
190 
191### Common Issues
1921. **"Container not running"** - Run `make up` or `make dev`
1932. **"Permission denied"** - Ensure Docker Desktop is running
1943. **"Port conflicts"** - Check ports 3000, 8080, 5432 are available
1954. **"Database errors"** - Try `make db-reset` for fresh start
196 
197### Recovery Steps
1981. Check system status: `make status`
1992. View logs: `make logs`
2003. Restart services: `make restart`
2014. Reset database: `make db-reset`
2025. Restore backup: `make restore`