# 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`](frontend/src/routes/reports/+page.svelte) and use the backend API at [`/api/reports`](backend/src/api/routes/reports.py) and [`/api/reports/{report_id}`](backend/src/api/routes/reports.py).

### 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.