ss-tools/docs/settings.md

Web Application Settings Mechanism

This document describes the settings management system for the Superset Tools application.

Overview

The settings mechanism allows users to configure multiple Superset environments and global application settings (like backup storage) via the web UI.

Backend Architecture

Data Models

Configuration is structured using Pydantic models in backend/src/core/config_models.py:

• Environment: Represents a Superset instance (URL, credentials). The base_url is automatically normalized to include the /api/v1 suffix if missing.
• GlobalSettings: Global application parameters (e.g., storage.root_path).
• AppConfig: The root configuration object.

Configuration Manager

The ConfigManager (backend/src/core/config_manager.py) handles:

• Persistence to config.json.
• CRUD operations for environments.
• Validation and logging.

API Endpoints

The settings API is available at /settings:

• GET /settings: Retrieve all settings (passwords are masked).
• PATCH /settings/global: Update global settings.
• GET /settings/environments: List environments.
• POST /settings/environments: Add environment.
• PUT /settings/environments/{id}: Update environment.
• DELETE /settings/environments/{id}: Remove environment.
• POST /settings/environments/{id}/test: Test connection.

Frontend Implementation

The settings page is located at frontend/src/pages/Settings.svelte. It provides forms for managing global settings and Superset environments.

Reports Center

Unified reports are available at /reports and use the backend API at /api/reports and /api/reports/{report_id}.

What operators can do

• View all task outcomes (LLM verification, backup, migration, documentation) in one list.
• Filter by type and status.
• Open report detail with diagnostics and recommended next actions.
• Continue working even for unknown task types and partial payloads (explicit placeholders are shown instead of hidden data).

Troubleshooting

• If report list is empty, verify tasks exist and clear filters.
• If report detail is not found (404), confirm the selected report still exists in task history.
• If report API tests fail during local execution with database connectivity errors, ensure the configured DB is reachable or run in an environment with available test DB services.

Integration

Existing plugins and utilities use the ConfigManager to fetch configuration:

• superset_tool/utils/init_clients.py: Dynamically initializes Superset clients from the configured environments.
• BackupPlugin: Uses the configured storage.root_path as the default storage location.