ss-tools/specs/002-app-settings/plan.md

Technical Plan: Web Application Settings Mechanism

This plan outlines the implementation of a settings management system for the Superset Tools application, allowing users to configure multiple Superset environments and global application settings (like backup storage) via the web UI.

1. Backend Architecture

1.1 Data Models (Pydantic)

We will define models in backend/src/core/config_models.py:

from pydantic import BaseModel, Field
from typing import List, Optional

class Environment(BaseModel):
    id: str
    name: str
    url: str
    username: str
    password: str  # Will be masked in UI
    is_default: bool = False

class GlobalSettings(BaseModel):
    backup_path: str
    default_environment_id: Optional[str] = None

class AppConfig(BaseModel):
    environments: List[Environment] = []
    settings: GlobalSettings

1.2 Configuration Manager

A new class ConfigManager in backend/src/core/config_manager.py will handle:

• Loading/saving AppConfig to config.json.
• CRUD operations for environments.
• Updating global settings.
• Validating backup paths and Superset URLs.
• Enforcing system invariants (e.g., at least one environment configured).

1.3 API Endpoints

New router backend/src/api/routes/settings.py:

• GET /settings: Retrieve all settings (masking passwords).
• PATCH /settings/global: Update global settings (backup path, etc.).
• GET /settings/environments: List all environments.
• POST /settings/environments: Add a new environment.
• PUT /settings/environments/{id}: Update an environment.
• DELETE /settings/environments/{id}: Remove an environment.
• POST /settings/environments/{id}/test: Test connection to a specific environment.

1.4 Integration

• Update backend/src/dependencies.py to provide a singleton ConfigManager.
• Refactor superset_tool/utils/init_clients.py to fetch environment details from ConfigManager instead of hardcoded values.

2. Frontend Implementation

2.1 Settings Page

• Create frontend/src/pages/Settings.svelte.
• Add a "Settings" link to the main navigation (likely in App.svelte).

2.2 Components

• EnvironmentList: Displays a table/list of configured environments with Edit/Delete buttons.
• EnvironmentForm: A modal or inline form for adding/editing environments.
• GlobalSettingsForm: Form for editing the backup storage path.

2.3 API Integration

• Add functions to frontend/src/lib/api.js for interacting with the new settings endpoints.

3. Workflow Diagram

graph TD
    UI[Web UI - Settings Page] --> API[FastAPI Settings Router]
    API --> CM[Config Manager]
    CM --> JSON[(config.json)]
    CM --> SS[Superset Instance] : Test Connection
    
    Plugins[Plugins - Backup/Migration] --> CM : Get Env/Path

4. Implementation Steps

1. Backend Core:
   • Create config_models.py and config_manager.py.
   • Implement file-based persistence.
2. Backend API:
   • Implement settings.py router.
   • Register router in app.py.
3. Frontend UI:
   • Create Settings.svelte and necessary components.
   • Implement API calls and state management.
4. Refactoring:
   • Update init_clients.py to use the new configuration system.
   • Ensure existing plugins (Backup, Migration) use the configured settings.
5. Validation:
   • Add path existence/write checks for backup storage.
   • Add URL/Connection checks for Superset environments.