# IvoryOS major refactoring summary

This document summarizes the major architectural changes and refactorings implemented.

## Dissolving the monolithic `utils/` directory

The `ivoryos/utils/` directory has been broken apart into logical, domain-specific packages to enforce a cleaner separation of concerns:

- `ivoryos/core/`: system-level abstractions such as `module_loader.py` and `return_handlers.py`.
- `ivoryos/forms/`: UI form generation and WTForms logic such as `dynamic_forms.py`.
- `ivoryos/models/`: database models such as `base.py`, `execution.py`, `script.py`, `user.py`, and `workflow.py`.
- `ivoryos/parsers/`: data serialization, JSON parsing, and type conversions.
- `ivoryos/runtime/`: execution orchestration, control flows, and queue management such as `script_runner.py` and `task_runner.py`.
- `ivoryos/services/`: standalone backend services such as `llm_agent.py`, `draft_service.py`, and `client_proxy.py`.

## Real-time Socket.IO synchronization

Legacy HTTP polling through `GET /status` and `GET /queue` has been replaced with an event-driven Socket.IO architecture.

- Real-time events such as `busy_status`, `queue_status`, and `pause_status` are managed centrally in `ivoryos/socket_handlers.py`.
- Frontend synchronization is handled through `window.platformState` in `socket_handler.js`, reducing server overhead and UI latency.

## Codebase cleanup

- Community examples were removed from the core package area because they were primarily publication-oriented and not intended for core reproducibility.
- Integration and unit tests in `tests/` were updated to reflect the package-based import structure.