CGW-Quote-Builder/app/admin/README.md

Admin Utilities

This folder contains administrative tools and utilities for maintaining the CGW Product Finder application.

🛠️ Available Tools

fix_default_locations.py

Purpose: Ensures all users have their default location marked as accessible.

Usage:

cd app/admin
python fix_default_locations.py

What it does:

• Scans all users in data/users.json
• Checks if each user's default location is marked as accessible
• Automatically fixes any users where the default location is not accessible
• Reports results for each user

When to use:

• After manual edits to users.json
• After importing users from backup
• If users report they can't access their default location
• As a maintenance check

test_password_security.py

Purpose: Demonstrates and tests the password hashing security implementation.

Usage:

cd app/admin
python test_password_security.py

What it does:

• Demonstrates PBKDF2-SHA256 password hashing
• Shows security features (iterations, salt, etc.)
• Verifies password verification works correctly
• Useful for understanding the security implementation

When to use:

• To verify password hashing is working correctly
• To demonstrate security to stakeholders
• For educational purposes
• When troubleshooting password-related issues

📋 Running Admin Tools

All admin tools should be run from within the app/admin directory to ensure correct file paths.

Example:

# Navigate to admin folder
cd "C:\Users\Work\Desktop\CGW Product Finder\app\admin"

# Run a tool
python fix_default_locations.py

⚠️ Important Notes

• Backup First: Always backup data/users.json before running utilities that modify data
• Test Environment: Test utilities in a development environment before running in production
• File Paths: These tools assume they're being run from the app/admin directory
• Python Version: Requires Python 3.7 or higher

🔒 Security Considerations

• These tools have direct access to user data
• Do not expose these tools to web-facing directories
• Keep this folder secure with appropriate file permissions
• Never commit sensitive user data to version control

📝 Adding New Admin Tools

When adding new administrative tools to this folder:

1. Add the Python script file
2. Update this README with documentation
3. Include clear usage instructions
4. Document any data modifications it makes
5. Include error handling and user feedback

🐛 Troubleshooting

"File not found" errors:

• Ensure you're running from the app/admin directory
• Check that ../data/users.json exists

Permission denied:

• Ensure the application is not running
• Check file permissions on data/users.json

Import errors:

• Ensure all required dependencies are installed: pip install -r ../requirements.txt
• Verify Python version: python --version