I've successfully reorganized your TutorBot project structure to improve clarity and maintainability. All shell scripts are now organized in a dedicated scripts/ folder, and Docker documentation is in a docker/ folder.
/home/stephen/projects/tutorbot/
├── main.py # Core Flask application (delegates to modules)
├── requirements.txt # Python dependencies
├── docker-compose.yml # Docker configuration (stays in root)
├── Dockerfile # Docker image (stays in root)
├── .env # Environment variables
├── env_example.txt # Environment template
├── help.sh # Help script (stays in root for easy access)
├── test_prefill_overview.py # Test prefill functionality
├── show_prefill_overview.py # Show prefill overview
├── modules/ # 🆕 MODULAR ARCHITECTURE
│ ├── __init__.py
│ ├── core/ # Core configuration
│ │ ├── __init__.py
│ │ └── config.py # Centralized configuration
│ ├── handlers/ # Business logic handlers
│ │ ├── __init__.py
│ │ ├── conversation.py # Message handling
│ │ ├── intake.py # Prefill and intake flows
│ │ ├── menu.py # Menu systems
│ │ ├── payment.py # Payment processing
│ │ ├── planning.py # Lesson planning
│ │ └── contact.py # Contact management
│ ├── utils/ # Utility functions
│ │ ├── __init__.py
│ │ ├── cw_api.py # Chatwoot API wrapper
│ │ ├── text_helpers.py # Text and messaging utilities
│ │ ├── language.py # Language detection
│ │ ├── mapping.py # Data mapping utilities
│ │ ├── menu_guard.py # Menu selection validation
│ │ └── attribute_manager.py # Attribute management
│ ├── routes/ # Flask route handlers
│ │ ├── __init__.py
│ │ ├── health.py # Health check endpoints
│ │ ├── webhook.py # Chatwoot webhook routes
│ │ └── stripe.py # Stripe webhook routes
│ └── integrations/ # External service integrations
│ ├── __init__.py
│ ├── openai_service.py # OpenAI API integration
│ └── calendar_integration.py # Google Calendar API
├── config/ # Configuration files
│ ├── contact_attributes.yaml
│ ├── conversation_attributes.yaml
│ ├── labels_lean.yaml
│ └── automations.yaml
├── scripts/ # 🆕 ALL SHELL SCRIPTS
│ ├── README.md # Scripts documentation
│ ├── dev.sh # Development shortcuts
│ ├── wipe.sh # Quick contact wipe
│ ├── wipe_all.sh # Quick data wipe
│ ├── debug_toggle.sh # Main debug toggle script
│ ├── debug_on.sh # Enable debug mode
│ ├── debug_off.sh # Disable debug mode
│ ├── debug_private.sh # Enable private debug mode
│ ├── debug_console.sh # Enable console debug mode
│ ├── debug_status.sh # Show debug status
│ ├── confirm_toggle.sh # Main confirmation toggle script
│ ├── confirm_on.sh # Enable confirmation mode
│ ├── confirm_off.sh # Disable confirmation mode
│ ├── confirm_status.sh # Show confirmation status
│ ├── export_env.sh # Export environment variables (in dev/)
│ ├── setup_attributes.py # Setup custom attributes
│ ├── setup_labels.py # Setup labels
│ ├── setup_all.py # Setup everything
│ ├── setup_automation_rules.py
│ ├── setup_chatwoot.py # Setup Chatwoot configuration
│ ├── wipe_contacts.py # Manual contact wipe
│ ├── wipe_all.py # Manual data wipe
│ ├── cleanup_all.py # Clean up all data
│ ├── validate_structure.py # Validate project structure
│ ├── audit_attributes.py # Audit custom attributes
│ ├── analyze_logs.py # Analyze log files
│ ├── check_inboxes.py # Check inbox status
│ ├── list_contact_languages.py
│ ├── list_automation.py # List automation rules
│ ├── test_real_message.py # Test with real message
│ ├── test_real_conversation.py
│ ├── test_bot.py # Test bot functionality
│ ├── test_chatwoot_api.py # Test Chatwoot API
│ └── test_input_select.py # Test input selection
├── docker/ # 🆕 DOCKER DOCUMENTATION
│ └── README.md # Docker setup and usage
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_main.py # Main test suite
│ ├── test_config.py # Test configuration
│ └── README.md # Test documentation
├── docs/ # Documentation
│ └── README_chatwoot_setup.md
├── run_tests.py # Test runner
├── test_setup.py # Test environment setup
└── TEST_SUITE_SUMMARY.md # Test suite summary
scripts/ folderscripts/README.mdmodules/handlers/ foldermodules/utils/ foldermodules/routes/ foldermodules/integrations/ foldermodules/core/config.pydocker/README.md# Old commands (still work with aliases)
debug
confirm
wipe
exportenv
# New organized commands
./scripts/debug_toggle.sh
./scripts/confirm_toggle.sh
./scripts/wipe.sh
./scripts/dev/export_env.sh
# Scripts documentation
cat scripts/README.md
# Docker documentation
cat docker/README.md
# Help system
./help.sh
dev.sh - Development environment managementwipe.sh - Quick contact wipewipe_all.sh - Quick data wipedebug_toggle.sh - Main debug toggle (multiple modes)debug_on.sh - Enable debug modedebug_off.sh - Disable debug modedebug_private.sh - Enable private debug modedebug_console.sh - Enable console debug modedebug_status.sh - Show debug statusconfirm_toggle.sh - Main confirmation toggleconfirm_on.sh - Enable confirmation modeconfirm_off.sh - Disable confirmation modeconfirm_status.sh - Show confirmation statusexport_env.sh - Export environment variables# Check debug status
./scripts/debug_toggle.sh status
# Enable debug mode
./scripts/debug_toggle.sh on
# Enable private debug mode
./scripts/debug_toggle.sh private
# Quick toggle
./scripts/debug_toggle.sh
# Check confirmation status
./scripts/confirm_toggle.sh status
# Enable confirmation mode
./scripts/confirm_toggle.sh on
# Quick toggle
./scripts/confirm_toggle.sh
# Wipe contacts
./scripts/wipe.sh
# Wipe all data
./scripts/wipe_all.sh
# Export environment variables
source ./scripts/dev/export_env.sh
# Or use the script directly
./scripts/dev/export_env.sh
docker-compose.yml must be in root for docker-compose commandsDockerfile is expected in root or build contextdocker/README.md contains comprehensive Docker documentationscripts/ folderscripts/The TutorBot project now has a clean, organized structure that makes it easy to:
The organization follows best practices for project structure while maintaining backward compatibility with existing aliases and workflows.
Your TutorBot project is now enterprise-ready with professional organization and comprehensive documentation! 🎯