ss-tools/specs/026-dashboard-health-windows/data-model.md

Data Model: Dashboard Health Windows

Entities

ValidationPolicy (New)

Layer: Domain (Backend DB) Purpose: Defines a scheduled rule for validating a group of dashboards within an execution window.

Field	Type	Description
id	UUID (PK)	Unique policy identifier
name	String	Human-readable name for the policy (e.g., "Nightly Critical Prod")
environment_id	String	Foreign Key to configured Superset environment
is_active	Boolean	Whether the policy is currently enabled (default: true)
dashboard_ids	JSON	Array of dashboard string identifiers/slugs targeted by this policy
schedule_days	JSON	Array of integers representing days of week (0=Mon, 6=Sun)
window_start	Time	Start time of the execution window (e.g., 01:00)
window_end	Time	End time of the execution window (e.g., 05:00)
notify_owners	Boolean	Whether to route alerts dynamically based on Superset owners
custom_channels	JSON	List of external channels (e.g., [{"type": "slack", "target": "#alerts"}])
alert_condition	Enum	Trigger condition: FAIL_ONLY, WARN_AND_FAIL, ALWAYS
created_at	DateTime	Audit timestamp
updated_at	DateTime	Audit timestamp

Relationships:

• Targets multiple Dashboards (implied via JSON array of IDs).

NotificationConfig (New)

Layer: Domain (Backend DB - AppConfigRecord or standalone) Purpose: Global settings for external notification providers (configured by Admins).

Field	Type	Description
id	UUID (PK)	Unique provider config identifier
type	Enum	Provider type: SMTP, SLACK, TELEGRAM
name	String	Display name for the config
credentials	JSON	Encrypted connection details (Host, Token, Password)
is_active	Boolean	Whether the provider is enabled

UserDashboardPreference (Extended)

Layer: Domain (Backend DB) Purpose: Extended to hold user contact details for smart routing.

Field	Type	Description
... existing ...
telegram_id	String	User's Telegram Chat ID for direct messages
email_address	String	Override email address for direct notifications
notify_on_fail	Boolean	Opt-out toggle for automated owner alerts

ValidationRecord (Updated/Extended)

Layer: Domain (Backend DB) Purpose: Represents the outcome of a single dashboard validation task.

Note: This entity likely already exists partially; this defines the required shape for this feature.

Field	Type	Description
id	UUID (PK)	Unique record identifier
task_id	UUID (FK)	Reference to the underlying execution task
dashboard_id	String (Index)	Identifier of the dashboard checked
environment_id	String (Index)	Environment where the dashboard lives
status	Enum	Validation status: PASS, WARN, FAIL, UNKNOWN
issues	JSON	Array of structured issue tags/types found (e.g., ["SQL_ERROR", "TIMEOUT"])
llm_summary	Text	Human-readable explanation of the findings from the LLM
screenshot_path	String (Optional)	Path to the visual artifact in storage
validated_at	DateTime	Timestamp of the check

Relationships:

• task_id points to TaskRecord.

API Contracts

DashboardItem (Extension)

The existing DashboardItem schema returned by GET /api/dashboards will be extended to support the Health Center view.

// Extended fields added to existing response
{
  "validation_status": "PASS | WARN | FAIL | UNKNOWN",
  "validation_issues": ["Broken Chart", "Timeout"],
  "last_validation_time": "2026-03-10T02:15:00Z",
  "last_validation_task_id": "uuid-string"
}

Validation Policy Endpoints

GET /api/settings/automation/policies

Returns a list of all validation policies.

POST /api/settings/automation/policies

Creates a new validation policy.

Request Body:

{
  "name": "Nightly Check",
  "environment_id": "ss-prod",
  "dashboard_ids": ["123", "456"],
  "schedule_days": [0, 1, 2, 3, 4],
  "window_start": "01:00",
  "window_end": "05:00",
  "notify_owners": true,
  "custom_channels": [
    {"type": "slack", "target": "#data-team"}
  ],
  "alert_condition": "FAIL_ONLY"
}

Global Notification Settings

• GET /api/settings/notifications/providers
• POST /api/settings/notifications/providers
• PUT /api/settings/notifications/providers/{id}

PUT /api/settings/automation/policies/{policy_id}

Updates an existing policy.

DELETE /api/settings/automation/policies/{policy_id}

Deletes a policy.

AI Assistant Output

The existing Assistant endpoints will need to return deep links to the new Health Center and detailed reports.

// Example Action returned by Assistant
{
  "action_type": "NAVIGATE",
  "url": "/dashboards/health?filter=fail",
  "label": "View Failed Dashboards"
}