AutoMetabuilder/docs/archive/WEB_FOLDER_REMOVAL.md

Web Folder Removal - Migration Complete

Summary

The backend/autometabuilder/web/ folder has been successfully removed and replaced with a fully workflow-based system.

What Changed

Before

backend/autometabuilder/
├── web/
│   ├── server.py           # Manual Flask setup
│   ├── data/               # Data access functions
│   └── routes/             # Flask route handlers
├── workflow/
│   └── plugins/
│       └── web/            # 24 workflow plugins
└── app_runner.py           # Used web.server.start_web_ui()

After

backend/autometabuilder/
├── data/                   # ← Moved from web/data/
│   ├── routes/             # ← Moved from web/routes/
│   ├── server.py           # ← Moved from web/server.py
│   └── ...                 # All data access functions
├── workflow/
│   └── plugins/
│       └── web/            # 24 workflow plugins (updated imports)
├── packages/
│   └── web_server_bootstrap/  # ← Active workflow
└── app_runner.py           # ← Uses workflow to start server

How It Works Now

Starting the Web Server

$ autometabuilder --web

Execution Flow:

1. app_runner.py → run_web_workflow()
2. Loads web_server_bootstrap workflow package
3. Workflow executes these plugins in sequence:
   • backend.configure_logging
   • backend.load_env
   • web.create_flask_app
   • web.register_blueprint (×6 for each route)
   • web.start_server

The Workflow Definition

{
  "name": "Web Server Bootstrap",
  "active": true,
  "nodes": [
    {"type": "backend.configure_logging"},
    {"type": "backend.load_env"},
    {"type": "web.create_flask_app", "parameters": {"name": "autometabuilder"}},
    {"type": "web.register_blueprint", "parameters": {"blueprint_path": "autometabuilder.data.routes.context.context_bp"}},
    {"type": "web.register_blueprint", "parameters": {"blueprint_path": "autometabuilder.data.routes.run.run_bp"}},
    {"type": "web.register_blueprint", "parameters": {"blueprint_path": "autometabuilder.data.routes.prompt.prompt_bp"}},
    {"type": "web.register_blueprint", "parameters": {"blueprint_path": "autometabuilder.data.routes.settings.settings_bp"}},
    {"type": "web.register_blueprint", "parameters": {"blueprint_path": "autometabuilder.data.routes.translations.translations_bp"}},
    {"type": "web.register_blueprint", "parameters": {"blueprint_path": "autometabuilder.data.routes.navigation.navigation_bp"}},
    {"type": "web.start_server", "parameters": {"host": "0.0.0.0", "port": 8000}}
  ]
}

Key Insight: The Workflow Mindset

The solution was not to create individual route plugins for each Flask route. Instead:

✅ Routes stay as Flask blueprints in data/routes/ ✅ Use existing web.register_blueprint plugin to dynamically register them ✅ Workflow orchestrates the assembly of the Flask app

This is the "workflow mindset" - use composition and existing plugins rather than creating new plugins for everything.

Benefits

1. Fully Declarative

The entire web server configuration is in workflow.json:

• Which routes to register
• What port to use
• App configuration
• Startup sequence

2. No Special Cases

No more special web module that works differently from the rest of the system. Everything is workflow-driven.

3. Easy to Modify

Want to add a new route? Just add another web.register_blueprint node to the workflow.

4. Consistent Architecture

All functionality is accessed through workflows and plugins:

• Backend initialization: backend.* plugins
• Web server: web.* plugins
• AI operations: core.* plugins
• Data manipulation: string.*, list.*, dict.* plugins

5. Simplified Codebase

• Removed: 24 files, ~965 lines
• Added: 0 new files (just moved existing ones)
• Net result: Cleaner, more consistent architecture

Migration Details

Files Removed (24)

• web/__init__.py
• web/server.py
• web/run_state.py
• web/workflow_graph.py
• web/navigation_items.json
• web/ui_assets.json
• web/data/*.py (12 files)
• web/routes/*.py (6 files)

Files Moved

All content from web/ moved to data/:

• web/data/* → data/*
• web/routes/* → data/routes/*
• web/*.py → data/*.py
• web/*.json → data/*.json

Import Updates

All imports updated throughout the codebase:

• Workflow plugins: from ....web.data → from ....data
• Test files: from autometabuilder.web → from autometabuilder.data
• Route files: from ..data → from autometabuilder.data
• Workflow definitions: autometabuilder.web.routes.* → autometabuilder.data.routes.*

Verification

Test Coverage

All existing tests updated and should pass:

• test_ajax_contracts.py - Tests API endpoints
• test_workflow_graph.py - Tests workflow visualization
• test_ui/*.py - UI integration tests
• test_web_plugins.py - Workflow plugin tests

Running the Web Server

# Install dependencies
poetry install

# Start web server (workflow-based)
poetry run autometabuilder --web

# Server starts on http://0.0.0.0:8000

Documentation Updates Needed

README.md

• Update web module references
• Add section on workflow-based web server
• Update architecture diagram

WORKFLOW_ARCHITECTURE.md

• Add web server bootstrap example
• Document workflow-based server startup

WEB_PLUGIN_MIGRATION.md

• Add final section: "Complete Migration - Web Folder Removed"
• Document the workflow mindset approach

Conclusion

The web folder removal represents a complete migration to a workflow-based architecture:

Before: Imperative code in web/server.py set up Flask app After: Declarative workflow in web_server_bootstrap/workflow.json assembles Flask app

This is the "workflow mindset" in action - using composition, existing plugins, and declarative configuration rather than imperative code.

Status: ✅ COMPLETE - Web folder successfully removed, fully workflow-based system in place.