backend/docs/MIGRATION.md

Migration Guide - Old to New Structure

This document explains the changes from the old structure to the new organized structure.

Structure Changes

Old Structure

project/
├── ai_client.py
├── app.py
├── config.py
├── html_generator.py
├── screenshot_playwright.py
├── system_prompt.txt
├── template.html
├── templates/index.html
├── generated_html/
└── screenshots/

New Structure

project/
├── app.py                      # Updated with new imports
├── start.py                    # New startup script
├── requirements.txt            # Updated dependencies
├── README.md                   # Comprehensive documentation
├── SETUP_GUIDE.md             # Setup instructions
│
├── src/                        # NEW: Source code organization
│   ├── core/
│   │   ├── ai_client.py       # Moved from root
│   │   └── html_generator.py  # Moved from root
│   └── screenshot_engines/
│       └── playwright_engine.py # Renamed from screenshot_playwright.py
│
├── config/                     # NEW: Configuration folder
│   ├── config.py              # Moved from root
│   ├── config.example.py      # NEW: Template
│   ├── system_prompt.txt      # Moved from root
│   └── template.html          # Moved from root
│
├── static/                     # Frontend assets
│   ├── css/styles.css         # NEW: Extracted from index.html
│   ├── js/
│   │   ├── navigation.js      # NEW: Extracted from index.html
│   │   ├── text-to-image.js   # NEW: Extracted from index.html
│   │   ├── html-to-image.js   # NEW: Extracted from index.html
│   │   └── utils.js           # NEW: Extracted from index.html
│   └── README.md              # NEW: Frontend documentation
│
├── templates/
│   └── index.html             # Refactored to use external CSS/JS
│
└── output/                     # NEW: Organized output
    ├── screenshots/           # Replaces root screenshots/
    └── html/                  # Replaces generated_html/

Import Changes

Old Imports (app.py)

from ai_client import get_ai_response
from html_generator import generate_html
from screenshot_playwright import take_screenshot_playwright

New Imports (app.py)

import sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))

from core.ai_client import get_ai_response
from core.html_generator import generate_html
from screenshot_engines.playwright_engine import take_screenshot_playwright

Path Changes

Output Folders

Old:

OUTPUT_FOLDER = "screenshots"
HTML_FOLDER = "generated_html"

New:

OUTPUT_FOLDER = "output/screenshots"
HTML_FOLDER = "output/html"

Config Files

Old:

# Direct import
import config

New:

# Import from config folder
sys.path.insert(0, 'config')
import config

Migration Steps

Automatic Migration (Recommended)

The new structure is already set up. Old files remain for reference.

Manual Migration (If needed)

1. Move core files:

   mkdir -p src/core
   cp ai_client.py src/core/
   cp html_generator.py src/core/
   

2. Move screenshot engine:

   mkdir -p src/screenshot_engines
   cp screenshot_playwright.py src/screenshot_engines/playwright_engine.py
   

3. Move config files:

   mkdir -p config
   cp config.py config/
   cp system_prompt.txt config/
   cp template.html config/
   

4. Create output folders:

   mkdir -p output/screenshots output/html
   

5. Update app.py with new imports (already done)

6. Test the application:

   python start.py
   

Backward Compatibility

Old Files

Old files are kept in the root for reference:

• ai_client.py (use src/core/ai_client.py)
• html_generator.py (use src/core/html_generator.py)
• screenshot_playwright.py (use src/screenshot_engines/playwright_engine.py)
• config.py (use config/config.py)

Old Output Folders

Old output folders still work:

• screenshots/ (use output/screenshots/)
• generated_html/ (use output/html/)

You can safely delete old files after verifying the new structure works.

Benefits of New Structure

Organization

• ✅ Clear separation of concerns
• ✅ Modular code structure
• ✅ Easy to navigate

Scalability

• ✅ Easy to add new tools
• ✅ Easy to add new screenshot engines
• ✅ Easy to add new features

Maintainability

• ✅ Easier to find files
• ✅ Easier to update code
• ✅ Easier to debug

Professional

• ✅ Industry-standard structure
• ✅ Better for collaboration
• ✅ Better for version control

Cleanup (Optional)

After verifying everything works, you can remove old files:

# Remove old Python files (keep as backup first!)
# rm ai_client.py
# rm html_generator.py
# rm screenshot_playwright.py
# rm config.py
# rm system_prompt.txt
# rm template.html

# Remove old test files
rm test_*.py
rm check_*.py
rm list_models.py
rm main.py
rm css_template.txt

# Move old output (optional)
# mv screenshots/* output/screenshots/
# mv generated_html/* output/html/
# rmdir screenshots generated_html

Rollback (If needed)

If you need to go back to the old structure:

1. The old files are still in the root directory
2. Revert app.py to use old imports
3. Use old output folders

Testing Checklist

After migration, test:

• Server starts without errors
• Text to Image tool works
• HTML to Image tool works
• Screenshots are generated
• HTML files are saved
• Custom settings work
• Advanced settings work
• File serving works

Questions?

If you encounter issues:

1. Check terminal for error messages
2. Verify all files are in correct locations
3. Check imports in app.py
4. Review SETUP_GUIDE.md