ss-tools/specs/project_map.md

# Project Semantic Map

> Compressed view for AI Context. Generated automatically.

- 📦 **generate_semantic_map** (`Module`)
  - 📝 Scans the codebase to generate a Semantic Map and Compliance Report based on the System Standard.
  - 🏗️ Layer: DevOps/Tooling
  - ℂ **SemanticEntity** (`Class`)
    - 📝 Represents a code entity (Module, Function, Component) found during parsing.
    - ƒ **to_dict** (`Function`)
      - 📝 Serializes the entity to a dictionary for JSON output.
    - ƒ **validate** (`Function`)
      - 📝 Checks for semantic compliance (closure, mandatory tags).
    - ƒ **get_score** (`Function`)
      - 📝 Calculates a compliance score (0.0 to 1.0).
  - ƒ **get_patterns** (`Function`)
    - 📝 Returns regex patterns for a specific language.
  - ƒ **parse_file** (`Function`)
    - 📝 Parses a single file to extract semantic entities.
  - ℂ **SemanticMapGenerator** (`Class`)
    - 📝 Orchestrates the mapping process.
    - ƒ **run** (`Function`)
      - 📝 Main execution flow.
      - 🔗 CALLS -> `_walk_and_parse`
      - 🔗 CALLS -> `_generate_artifacts`
    - ƒ **_walk_and_parse** (`Function`)
      - 📝 Recursively walks directories and triggers parsing.
    - ƒ **_process_file_results** (`Function`)
      - 📝 Validates entities and calculates file scores.
    - ƒ **_generate_artifacts** (`Function`)
      - 📝 Writes output files.
    - ƒ **_generate_report** (`Function`)
      - 📝 Generates the Markdown compliance report.
    - ƒ **_collect_issues** (`Function`)
      - 📝 Helper to collect issues for a specific file from the entity tree.
    - ƒ **_generate_compressed_map** (`Function`)
      - 📝 Generates the token-optimized project map.
    - ƒ **_write_entity_md** (`Function`)
      - 📝 Recursive helper to write entity tree to Markdown.
- 📦 **search_script** (`Module`)
  - 📝 Предоставляет утилиты для поиска по текстовым паттернам в метаданных датасетов Superset.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - ƒ **search_datasets** (`Function`)
    - 📝 Выполняет поиск по строковому паттерну в метаданных всех датасетов.
    - 🔗 CALLS -> `client.get_datasets`
  - ƒ **save_results_to_file** (`Function`)
    - 📝 Сохраняет результаты поиска в текстовый файл.
  - ƒ **print_search_results** (`Function`)
    - 📝 Форматирует результаты поиска для читаемого вывода в консоль.
  - ƒ **main** (`Function`)
    - 📝 Основная точка входа для запуска скрипта поиска.
    - 🔗 CALLS -> `setup_clients`
    - 🔗 CALLS -> `search_datasets`
    - 🔗 CALLS -> `print_search_results`
    - 🔗 CALLS -> `save_results_to_file`
- 📦 **get_dataset_structure** (`Module`)
  - 📝 Этот модуль предназначен для получения и сохранения структуры данных датасета из Superset. Он используется для отладки и анализа данных, возвращаемых API.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `superset_tool.utils.init_clients`
  - 🔗 DEPENDS_ON -> `superset_tool.utils.logger`
  - ƒ **get_and_save_dataset** (`Function`)
    - 📝 Получает структуру датасета из Superset и сохраняет ее в JSON-файл.
    - 🔗 CALLS -> `setup_clients`
    - 🔗 CALLS -> `superset_client.get_dataset`
- 📦 **debug_db_api** (`Module`)
  - 📝 Скрипт для отладки структуры ответа API баз данных.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - ƒ **debug_database_api** (`Function`)
    - 📝 Отладка структуры ответа API баз данных.
    - 🔗 CALLS -> `setup_clients`
    - 🔗 CALLS -> `client.get_databases`
