backend/scripts/README.md

Scripts Directory

This directory contains utility scripts for development, testing, deployment, and maintenance of the Atom platform.

Directory Structure

scripts/
├── dev/              # Development, testing, and debugging scripts
├── production/       # Production deployment and maintenance scripts
├── legacy/           # Obsolete or archived scripts (kept for reference)
├── README.md         # This file
└── [scripts]         # General utility scripts (to be categorized)

Script Categories

Development Scripts (dev/)

Scripts used during development for testing, debugging, and feature development:

• Test Scripts: test_*.py, *_test.py, e2e_*.py
• Demo Scripts: demo_*.py, showcase_*.py
• Debug Scripts: debug_*.py, diagnose_*.py
• Feature Development: *_implementation.py, *_phase*.py
• Utilities: Development helpers, data generators, mock data creators

Examples:

• test_workspace_permissions.py - Run permission tests
• debug_governance.py - Debug governance system
• demo_canvas_features.py - Showcase canvas capabilities

Production Scripts (production/)

Scripts used in production environments for deployment and maintenance:

• Deployment: deploy_*.py, production_*.py
• Database: Migrations, seeders, backups
• Monitoring: Health checks, metrics collection
• Maintenance: Cleanup, optimization, verification

Examples:

• deploy_production.py - Deploy to production
• seed_admin_user.py - Create initial admin user
• verify_integrations.py - Check integration health

Legacy Scripts (legacy/)

Obsolete or deprecated scripts kept for reference:

• Old Implementations: Superseded by new code
• Deprecated Features: Features no longer supported
• Historical Reference: For understanding past implementations

Note: Scripts in legacy/ should NOT be used in production. They are kept only for reference.

General Guidelines

Adding New Scripts

1. Choose the right category:

   • Development/debugging → dev/
   • Production deployment → production/
   • Utility scripts → Root (to be categorized later)

2. Name descriptively:

   • ✅ deploy_production.py
   • ✅ test_governance_permissions.py
   • ❌ script1.py
   • ❌ temp.py

3. Add docstring:

   """
   Script description.
   
   Usage:
       python script_name.py [args]
   
   Args:
       arg1: Description
   
   Examples:
       python script_name.py --arg1 value
   """
   

4. Make executable (if needed):

   chmod +x scripts/production/deploy.sh
   

Removing Scripts

Before deleting a script, verify:

1. ✅ Not referenced in production code
2. ✅ Not used in CI/CD pipelines
3. ✅ Not documented in user guides
4. ✅ No active GitHub issues reference it

If unsure, move to legacy/ instead of deleting.

Migration Status

Last Updated: February 2, 2026

Total Scripts: ~285

• ✅ Categorized: 160 scripts organized
  • dev/: 91 scripts
  • production/: 39 scripts
  • legacy/: 17 scripts
  • utils/: 13 scripts
• 🔄 Remaining in root: 125 scripts (to be categorized)
• ❌ Obsolete: ~50 (in legacy/)

Recent Changes:

• Moved all final_*.py assessment scripts to legacy/
• Moved dev_*.py diagnostic scripts to utils/
• Moved test_*.py, demo_*.py, debug_*.py to dev/
• Moved init_*.py initialization scripts to utils/
• Moved deployment scripts to production/

Common Operations

List all scripts

ls scripts/

Find test scripts

ls scripts/dev/test_*.py

Run a production deployment

python scripts/production/deploy.py --env production

Search for scripts by keyword

ls scripts/ | grep -i oauth

Maintenance

Weekly Tasks

• Review root directory for uncategorized scripts
• Move completed feature scripts to dev/
• Archive obsolete scripts to legacy/

Monthly Tasks

• Audit legacy/ for scripts safe to delete
• Update README with new scripts
• Test production deployment scripts

Related Documentation

• docs/DEPLOYMENT.md - Deployment procedures
• docs/DEVELOPMENT.md - Development setup
• IMPLEMENTATION_COMPLETION_REPORT.md - Recent changes

---

Last Updated: February 1, 2026 Status: Reorganization in progress