---
description: Development workflow automation and best practices for POS System
---

# Development Workflow Guide

## Quick Start Commands

### Primary Development Workflow
Use [Makefile](mdc:Makefile) for all development operations:

```bash
# Essential commands for daily development
make help         # Show all available commands
make dev          # Start development environment with hot reloading
make up           # Start Docker containers in background
make down         # Stop all containers
make status       # Check system status
```

### Database Management Workflow
```bash
# Database operations (all interactive and safe)
make create-admin # Create super admin user
make backup       # Backup entire system (database + files)
make restore      # Restore from backup (interactive menu)
make db-reset     # Reset to fresh state with seed data
make db-shell     # Access PostgreSQL shell
make remove-data  # DESTRUCTIVE: Remove all data (multiple confirmations)
```

## Development Environment Setup

### First Time Setup
1. Clone repository and navigate to project root
2. Ensure Docker Desktop is running
3. Run `make dev` - automatically creates `.env` file if missing
4. Access applications:
   - Frontend: http://localhost:3000
   - Backend API: http://localhost:8080
   - Database: localhost:5432

### Daily Development Workflow
```bash
# Start development session
make dev          # Starts all services with hot reloading

# During development
make logs         # View all service logs
make logs-backend # View only backend logs
make logs-frontend# View only frontend logs

# End development session
make down         # Stop all containers
```

## Database Development Workflow

### Working with Database
1. **Fresh Start**: `make db-reset` - Clean database with seed data
2. **Backup Before Changes**: `make backup` - Create safety backup
3. **Make Changes**: Edit schema files or use application
4. **Test Changes**: Verify functionality
5. **Create Admin**: `make create-admin` - Add admin users as needed

### Database Schema Changes
1. Edit [database/init/01_schema.sql](mdc:database/init/01_schema.sql)
2. Edit [database/init/02_seed_data.sql](mdc:database/init/02_seed_data.sql) if needed
3. Run `make db-reset` to apply changes
4. Test with fresh data

### Emergency Recovery
- All destructive operations create emergency backups
- Use `make restore` to recover from any backup
- Emergency backups are automatically created in `backups/` directory

## Production Deployment Workflow

### Production Build
```bash
# Build and start production environment
make prod         # Starts production containers

# Production utilities
make logs         # Monitor production logs
make backup       # Create production backup
make clean        # Clean up resources (with confirmations)
```

### Production Database Management
- Use same `make backup` and `make restore` commands
- Emergency backups created before any destructive operations
- All operations require explicit confirmations

## Safety Features

### Multiple Confirmation Layers
All potentially destructive operations require specific confirmations:
- `make remove-data` requires typing "DELETE ALL DATA"
- `make restore` requires typing "RESTORE"  
- `make clean` requires typing "YES"

### Automatic Backups
- Emergency backups created before destructive operations
- Backup rotation (keeps last 10 backups)
- Comprehensive backup manifests with metadata
- Multiple backup formats (SQL, tar.gz, complete bundles)

### Container Health Checking
- All database operations verify container is running
- Automatic fallback between dev/prod container names
- Clear error messages with resolution suggestions

## Advanced Development Features

### Testing and Quality
```bash
make test         # Run all tests
make lint         # Run linting checks
make format       # Format code
make deps         # Update dependencies
```

### System Monitoring
```bash
make status       # Comprehensive system status
make logs         # Real-time log monitoring
```

### Cleanup and Maintenance
```bash
make clean        # Remove unused Docker resources
make rebuild      # Force rebuild all images
make restart      # Restart all services
```

## Helper Scripts Reference

### Script Locations
All helper scripts are in [scripts/](mdc:scripts/) directory:

- **[create-admin.sh](mdc:scripts/create-admin.sh)** - Interactive admin user creation
- **[backup.sh](mdc:scripts/backup.sh)** - Complete system backup
- **[restore.sh](mdc:scripts/restore.sh)** - Interactive backup restoration  
- **[remove-data.sh](mdc:scripts/remove-data.sh)** - Safe data removal
- **[db-reset.sh](mdc:scripts/db-reset.sh)** - Database reset with verification

### Script Features
- **Colored Output** - Clear visual feedback with status indicators
- **Input Validation** - Prevents invalid operations
- **Error Handling** - Comprehensive error checking and recovery
- **Safety Confirmations** - Multiple confirmation layers for safety
- **Progress Reporting** - Step-by-step operation feedback

## Integration with Development Tools

### File Organization
- **Makefile Commands** - Organized by category with clear descriptions
- **Docker Integration** - Seamless container management
- **Environment Management** - Automatic `.env` file creation
- **Backup Management** - Automated backup rotation and cleanup

### IDE Integration
- All commands work from terminal in any IDE
- Makefile provides tab completion for commands
- Scripts provide clear error messages and next steps
- Comprehensive help system with `make help`

## Best Practices

### Development Session
1. **Always start with** `make status` to check current state
2. **Use** `make backup` before major changes
3. **Monitor with** `make logs` during development
4. **Clean up with** `make down` when finished

### Database Work
1. **Create backups** before schema changes
2. **Use** `make db-reset` for clean testing environment  
3. **Verify changes** with `make status`
4. **Keep emergency backups** for safety

### Production Deployment
1. **Always backup** production before changes
2. **Test locally** with `make prod`
3. **Monitor deployment** with `make logs`
4. **Verify functionality** with `make status`

## Troubleshooting

### Common Issues
1. **"Container not running"** - Run `make up` or `make dev`
2. **"Permission denied"** - Ensure Docker Desktop is running
3. **"Port conflicts"** - Check ports 3000, 8080, 5432 are available
4. **"Database errors"** - Try `make db-reset` for fresh start

### Recovery Steps
1. Check system status: `make status`
2. View logs: `make logs`
3. Restart services: `make restart`
4. Reset database: `make db-reset`
5. Restore backup: `make restore`