- 📦 **run_mapper** (`Module`)
  - 📝 Этот модуль является CLI-точкой входа для запуска процесса меппинга метаданных датасетов.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.utils.dataset_mapper`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - ƒ **main** (`Function`)
    - 📝 Парсит аргументы командной строки и запускает процесс меппинга.
    - 🔗 CALLS -> `setup_clients`
    - 🔗 CALLS -> `DatasetMapper.run_mapping`
- 📦 **migration_script** (`Module`)
  - 📝 Предоставляет интерактивный CLI для миграции дашбордов Superset между окружениями с возможностью восстановления после ошибок.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - ℂ **Migration** (`Class`)
    - 📝 Инкапсулирует логику интерактивной миграции дашбордов с возможностью «удалить‑и‑перезаписать» при ошибке импорта.
    - ƒ **Migration.__init__** (`Function`)
      - 📝 Инициализирует сервис миграции, настраивает логгер и начальные состояния.
    - ƒ **Migration.run** (`Function`)
      - 📝 Точка входа – последовательный запуск всех шагов миграции.
      - 🔗 CALLS -> `self.ask_delete_on_failure`
      - 🔗 CALLS -> `self.select_environments`
      - 🔗 CALLS -> `self.select_dashboards`
      - 🔗 CALLS -> `self.confirm_db_config_replacement`
      - 🔗 CALLS -> `self.execute_migration`
    - ƒ **Migration.ask_delete_on_failure** (`Function`)
      - 📝 Запрашивает у пользователя, следует ли удалять дашборд при ошибке импорта.
      - 🔗 CALLS -> `yesno`
    - ƒ **Migration.select_environments** (`Function`)
      - 📝 Позволяет пользователю выбрать исходное и целевое окружения Superset.
      - 🔗 CALLS -> `setup_clients`
      - 🔗 CALLS -> `menu`
    - ƒ **Migration.select_dashboards** (`Function`)
      - 📝 Позволяет пользователю выбрать набор дашбордов для миграции.
      - 🔗 CALLS -> `self.from_c.get_dashboards`
      - 🔗 CALLS -> `checklist`
    - ƒ **Migration.confirm_db_config_replacement** (`Function`)
      - 📝 Запрашивает у пользователя, требуется ли заменить имена БД в YAML-файлах.
      - 🔗 CALLS -> `yesno`
      - 🔗 CALLS -> `self._select_databases`
    - ƒ **Migration._select_databases** (`Function`)
      - 📝 Позволяет пользователю выбрать исходную и целевую БД через API.
      - 🔗 CALLS -> `self.from_c.get_databases`
      - 🔗 CALLS -> `self.to_c.get_databases`
      - 🔗 CALLS -> `self.from_c.get_database`
      - 🔗 CALLS -> `self.to_c.get_database`
      - 🔗 CALLS -> `menu`
    - ƒ **Migration._batch_delete_by_ids** (`Function`)
      - 📝 Удаляет набор дашбордов по их ID единым запросом.
      - 🔗 CALLS -> `self.to_c.network.request`
    - ƒ **Migration.execute_migration** (`Function`)
      - 📝 Выполняет экспорт-импорт дашбордов, обрабатывает ошибки и, при необходимости, выполняет процедуру восстановления.
      - 🔗 CALLS -> `self.from_c.export_dashboard`
      - 🔗 CALLS -> `create_temp_file`
      - 🔗 CALLS -> `update_yamls`
      - 🔗 CALLS -> `create_dashboard_export`
      - 🔗 CALLS -> `self.to_c.import_dashboard`
      - 🔗 CALLS -> `self._batch_delete_by_ids`
- 📦 **backup_script** (`Module`)
  - 📝 Этот модуль отвечает за автоматизированное резервное копирование дашбордов Superset.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - 📦 **BackupConfig** (`DataClass`)
    - 📝 Хранит конфигурацию для процесса бэкапа.
  - ƒ **backup_dashboards** (`Function`)
    - 📝 Выполняет бэкап всех доступных дашбордов для заданного клиента и окружения, пропуская ошибки экспорта.
    - 🔗 CALLS -> `client.get_dashboards`
    - 🔗 CALLS -> `client.export_dashboard`
    - 🔗 CALLS -> `save_and_unpack_dashboard`
    - 🔗 CALLS -> `archive_exports`
    - 🔗 CALLS -> `consolidate_archive_folders`
    - 🔗 CALLS -> `remove_empty_directories`
  - ƒ **main** (`Function`)
    - 📝 Основная точка входа для запуска процесса резервного копирования.
    - 🔗 CALLS -> `setup_clients`
    - 🔗 CALLS -> `backup_dashboards`
- 📦 **superset_tool.exceptions** (`Module`)
  - 📝 Определяет иерархию пользовательских исключений для всего инструмента, обеспечивая единую точку обработки ошибок.
  - 🏗️ Layer: Infra
  - ℂ **SupersetToolError** (`Class`)
    - 📝 Базовый класс для всех ошибок, генерируемых инструментом.
    - 🔗 INHERITS_FROM -> `Exception`
  - ℂ **AuthenticationError** (`Class`)
    - 📝 Ошибки, связанные с аутентификацией или авторизацией.
    - 🔗 INHERITS_FROM -> `SupersetToolError`
  - ℂ **PermissionDeniedError** (`Class`)
    - 📝 Ошибка, возникающая при отказе в доступе к ресурсу.
    - 🔗 INHERITS_FROM -> `AuthenticationError`
  - ℂ **SupersetAPIError** (`Class`)
    - 📝 Общие ошибки при взаимодействии с Superset API.
    - 🔗 INHERITS_FROM -> `SupersetToolError`
  - ℂ **ExportError** (`Class`)
    - 📝 Ошибки, специфичные для операций экспорта.
    - 🔗 INHERITS_FROM -> `SupersetAPIError`
  - ℂ **DashboardNotFoundError** (`Class`)
    - 📝 Ошибка, когда запрошенный дашборд или ресурс не найден (404).
    - 🔗 INHERITS_FROM -> `SupersetAPIError`
  - ℂ **DatasetNotFoundError** (`Class`)
    - 📝 Ошибка, когда запрашиваемый набор данных не существует (404).
    - 🔗 INHERITS_FROM -> `SupersetAPIError`
  - ℂ **InvalidZipFormatError** (`Class`)
    - 📝 Ошибка, указывающая на некорректный формат или содержимое ZIP-архива.
    - 🔗 INHERITS_FROM -> `SupersetToolError`
  - ℂ **NetworkError** (`Class`)
    - 📝 Ошибки, связанные с сетевым соединением.
    - 🔗 INHERITS_FROM -> `SupersetToolError`
  - ℂ **FileOperationError** (`Class`)
    - 📝 Общие ошибки файловых операций (I/O).
    - 🔗 INHERITS_FROM -> `SupersetToolError`
  - ℂ **InvalidFileStructureError** (`Class`)
    - 📝 Ошибка, указывающая на некорректную структуру файлов или директорий.
    - 🔗 INHERITS_FROM -> `FileOperationError`
  - ℂ **ConfigurationError** (`Class`)
    - 📝 Ошибки, связанные с неверной конфигурацией инструмента.
    - 🔗 INHERITS_FROM -> `SupersetToolError`
- 📦 **superset_tool** (`Module`)
  - 📝 Root package for superset_tool.
  - 🏗️ Layer: Domain
- 📦 **superset_tool.client** (`Module`)
  - 📝 Предоставляет высокоуровневый клиент для взаимодействия с Superset REST API, инкапсулируя логику запросов, обработку ошибок и пагинацию.
  - 🏗️ Layer: Domain
  - 🔗 DEPENDS_ON -> `superset_tool.models`
  - 🔗 DEPENDS_ON -> `superset_tool.exceptions`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - ℂ **SupersetClient** (`Class`)
    - 📝 Класс-обёртка над Superset REST API, предоставляющий методы для работы с дашбордами и датасетами.
    - ƒ **SupersetClient.__init__** (`Function`)
      - 📝 Инициализирует клиент, проверяет конфигурацию и создает сетевой клиент.
    - ƒ **SupersetClient._validate_config** (`Function`)
      - 📝 Проверяет, что переданный объект конфигурации имеет корректный тип.
    - ƒ **SupersetClient.headers** (`Function`)
      - 📝 Возвращает базовые HTTP-заголовки, используемые сетевым клиентом.
    - ƒ **SupersetClient.get_dashboards** (`Function`)
      - 📝 Получает полный список дашбордов, автоматически обрабатывая пагинацию.
      - 🔗 CALLS -> `self._fetch_total_object_count`
      - 🔗 CALLS -> `self._fetch_all_pages`
    - ƒ **SupersetClient.export_dashboard** (`Function`)
      - 📝 Экспортирует дашборд в виде ZIP-архива.
      - 🔗 CALLS -> `self.network.request`
    - ƒ **SupersetClient.import_dashboard** (`Function`)
      - 📝 Импортирует дашборд из ZIP-файла с возможностью автоматического удаления и повторной попытки при ошибке.
      - 🔗 CALLS -> `self._do_import`
      - 🔗 CALLS -> `self.delete_dashboard`
      - 🔗 CALLS -> `self.get_dashboards`
    - ƒ **SupersetClient._resolve_target_id_for_delete** (`Function`)
      - 📝 Определяет ID дашборда для удаления, используя ID или slug.
    - ƒ **SupersetClient._do_import** (`Function`)
      - 📝 Выполняет один запрос на импорт без обработки исключений.
    - ƒ **SupersetClient.delete_dashboard** (`Function`)
      - 📝 Удаляет дашборд по его ID или slug.
      - 🔗 CALLS -> `self.network.request`
    - ƒ **SupersetClient._extract_dashboard_id_from_zip** (`Function`)
      - 📝 Извлекает ID дашборда из `metadata.yaml` внутри ZIP-архива.
    - ƒ **SupersetClient._extract_dashboard_slug_from_zip** (`Function`)
      - 📝 Извлекает slug дашборда из `metadata.yaml` внутри ZIP-архива.
    - ƒ **SupersetClient._validate_export_response** (`Function`)
      - 📝 Проверяет, что HTTP-ответ на экспорт является валидным ZIP-архивом.
    - ƒ **SupersetClient._resolve_export_filename** (`Function`)
      - 📝 Определяет имя файла для экспорта из заголовков или генерирует его.
    - ƒ **SupersetClient._validate_query_params** (`Function`)
      - 📝 Формирует корректный набор параметров запроса с пагинацией.
    - ƒ **SupersetClient._fetch_total_object_count** (`Function`)
      - 📝 Получает общее количество объектов по указанному эндпоинту для пагинации.
    - ƒ **SupersetClient._fetch_all_pages** (`Function`)
      - 📝 Итерируется по всем страницам пагинированного API и собирает все данные.
    - ƒ **SupersetClient._validate_import_file** (`Function`)
      - 📝 Проверяет, что файл существует, является ZIP-архивом и содержит `metadata.yaml`.
    - ƒ **SupersetClient.get_datasets** (`Function`)
      - 📝 Получает полный список датасетов, автоматически обрабатывая пагинацию.
      - 🔗 CALLS -> `self._fetch_total_object_count`
      - 🔗 CALLS -> `self._fetch_all_pages`
    - ƒ **SupersetClient.get_databases** (`Function`)
      - 📝 Получает полный список баз данных, автоматически обрабатывая пагинацию.
      - 🔗 CALLS -> `self._fetch_total_object_count`
      - 🔗 CALLS -> `self._fetch_all_pages`
    - ƒ **SupersetClient.get_dataset** (`Function`)
      - 📝 Получает информацию о конкретном датасете по его ID.
      - 🔗 CALLS -> `self.network.request`
    - ƒ **SupersetClient.get_database** (`Function`)
      - 📝 Получает информацию о конкретной базе данных по её ID.
      - 🔗 CALLS -> `self.network.request`
    - ƒ **SupersetClient.update_dataset** (`Function`)
      - 📝 Обновляет данные датасета по его ID.
      - 🔗 CALLS -> `self.network.request`
- 📦 **superset_tool.models** (`Module`)
  - 📝 Определяет Pydantic-модели для конфигурации инструмента, обеспечивая валидацию данных.
  - 🏗️ Layer: Infra
  - 🔗 DEPENDS_ON -> `pydantic`
  - 🔗 DEPENDS_ON -> `superset_tool.utils.logger`
  - ℂ **SupersetConfig** (`Class`)
    - 📝 Модель конфигурации для подключения к одному экземпляру Superset API.
    - 🔗 INHERITS_FROM -> `pydantic.BaseModel`
    - ƒ **SupersetConfig.validate_auth** (`Function`)
      - 📝 Проверяет, что словарь `auth` содержит все необходимые для аутентификации поля.
    - ƒ **SupersetConfig.normalize_base_url** (`Function`)
      - 📝 Нормализует `base_url`, добавляя `/api/v1`, если он отсутствует.
  - ℂ **DatabaseConfig** (`Class`)
    - 📝 Модель для параметров трансформации баз данных при миграции дашбордов.
    - 🔗 INHERITS_FROM -> `pydantic.BaseModel`
    - ƒ **DatabaseConfig.validate_config** (`Function`)
      - 📝 Проверяет, что словарь `database_config` содержит ключи 'old' и 'new'.
- 📦 **superset_tool.utils.logger** (`Module`)
  - 📝 Предоставляет универсальную обёртку над стандартным `logging.Logger` для унифицированного создания и управления логгерами с выводом в консоль и/или файл.
  - 🏗️ Layer: Infra
  - ℂ **SupersetLogger** (`Class`)
    - 📝 Обёртка над `logging.Logger`, которая упрощает конфигурацию и использование логгеров.
    - ƒ **SupersetLogger.__init__** (`Function`)
      - 📝 Конфигурирует и инициализирует логгер, добавляя обработчики для файла и/или консоли.
    - ƒ **SupersetLogger._log** (`Function`)
      - 📝 (Helper) Универсальный метод для вызова соответствующего уровня логирования.
    - ƒ **SupersetLogger.info** (`Function`)
      - 📝 Записывает сообщение уровня INFO.
    - ƒ **SupersetLogger.debug** (`Function`)
      - 📝 Записывает сообщение уровня DEBUG.
    - ƒ **SupersetLogger.warning** (`Function`)
      - 📝 Записывает сообщение уровня WARNING.
    - ƒ **SupersetLogger.error** (`Function`)
      - 📝 Записывает сообщение уровня ERROR.
    - ƒ **SupersetLogger.critical** (`Function`)
      - 📝 Записывает сообщение уровня CRITICAL.
    - ƒ **SupersetLogger.exception** (`Function`)
      - 📝 Записывает сообщение уровня ERROR вместе с трассировкой стека текущего исключения.
- 📦 **superset_tool.utils.network** (`Module`)
  - 📝 Инкапсулирует низкоуровневую HTTP-логику для взаимодействия с Superset API, включая аутентификацию, управление сессией, retry-логику и обработку ошибок.
  - 🏗️ Layer: Infra
  - 🔗 DEPENDS_ON -> `superset_tool.exceptions`
  - 🔗 DEPENDS_ON -> `superset_tool.utils.logger`
  - 🔗 DEPENDS_ON -> `requests`
  - ℂ **APIClient** (`Class`)
    - 📝 Инкапсулирует HTTP-логику для работы с API, включая сессии, аутентификацию, и обработку запросов.
    - ƒ **APIClient.__init__** (`Function`)
      - 📝 Инициализирует API клиент с конфигурацией, сессией и логгером.
    - ƒ **APIClient._init_session** (`Function`)
      - 📝 Создает и настраивает `requests.Session` с retry-логикой.
    - ƒ **APIClient.authenticate** (`Function`)
      - 📝 Выполняет аутентификацию в Superset API и получает access и CSRF токены.
    - ƒ **APIClient.headers** (`Function`)
      - 📝 Возвращает HTTP-заголовки для аутентифицированных запросов.
    - ƒ **APIClient.request** (`Function`)
      - 📝 Выполняет универсальный HTTP-запрос к API.
    - ƒ **APIClient._handle_http_error** (`Function`)
      - 📝 (Helper) Преобразует HTTP ошибки в кастомные исключения.
    - ƒ **APIClient._handle_network_error** (`Function`)
      - 📝 (Helper) Преобразует сетевые ошибки в `NetworkError`.
    - ƒ **APIClient.upload_file** (`Function`)
      - 📝 Загружает файл на сервер через multipart/form-data.
    - ƒ **APIClient._perform_upload** (`Function`)
      - 📝 (Helper) Выполняет POST запрос с файлом.
    - ƒ **APIClient.fetch_paginated_count** (`Function`)
      - 📝 Получает общее количество элементов для пагинации.
    - ƒ **APIClient.fetch_paginated_data** (`Function`)
      - 📝 Автоматически собирает данные со всех страниц пагинированного эндпоинта.
- 📦 **superset_tool.utils.whiptail_fallback** (`Module`)
  - 📝 Предоставляет плотный консольный UI-fallback для интерактивных диалогов, имитируя `whiptail` для систем, где он недоступен.
  - 🏗️ Layer: UI
  - ƒ **menu** (`Function`)
    - 📝 Отображает меню выбора и возвращает выбранный элемент.
  - ƒ **checklist** (`Function`)
    - 📝 Отображает список с возможностью множественного выбора.
  - ƒ **yesno** (`Function`)
    - 📝 Задает вопрос с ответом да/нет.
  - ƒ **msgbox** (`Function`)
    - 📝 Отображает информационное сообщение.
  - ƒ **inputbox** (`Function`)
    - 📝 Запрашивает у пользователя текстовый ввод.
  - ℂ **_ConsoleGauge** (`Class`)
    - 📝 Контекстный менеджер для имитации `whiptail gauge` в консоли.
  - ƒ **gauge** (`Function`)
    - 📝 Создает и возвращает экземпляр `_ConsoleGauge`.
- 📦 **superset_tool.utils.dataset_mapper** (`Module`)
  - 📝 Этот модуль отвечает за обновление метаданных (verbose_map) в датасетах Superset, извлекая их из PostgreSQL или XLSX-файлов.
  - 🏗️ Layer: Domain
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `pandas`
  - 🔗 DEPENDS_ON -> `psycopg2`
  - ℂ **DatasetMapper** (`Class`)
    - 📝 Класс для меппинга и обновления verbose_map в датасетах Superset.
    - ƒ **DatasetMapper.get_postgres_comments** (`Function`)
      - 📝 Извлекает комментарии к колонкам из системного каталога PostgreSQL.
    - ƒ **DatasetMapper.load_excel_mappings** (`Function`)
      - 📝 Загружает меппинги 'column_name' -> 'column_comment' из XLSX файла.
    - ƒ **DatasetMapper.run_mapping** (`Function`)
      - 📝 Основная функция для выполнения меппинга и обновления verbose_map датасета в Superset.
      - 🔗 CALLS -> `self.get_postgres_comments`
      - 🔗 CALLS -> `self.load_excel_mappings`
      - 🔗 CALLS -> `superset_client.get_dataset`
      - 🔗 CALLS -> `superset_client.update_dataset`
- 📦 **superset_tool.utils** (`Module`)
  - 📝 Utility package for superset_tool.
  - 🏗️ Layer: Infra
- 📦 **superset_tool.utils.init_clients** (`Module`)
  - 📝 Централизованно инициализирует клиенты Superset для различных окружений (DEV, PROD, SBX, PREPROD), используя `keyring` для безопасного доступа к паролям.
  - 🏗️ Layer: Infra
  - 🔗 DEPENDS_ON -> `superset_tool.models`
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `keyring`
  - ƒ **setup_clients** (`Function`)
    - 📝 Инициализирует и возвращает словарь клиентов `SupersetClient`.
- 📦 **superset_tool.utils.fileio** (`Module`)
  - 📝 Предоставляет набор утилит для управления файловыми операциями, включая работу с временными файлами, архивами ZIP, файлами YAML и очистку директорий.
  - 🏗️ Layer: Infra
  - 🔗 DEPENDS_ON -> `superset_tool.exceptions`
  - 🔗 DEPENDS_ON -> `superset_tool.utils.logger`
  - 🔗 DEPENDS_ON -> `pyyaml`
  - ƒ **create_temp_file** (`Function`)
    - 📝 Контекстный менеджер для создания временного файла или директории с гарантированным удалением.
  - ƒ **remove_empty_directories** (`Function`)
    - 📝 Рекурсивно удаляет все пустые поддиректории, начиная с указанного пути.
  - ƒ **read_dashboard_from_disk** (`Function`)
    - 📝 Читает бинарное содержимое файла с диска.
  - ƒ **calculate_crc32** (`Function`)
    - 📝 Вычисляет контрольную сумму CRC32 для файла.
  - 📦 **RetentionPolicy** (`DataClass`)
    - 📝 Определяет политику хранения для архивов (ежедневные, еженедельные, ежемесячные).
  - ƒ **archive_exports** (`Function`)
    - 📝 Управляет архивом экспортированных файлов, применяя политику хранения и дедупликацию.
    - 🔗 CALLS -> `apply_retention_policy`
    - 🔗 CALLS -> `calculate_crc32`
  - ƒ **apply_retention_policy** (`Function`)
    - 📝 (Helper) Применяет политику хранения к списку файлов, возвращая те, что нужно сохранить.
  - ƒ **save_and_unpack_dashboard** (`Function`)
    - 📝 Сохраняет бинарное содержимое ZIP-архива на диск и опционально распаковывает его.
  - ƒ **update_yamls** (`Function`)
    - 📝 Обновляет конфигурации в YAML-файлах, заменяя значения или применяя regex.
    - 🔗 CALLS -> `_update_yaml_file`
  - ƒ **_update_yaml_file** (`Function`)
    - 📝 (Helper) Обновляет один YAML файл.
  - ƒ **create_dashboard_export** (`Function`)
    - 📝 Создает ZIP-архив из указанных исходных путей.
  - ƒ **sanitize_filename** (`Function`)
    - 📝 Очищает строку от символов, недопустимых в именах файлов.
  - ƒ **get_filename_from_headers** (`Function`)
    - 📝 Извлекает имя файла из HTTP заголовка 'Content-Disposition'.
  - ƒ **consolidate_archive_folders** (`Function`)
    - 📝 Консолидирует директории архивов на основе общего слага в имени.
- 🧩 **App** (`Component`)
  - 📝 The root component of the frontend application. Manages navigation and layout.
  - 🏗️ Layer: UI
  - ƒ **handleFormSubmit** (`Function`)
    - 📝 Handles form submission for task creation.
  - ƒ **navigate** (`Function`)
    - 📝 Changes the current page and resets state.
- 📦 **main** (`Module`)
  - 📝 Entry point for the Svelte application.
  - 🏗️ Layer: UI-Entry
  - 📦 **app_instance** (`Data`)
    - 📝 Initialized Svelte app instance.
- 🧩 **DashboardGrid** (`Component`)
  - 📝 Displays a grid of dashboards with selection and pagination.
  - 🏗️ Layer: Component
  - ƒ **handleSort** (`Function`)
    - 📝 Toggles sort direction or changes sort column.
  - ƒ **handleSelectionChange** (`Function`)
    - 📝 Handles individual checkbox changes.
  - ƒ **handleSelectAll** (`Function`)
    - 📝 Handles select all checkbox.
  - ƒ **goToPage** (`Function`)
    - 📝 Changes current page.
- 🧩 **TaskHistory** (`Component`)
  - 📝 Displays a list of recent tasks with their status and allows selecting them for viewing logs.
  - 🏗️ Layer: UI
  - ƒ **fetchTasks** (`Function`)
    - 📝 Fetches the list of recent tasks from the API.
  - ƒ **clearTasks** (`Function`)
    - 📝 Clears tasks from the history, optionally filtered by status.
  - ƒ **selectTask** (`Function`)
    - 📝 Selects a task and fetches its full details.
  - ƒ **getStatusColor** (`Function`)
    - 📝 Returns the CSS color class for a given task status.
  - ƒ **onMount** (`Function`)
    - 📝 Initializes the component by fetching tasks and starting polling.
  - ƒ **onDestroy** (`Function`)
    - 📝 Cleans up the polling interval when the component is destroyed.
- 🧩 **MappingTable** (`Component`)
  - 📝 Displays and allows editing of database mappings.
  - 🏗️ Layer: Feature
  - ƒ **updateMapping** (`Function`)
    - 📝 Updates a mapping for a specific source database.
  - ƒ **getSuggestion** (`Function`)
    - 📝 Finds a suggestion for a source database.
- 🧩 **EnvSelector** (`Component`)
  - 📝 Provides a UI component for selecting source and target environments.
  - 🏗️ Layer: Feature
  - ƒ **handleSelect** (`Function`)
    - 📝 Dispatches the selection change event.
- 🧩 **TaskList** (`Component`)
  - 📝 Displays a list of tasks with their status and execution details.
  - 🏗️ Layer: Component
  - ƒ **getStatusColor** (`Function`)
    - 📝 Returns the CSS color class for a given task status.
  - ƒ **formatTime** (`Function`)
    - 📝 Formats a date string using date-fns.
  - ƒ **handleTaskClick** (`Function`)
    - 📝 Dispatches a select event when a task is clicked.
- 🧩 **DynamicForm** (`Component`)
  - 📝 Generates a form dynamically based on a JSON schema.
  - 🏗️ Layer: UI
  - ƒ **handleSubmit** (`Function`)
    - 📝 Dispatches the submit event with the form data.
  - ƒ **initializeForm** (`Function`)
    - 📝 Initialize form data with default values from the schema.
- 🧩 **Footer** (`Component`)
  - 📝 Displays the application footer with copyright information.
  - 🏗️ Layer: UI
- 🧩 **Navbar** (`Component`)
  - 📝 Main navigation bar for the application.
  - 🏗️ Layer: UI
- 🧩 **TaskRunner** (`Component`)
  - 📝 Connects to a WebSocket to display real-time logs for a running task.
  - 🏗️ Layer: UI
  - ƒ **connect** (`Function`)
    - 📝 Establishes WebSocket connection with exponential backoff.
  - ƒ **fetchTargetDatabases** (`Function`)
    - 📝 Fetches the list of databases in the target environment.
  - ƒ **handleMappingResolve** (`Function`)
    - 📝 Handles the resolution of a missing database mapping.
  - ƒ **handlePasswordResume** (`Function`)
    - 📝 Handles the submission of database passwords to resume a task.
  - ƒ **startDataTimeout** (`Function`)
    - 📝 Starts a timeout to detect when the log stream has stalled.
  - ƒ **resetDataTimeout** (`Function`)
    - 📝 Resets the data stall timeout.
  - ƒ **onMount** (`Function`)
    - 📝 Initializes the component and subscribes to task selection changes.
  - ƒ **onDestroy** (`Function`)
    - 📝 Close WebSocket connection when the component is destroyed.
- 🧩 **TaskLogViewer** (`Component`)
  - 📝 Displays detailed logs for a specific task in a modal.
  - 🏗️ Layer: UI
  - ƒ **fetchLogs** (`Function`)
    - 📝 Fetches logs for the current task.
  - ƒ **scrollToBottom** (`Function`)
    - 📝 Scrolls the log container to the bottom.
  - ƒ **handleScroll** (`Function`)
    - 📝 Updates auto-scroll preference based on scroll position.
  - ƒ **close** (`Function`)
    - 📝 Closes the log viewer modal.
  - ƒ **getLogLevelColor** (`Function`)
    - 📝 Returns the CSS color class for a given log level.
  - ƒ **onDestroy** (`Function`)
    - 📝 Cleans up the polling interval.
- 🧩 **PasswordPrompt** (`Component`)
  - 📝 A modal component to prompt the user for database passwords when a migration task is paused.
  - 🏗️ Layer: UI
  - ƒ **handleSubmit** (`Function`)
    - 📝 Validates and dispatches the passwords to resume the task.
  - ƒ **handleCancel** (`Function`)
    - 📝 Cancels the password prompt.
- 🧩 **MissingMappingModal** (`Component`)
  - 📝 Prompts the user to provide a database mapping when one is missing during migration.
  - 🏗️ Layer: Feature
  - ƒ **resolve** (`Function`)
    - 📝 Dispatches the resolution event with the selected mapping.
  - ƒ **cancel** (`Function`)
    - 📝 Cancels the mapping resolution modal.
- 🧩 **Toast** (`Component`)
  - 📝 Displays transient notifications (toasts) in the bottom-right corner.
  - 🏗️ Layer: UI
- 🧩 **Settings** (`Component`)
  - 📝 The main settings page for the application, allowing management of environments and global settings.
  - 🏗️ Layer: UI
  - ƒ **loadSettings** (`Function`)
    - 📝 Loads settings from the backend.
  - ƒ **handleSaveGlobal** (`Function`)
    - 📝 Saves global settings to the backend.
  - ƒ **handleAddOrUpdateEnv** (`Function`)
    - 📝 Adds or updates an environment.
  - ƒ **handleDeleteEnv** (`Function`)
    - 📝 Deletes an environment.
  - ƒ **handleTestEnv** (`Function`)
    - 📝 Tests the connection to an environment.
  - ƒ **editEnv** (`Function`)
    - 📝 Sets the form to edit an existing environment.
  - ƒ **resetEnvForm** (`Function`)
    - 📝 Resets the environment form.
- 🧩 **Dashboard** (`Component`)
  - 📝 Displays the list of available plugins and allows selecting one.
  - 🏗️ Layer: UI
  - ƒ **onMount** (`Function`)
    - 📝 Fetch plugins when the component mounts.
  - ƒ **selectPlugin** (`Function`)
    - 📝 Selects a plugin to display its form.
- 📦 **stores_module** (`Module`)
  - 📝 Global state management using Svelte stores.
  - 🏗️ Layer: UI-State
  - 📦 **plugins** (`Data`)
    - 📝 Store for the list of available plugins.
  - 📦 **tasks** (`Data`)
    - 📝 Store for the list of tasks.
  - 📦 **selectedPlugin** (`Data`)
    - 📝 Store for the currently selected plugin.
  - 📦 **selectedTask** (`Data`)
    - 📝 Store for the currently selected task.
  - 📦 **currentPage** (`Data`)
    - 📝 Store for the current page.
  - 📦 **taskLogs** (`Data`)
    - 📝 Store for the logs of the currently selected task.
  - ƒ **fetchPlugins** (`Function`)
    - 📝 Fetches plugins from the API and updates the plugins store.
  - ƒ **fetchTasks** (`Function`)
    - 📝 Fetches tasks from the API and updates the tasks store.
- 📦 **toasts_module** (`Module`)
  - 📝 Manages toast notifications using a Svelte writable store.
  - 🏗️ Layer: UI-State
  - 📦 **toasts** (`Data`)
    - 📝 Writable store containing the list of active toasts.
  - ƒ **addToast** (`Function`)
    - 📝 Adds a new toast message.
  - ƒ **removeToast** (`Function`)
    - 📝 Removes a toast message by ID.
- 📦 **api_module** (`Module`)
  - 📝 Handles all communication with the backend API.
  - 🏗️ Layer: Infra-API
  - ƒ **getWsUrl** (`Function`)
    - 📝 Returns the WebSocket URL for a specific task, with fallback logic.
  - ƒ **fetchApi** (`Function`)
    - 📝 Generic GET request wrapper.
  - ƒ **postApi** (`Function`)
    - 📝 Generic POST request wrapper.
  - ƒ **requestApi** (`Function`)
    - 📝 Generic request wrapper.
  - 📦 **api** (`Data`)
    - 📝 API client object with specific methods.
- 🧩 **MigrationDashboard** (`Component`)
  - 📝 Main dashboard for configuring and starting migrations.
  - 🏗️ Layer: Page
  - ƒ **fetchEnvironments** (`Function`)
    - 📝 Fetches the list of environments from the API.
  - ƒ **fetchDashboards** (`Function`)
    - 📝 Fetches dashboards for the selected source environment.
  - ƒ **fetchDatabases** (`Function`)
    - 📝 Fetches databases from both environments and gets suggestions.
  - ƒ **handleMappingUpdate** (`Function`)
    - 📝 Saves a mapping to the backend.
  - ƒ **handleViewLogs** (`Function`)
    - 📝 Opens the log viewer for a specific task.
  - ƒ **handlePasswordPrompt** (`Function`)
    - 📝 Reactive logic to show password prompt when a task is awaiting input.
  - ƒ **handleResumeMigration** (`Function`)
    - 📝 Resumes a migration task with provided passwords.
  - ƒ **startMigration** (`Function`)
    - 📝 Starts the migration process.
- 🧩 **MappingManagement** (`Component`)
  - 📝 Page for managing database mappings between environments.
  - 🏗️ Layer: Page
  - ƒ **fetchEnvironments** (`Function`)
    - 📝 Fetches the list of environments.
  - ƒ **fetchDatabases** (`Function`)
    - 📝 Fetches databases from both environments and gets suggestions.
  - ƒ **handleUpdate** (`Function`)
    - 📝 Saves a mapping to the backend.
- 📦 **Dependencies** (`Module`)
  - 📝 Manages the creation and provision of shared application dependencies, such as the PluginLoader and TaskManager, to avoid circular imports.
  - 🏗️ Layer: Core
- 📦 **AppModule** (`Module`)
  - 📝 The main entry point for the FastAPI application. It initializes the app, configures CORS, sets up dependencies, includes API routers, and defines the WebSocket endpoint for log streaming.
  - 🏗️ Layer: UI (API)
  - 📦 **App** (`Global`)
    - 📝 The global FastAPI application instance.
  - 📦 **WebSocketEndpoint** (`Endpoint`)
    - 📝 Provides a WebSocket endpoint for clients to connect to and receive real-time log entries for a specific task.
  - 📦 **StaticFiles** (`Mount`)
    - 📝 Mounts the frontend build directory to serve static assets.
    - 📦 **RootEndpoint** (`Endpoint`)
      - 📝 A simple root endpoint to confirm that the API is running.
- 📦 **backend.src.models.mapping** (`Module`)
  - 📝 Defines the database schema for environment metadata and database mappings using SQLAlchemy.
  - 🏗️ Layer: Domain
  - 🔗 DEPENDS_ON -> `sqlalchemy`
  - ℂ **MigrationStatus** (`Class`)
    - 📝 Enumeration of possible migration job statuses.
  - ℂ **Environment** (`Class`)
    - 📝 Represents a Superset instance environment.
  - ℂ **DatabaseMapping** (`Class`)
    - 📝 Represents a mapping between source and target databases.
  - ℂ **MigrationJob** (`Class`)
    - 📝 Represents a single migration execution job.
- 📦 **backend.src.models.dashboard** (`Module`)
  - 📝 Defines data models for dashboard metadata and selection.
  - 🏗️ Layer: Model
  - ℂ **DashboardMetadata** (`Class`)
    - 📝 Represents a dashboard available for migration.
  - ℂ **DashboardSelection** (`Class`)
    - 📝 Represents the user's selection of dashboards to migrate.
- 📦 **backend.src.models.task** (`Module`)
  - 📝 Defines the database schema for task execution records.
  - 🏗️ Layer: Domain
  - 🔗 DEPENDS_ON -> `sqlalchemy`
  - ℂ **TaskRecord** (`Class`)
    - 📝 Represents a persistent record of a task execution.
- 📦 **backend.src.services.mapping_service** (`Module`)
  - 📝 Orchestrates database fetching and fuzzy matching suggestions.
  - 🏗️ Layer: Service
  - 🔗 DEPENDS_ON -> `backend.src.core.superset_client`
  - 🔗 DEPENDS_ON -> `backend.src.core.utils.matching`
  - ℂ **MappingService** (`Class`)
    - 📝 Service for handling database mapping logic.
    - ƒ **MappingService.__init__** (`Function`)
      - 📝 Initializes the mapping service with a config manager.
    - ƒ **MappingService._get_client** (`Function`)
      - 📝 Helper to get an initialized SupersetClient for an environment.
    - ƒ **MappingService.get_suggestions** (`Function`)
      - 📝 Fetches databases from both environments and returns fuzzy matching suggestions.
- 📦 **ConfigManagerModule** (`Module`)
  - 📝 Manages application configuration, including loading/saving to JSON and CRUD for environments.
  - 🏗️ Layer: Core
  - 🔗 DEPENDS_ON -> `ConfigModels`
  - 🔗 CALLS -> `logger`
  - ℂ **ConfigManager** (`Class`)
    - 📝 A class to handle application configuration persistence and management.
    - ƒ **__init__** (`Function`)
      - 📝 Initializes the ConfigManager.
    - ƒ **_load_config** (`Function`)
      - 📝 Loads the configuration from disk or creates a default one.
    - ƒ **_save_config_to_disk** (`Function`)
      - 📝 Saves the provided configuration object to disk.
    - ƒ **save** (`Function`)
      - 📝 Saves the current configuration state to disk.
    - ƒ **get_config** (`Function`)
      - 📝 Returns the current configuration.
    - ƒ **update_global_settings** (`Function`)
      - 📝 Updates the global settings and persists the change.
    - ƒ **validate_path** (`Function`)
      - 📝 Validates if a path exists and is writable.
    - ƒ **get_environments** (`Function`)
      - 📝 Returns the list of configured environments.
    - ƒ **has_environments** (`Function`)
      - 📝 Checks if at least one environment is configured.
    - ƒ **add_environment** (`Function`)
      - 📝 Adds a new environment to the configuration.
    - ƒ **update_environment** (`Function`)
      - 📝 Updates an existing environment.
    - ƒ **delete_environment** (`Function`)
      - 📝 Deletes an environment by ID.
- 📦 **backend.src.core.superset_client** (`Module`)
  - 📝 Extends the base SupersetClient with database-specific metadata fetching.
  - 🏗️ Layer: Core
  - 🔗 INHERITS_FROM -> `superset_tool.client.SupersetClient`
  - ℂ **SupersetClient** (`Class`)
    - 📝 Extended SupersetClient for migration-specific operations.
    - ƒ **SupersetClient.get_databases_summary** (`Function`)
      - 📝 Fetch a summary of databases including uuid, name, and engine.
    - ƒ **SupersetClient.get_database_by_uuid** (`Function`)
      - 📝 Find a database by its UUID.
    - ƒ **SupersetClient.get_dashboards_summary** (`Function`)
      - 📝 Fetches dashboard metadata optimized for the grid.
- 📦 **backend.src.core.migration_engine** (`Module`)
  - 📝 Handles the interception and transformation of Superset asset ZIP archives.
  - 🏗️ Layer: Core
  - 🔗 DEPENDS_ON -> `PyYAML`
  - ℂ **MigrationEngine** (`Class`)
    - 📝 Engine for transforming Superset export ZIPs.
    - ƒ **MigrationEngine.transform_zip** (`Function`)
      - 📝 Extracts ZIP, replaces database UUIDs in YAMLs, and re-packages.
    - ƒ **MigrationEngine._transform_yaml** (`Function`)
      - 📝 Replaces database_uuid in a single YAML file.
- 📦 **LoggerModule** (`Module`)
  - 📝 Configures the application's logging system, including a custom handler for buffering logs and streaming them over WebSockets.
  - 🏗️ Layer: Core
  - ℂ **BeliefFormatter** (`Class`)
    - 📝 Custom logging formatter that adds belief state prefixes to log messages.
  - ℂ **LogEntry** (`Class`)
    - 📝 A Pydantic model representing a single, structured log entry. This is a re-definition for consistency, as it's also defined in task_manager.py.
  - ƒ **BeliefScope** (`Function`)
    - 📝 Context manager for structured Belief State logging.
  - ƒ **ConfigureLogger** (`Function`)
    - 📝 Configures the logger with the provided logging settings.
  - ℂ **WebSocketLogHandler** (`Class`)
    - 📝 A custom logging handler that captures log records into a buffer. It is designed to be extended for real-time log streaming over WebSockets.
  - 📦 **Logger** (`Global`)
    - 📝 The global logger instance for the application, configured with both a console handler and the custom WebSocket handler.
- 📦 **backend.src.core.database** (`Module`)
  - 📝 Configures the SQLite database connection and session management.
  - 🏗️ Layer: Core
  - 🔗 DEPENDS_ON -> `sqlalchemy`
  - 📦 **DATABASE_URL** (`Constant`)
  - 📦 **TASKS_DATABASE_URL** (`Constant`)
  - 📦 **engine** (`Variable`)
  - 📦 **tasks_engine** (`Variable`)
  - ℂ **SessionLocal** (`Class`)
    - 📝 A session factory for the main mappings database.
  - ℂ **TasksSessionLocal** (`Class`)
    - 📝 A session factory for the tasks execution database.
  - ƒ **init_db** (`Function`)
    - 📝 Initializes the database by creating all tables.
  - ƒ **get_db** (`Function`)
    - 📝 Dependency for getting a database session.
  - ƒ **get_tasks_db** (`Function`)
    - 📝 Dependency for getting a tasks database session.
- 📦 **ConfigModels** (`Module`)
  - 📝 Defines the data models for application configuration using Pydantic.
  - 🏗️ Layer: Core
  - 📦 **Schedule** (`DataClass`)
    - 📝 Represents a backup schedule configuration.
  - 📦 **Environment** (`DataClass`)
    - 📝 Represents a Superset environment configuration.
  - 📦 **LoggingConfig** (`DataClass`)
    - 📝 Defines the configuration for the application's logging system.
  - 📦 **GlobalSettings** (`DataClass`)
    - 📝 Represents global application settings.
  - 📦 **AppConfig** (`DataClass`)
    - 📝 The root configuration model containing all application settings.
- 📦 **SchedulerModule** (`Module`)
  - 📝 Manages scheduled tasks using APScheduler.
  - 🏗️ Layer: Core
  - ℂ **SchedulerService** (`Class`)
    - 📝 Provides a service to manage scheduled backup tasks.
    - ƒ **SchedulerService.start** (`Function`)
      - 📝 Starts the background scheduler and loads initial schedules.
    - ƒ **SchedulerService.stop** (`Function`)
      - 📝 Stops the background scheduler.
    - ƒ **SchedulerService.load_schedules** (`Function`)
      - 📝 Loads backup schedules from configuration and registers them.
    - ƒ **SchedulerService.add_backup_job** (`Function`)
      - 📝 Adds a scheduled backup job for an environment.
    - ƒ **SchedulerService._trigger_backup** (`Function`)
      - 📝 Triggered by the scheduler to start a backup task.
- ℂ **PluginLoader** (`Class`)
  - 📝 Scans a specified directory for Python modules, dynamically loads them, and registers any classes that are valid implementations of the PluginBase interface.
  - 🏗️ Layer: Core
  - ƒ **PluginLoader.__init__** (`Function`)
    - 📝 Initializes the PluginLoader with a directory to scan.
  - ƒ **PluginLoader._load_plugins** (`Function`)
    - 📝 Scans the plugin directory and loads all valid plugins.
  - ƒ **PluginLoader._load_module** (`Function`)
    - 📝 Loads a single Python module and discovers PluginBase implementations.
  - ƒ **PluginLoader._register_plugin** (`Function`)
    - 📝 Registers a PluginBase instance and its configuration.
  - ƒ **PluginLoader.get_plugin** (`Function`)
    - 📝 Retrieves a loaded plugin instance by its ID.
  - ƒ **PluginLoader.get_all_plugin_configs** (`Function`)
    - 📝 Returns a list of all registered plugin configurations.
  - ƒ **PluginLoader.has_plugin** (`Function`)
    - 📝 Checks if a plugin with the given ID is registered.
- ℂ **PluginBase** (`Class`)
  - 📝 Defines the abstract base class that all plugins must implement to be recognized by the system. It enforces a common structure for plugin metadata and execution.
  - 🏗️ Layer: Core
- ℂ **PluginConfig** (`Class`)
  - 📝 A Pydantic model used to represent the validated configuration and metadata of a loaded plugin. This object is what gets exposed to the API layer.
  - 🏗️ Layer: Core
- 📦 **backend.src.core.utils.matching** (`Module`)
  - 📝 Provides utility functions for fuzzy matching database names.
  - 🏗️ Layer: Core
  - 🔗 DEPENDS_ON -> `rapidfuzz`
  - ƒ **suggest_mappings** (`Function`)
    - 📝 Suggests mappings between source and target databases using fuzzy matching.
- 📦 **TaskManagerModule** (`Module`)
  - 📝 Manages the lifecycle of tasks, including their creation, execution, and state tracking. It uses a thread pool to run plugins asynchronously.
  - 🏗️ Layer: Core
  - ℂ **TaskManager** (`Class`)
    - 📝 Manages the lifecycle of tasks, including their creation, execution, and state tracking.
    - ƒ **TaskManager.__init__** (`Function`)
      - 📝 Initialize the TaskManager with dependencies.
    - ƒ **TaskManager.create_task** (`Function`)
      - 📝 Creates and queues a new task for execution.
    - ƒ **TaskManager._run_task** (`Function`)
      - 📝 Internal method to execute a task.
    - ƒ **TaskManager.resolve_task** (`Function`)
      - 📝 Resumes a task that is awaiting mapping.
    - ƒ **TaskManager.wait_for_resolution** (`Function`)
      - 📝 Pauses execution and waits for a resolution signal.
    - ƒ **TaskManager.wait_for_input** (`Function`)
      - 📝 Pauses execution and waits for user input.
    - ƒ **TaskManager.get_task** (`Function`)
      - 📝 Retrieves a task by its ID.
    - ƒ **TaskManager.get_all_tasks** (`Function`)
      - 📝 Retrieves all registered tasks.
    - ƒ **TaskManager.get_tasks** (`Function`)
      - 📝 Retrieves tasks with pagination and optional status filter.
    - ƒ **TaskManager.get_task_logs** (`Function`)
      - 📝 Retrieves logs for a specific task.
    - ƒ **TaskManager._add_log** (`Function`)
      - 📝 Adds a log entry to a task and notifies subscribers.
    - ƒ **TaskManager.subscribe_logs** (`Function`)
      - 📝 Subscribes to real-time logs for a task.
    - ƒ **TaskManager.unsubscribe_logs** (`Function`)
      - 📝 Unsubscribes from real-time logs for a task.
    - ƒ **TaskManager.load_persisted_tasks** (`Function`)
      - 📝 Load persisted tasks using persistence service.
    - ƒ **TaskManager.await_input** (`Function`)
      - 📝 Transition a task to AWAITING_INPUT state with input request.
    - ƒ **TaskManager.resume_task_with_password** (`Function`)
      - 📝 Resume a task that is awaiting input with provided passwords.
    - ƒ **TaskManager.clear_tasks** (`Function`)
      - 📝 Clears tasks based on status filter.
- 📦 **TaskManagerPackage** (`Module`)
  - 📝 Exports the public API of the task manager package.
  - 🏗️ Layer: Core
- 📦 **TaskCleanupModule** (`Module`)
  - 📝 Implements task cleanup and retention policies.
  - 🏗️ Layer: Core
  - ℂ **TaskCleanupService** (`Class`)
    - 📝 Provides methods to clean up old task records.
    - ƒ **TaskCleanupService.run_cleanup** (`Function`)
      - 📝 Deletes tasks older than the configured retention period.
- 📦 **TaskManagerModels** (`Module`)
  - 📝 Defines the data models and enumerations used by the Task Manager.
  - 🏗️ Layer: Core
  - 📦 **TaskStatus** (`Enum`)
    - 📝 Defines the possible states a task can be in during its lifecycle.
  - ℂ **LogEntry** (`Class`)
    - 📝 A Pydantic model representing a single, structured log entry associated with a task.
  - ℂ **Task** (`Class`)
    - 📝 A Pydantic model representing a single execution instance of a plugin, including its status, parameters, and logs.
    - ƒ **Task.__init__** (`Function`)
      - 📝 Initializes the Task model and validates input_request for AWAITING_INPUT status.
- 📦 **TaskPersistenceModule** (`Module`)
  - 📝 Handles the persistence of tasks using SQLAlchemy and the tasks.db database.
  - 🏗️ Layer: Core
  - ℂ **TaskPersistenceService** (`Class`)
    - 📝 Provides methods to save and load tasks from the tasks.db database using SQLAlchemy.
    - ƒ **TaskPersistenceService.persist_task** (`Function`)
      - 📝 Persists or updates a single task in the database.
    - ƒ **TaskPersistenceService.persist_tasks** (`Function`)
      - 📝 Persists multiple tasks.
    - ƒ **TaskPersistenceService.load_tasks** (`Function`)
      - 📝 Loads tasks from the database.
    - ƒ **TaskPersistenceService.delete_tasks** (`Function`)
      - 📝 Deletes specific tasks from the database.
- 📦 **BackupPlugin** (`Module`)
  - 📝 A plugin that provides functionality to back up Superset dashboards.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - ℂ **BackupPlugin** (`Class`)
    - 📝 Implementation of the backup plugin logic.
- 📦 **MigrationPlugin** (`Module`)
  - 📝 A plugin that provides functionality to migrate Superset dashboards between environments.
  - 🏗️ Layer: App
  - 🔗 DEPENDS_ON -> `superset_tool.client`
  - 🔗 DEPENDS_ON -> `superset_tool.utils`
  - ℂ **MigrationPlugin** (`Class`)
    - 📝 Implementation of the migration plugin logic.
    - 📦 **MigrationPlugin.execute** (`Action`)
      - 📝 Execute the migration logic with proper task logging.
- 📦 **AuthModule** (`Module`)
  - 📝 Implements ADFS authentication using Authlib for FastAPI. It provides a dependency to protect endpoints.
  - 🏗️ Layer: UI (API)
- 📦 **SettingsRouter** (`Module`)
  - 📝 Provides API endpoints for managing application settings and Superset environments.
  - 🏗️ Layer: UI (API)
  - 🔗 DEPENDS_ON -> `ConfigManager`
  - 🔗 DEPENDS_ON -> `ConfigModels`
  - ƒ **get_settings** (`Function`)
    - 📝 Retrieves all application settings.
  - ƒ **update_global_settings** (`Function`)
    - 📝 Updates global application settings.
  - ƒ **get_environments** (`Function`)
    - 📝 Lists all configured Superset environments.
  - ƒ **add_environment** (`Function`)
    - 📝 Adds a new Superset environment.
  - ƒ **update_environment** (`Function`)
    - 📝 Updates an existing Superset environment.
  - ƒ **delete_environment** (`Function`)
    - 📝 Deletes a Superset environment.
  - ƒ **test_environment_connection** (`Function`)
    - 📝 Tests the connection to a Superset environment.
  - ƒ **validate_backup_path** (`Function`)
    - 📝 Validates if a backup path exists and is writable.
- 📦 **TasksRouter** (`Module`)
  - 📝 Defines the FastAPI router for task-related endpoints, allowing clients to create, list, and get the status of tasks.
  - 🏗️ Layer: UI (API)
- 📦 **backend.src.api.routes.environments** (`Module`)
  - 📝 API endpoints for listing environments and their databases.
  - 🏗️ Layer: API
  - 🔗 DEPENDS_ON -> `backend.src.dependencies`
  - 🔗 DEPENDS_ON -> `backend.src.core.superset_client`
  - 📦 **ScheduleSchema** (`DataClass`)
  - 📦 **EnvironmentResponse** (`DataClass`)
  - 📦 **DatabaseResponse** (`DataClass`)
  - ƒ **get_environments** (`Function`)
    - 📝 List all configured environments.
  - ƒ **update_environment_schedule** (`Function`)
    - 📝 Update backup schedule for an environment.
  - ƒ **get_environment_databases** (`Function`)
    - 📝 Fetch the list of databases from a specific environment.
- 📦 **PluginsRouter** (`Module`)
  - 📝 Defines the FastAPI router for plugin-related endpoints, allowing clients to list available plugins.
  - 🏗️ Layer: UI (API)
- 📦 **backend.src.api.routes.migration** (`Module`)
  - 📝 API endpoints for migration operations.
  - 🏗️ Layer: API
  - 🔗 DEPENDS_ON -> `backend.src.dependencies`
  - 🔗 DEPENDS_ON -> `backend.src.models.dashboard`
  - ƒ **get_dashboards** (`Function`)
    - 📝 Fetch all dashboards from the specified environment for the grid.
  - ƒ **execute_migration** (`Function`)
    - 📝 Execute the migration of selected dashboards.
- 📦 **backend.src.api.routes.mappings** (`Module`)
  - 📝 API endpoints for managing database mappings and getting suggestions.
  - 🏗️ Layer: API
  - 🔗 DEPENDS_ON -> `backend.src.dependencies`
  - 🔗 DEPENDS_ON -> `backend.src.core.database`
  - 🔗 DEPENDS_ON -> `backend.src.services.mapping_service`
  - 📦 **MappingCreate** (`DataClass`)
  - 📦 **MappingResponse** (`DataClass`)
  - 📦 **SuggestRequest** (`DataClass`)
  - ƒ **get_mappings** (`Function`)
    - 📝 List all saved database mappings.
  - ƒ **create_mapping** (`Function`)
    - 📝 Create or update a database mapping.
  - ƒ **suggest_mappings_api** (`Function`)
    - 📝 Get suggested mappings based on fuzzy matching.