ss-tools/specs/031-maintenance-banner/contracts/modules.md

Semantic Contracts: Maintenance Banner for Dashboards

Feature Branch: 031-maintenance-banner Created: 2026-05-21 Status: Phase 1 — Design Contracts Updated: 2026-05-25 — Added APIKey contracts

Backend Contracts

[DEF:MaintenanceEvent:Model]

@COMPLEXITY 1 @PURPOSE SQLAlchemy ORM model for maintenance event records. @LAYER models @FILE backend/src/models/maintenance.py @RELATION DEPENDS_ON -> [Base:Model]

Columns: id (str PK), task_id (str, loose reference to TaskManager), environment_id (str — snapshot of target env at creation), tables (JSON), start_time (datetime tz, required), end_time (datetime tz, nullable), message (text?), status (enum: pending/applying/active/partial/ending/completed/failed), created_at, updated_at.

[DEF:MaintenanceDashboardBanner:Model]

@COMPLEXITY 1 @PURPOSE Canonical "one chart per dashboard" entity — enforces invariant exactly one banner chart per dashboard regardless of active event count. Unique partial index on (environment_id, dashboard_id) WHERE status='active'. @LAYER models @FILE backend/src/models/maintenance.py @RELATION DEPENDS_ON -> [Base:Model]

Columns: id (str PK), environment_id (str), dashboard_id (int), chart_id (int? — Superset markdown chart ID), banner_text (text — current aggregated markdown), status (enum: active/removed), created_at, updated_at.

[DEF:MaintenanceDashboardState:Model]

@COMPLEXITY 1 @PURPOSE Junction linking events to dashboards. References shared MaintenanceDashboardBanner — does not own chart_id directly. @LAYER models @FILE backend/src/models/maintenance.py @RELATION DEPENDS_ON -> [Base:Model] @RELATION DEPENDS_ON -> [MaintenanceEvent:Model] @RELATION DEPENDS_ON -> [MaintenanceDashboardBanner:Model]

Columns: id (str PK), event_id (str FK→maintenance_events.id), dashboard_id (int), banner_id (str FK→maintenance_dashboard_banners.id), status (enum: pending_apply/active/removing/removed/apply_failed/removal_failed), created_at, updated_at. Index: (dashboard_id, status).

[DEF:MaintenanceSettings:Model]

@COMPLEXITY 1 @PURPOSE Single-row configuration table for maintenance mode settings. @LAYER models @FILE backend/src/models/maintenance.py @RELATION DEPENDS_ON -> [Base:Model]

Columns: id (str PK, "default"), target_environment_id (str), display_timezone (str, default "UTC"), banner_template (text — markdown with optional {start_time}, {end_time}, {message}; default includes all three), dashboard_scope (enum: published_only/draft_only/all), excluded_dashboard_ids (JSON), forced_dashboard_ids (JSON), updated_at.

[DEF:APIKey:Model]

@COMPLEXITY 1 @PURPOSE Service-to-service static bearer token for external tool authentication. Raw key (format: ssk_<43 URL-safe chars>) shown once at creation; only SHA-256 hash stored. Environment-scoped, permission-gated, revocable. @LAYER models @FILE backend/src/models/maintenance.py (or backend/src/models/api_key.py) @RELATION DEPENDS_ON -> [Base:Model] @INVARIANT Raw key NEVER stored in DB. Only key_hash = SHA256(token) persisted. Prefix (first 11 chars of token) stored unhashed for admin identification. @INVARIANT One key per external tool (named). Multiple keys per tool possible but not recommended — use key rotation.

Columns: id (UUID PK), key_hash (str UNIQUE, SHA-256 of raw key), prefix (str, first 11 chars), name (str), environment_id (str|null — scoped to one env; null = all), permissions (JSON str[]), active (bool), created_at, expires_at (datetime|null), last_used_at (datetime|null).

[DEF:APIKeyPrincipal:Dependency]

@COMPLEXITY 2 @PURPOSE FastAPI dependency resolving an APIKey DB row into a lightweight principal object for RBAC checks. Activated by X-API-Key header. Falls through when header absent (allowing JWT to take over). @LAYER dependencies @FILE backend/src/dependencies.py or backend/src/core/auth/api_key.py @RELATION DEPENDS_ON -> [APIKey:Model] @RELATION DEPENDS_ON -> [FastAPI.Header] @PRE X-API-Key header may be present. DB session available. @POST If header valid and key active → returns APIKeyPrincipal(name, environment_id, permissions). If header absent → returns None (fall through to JWT). If invalid/expired → raises HTTPException(401).

Verification flow: hash incoming header, lookup in DB by hash, check active + expires_at, update last_used_at.

[DEF:APIKeyAdminRoutes:Module]

@COMPLEXITY 2 @PURPOSE Admin-only API key CRUD endpoints. Keys are read-once secrets. @LAYER api @FILE backend/src/api/routes/admin/api_keys.py (new) @RELATION DEPENDS_ON -> [APIKey:Model] @RELATION DEPENDS_ON -> [has_permission("admin:settings", "WRITE")] @INVARIANT Raw key returned ONLY in POST response — never in GET. @INVARIANT DELETE sets active=false — preserves audit trail (no physical deletion).

Endpoints:

• GET /api/admin/api-keys — list all (active + revoked)
• POST /api/admin/api-keys — generate new key (returns {id, raw_key, prefix, name, ...})
• DELETE /api/admin/api-keys/{id} — revoke key (active=false)

---

[DEF:MaintenanceSchemas:Module]

@COMPLEXITY 1 @PURPOSE Pydantic request/response schemas for maintenance API endpoints. @LAYER schemas @FILE backend/src/api/routes/maintenance/_schemas.py @RELATION DEPENDS_ON -> [pydantic.BaseModel]

Request schemas:

• MaintenanceStartRequest — tables, start_time, end_time(opt), message(opt), environment_id (required — per FR-001 2026-05-25 revision)
• MaintenanceSettingsUpdate — all optional partial-update fields

Response schemas: MaintenanceStartResponse, MaintenanceEndResponse, MaintenanceSettingsResponse, MaintenanceEventItem, MaintenanceEventListResponse, MaintenanceDashboardBannerState.

[DEF:SupersetDashboardsWriteMixin:Class]

@COMPLEXITY 4 @PURPOSE Extends SupersetClient with dashboard write operations. @LAYER core @FILE backend/src/core/superset_client/_dashboards_write.py @RELATION DEPENDS_ON -> [SupersetClientBase:Class] @RELATION DEPENDS_ON -> [NetworkClient:Class] @PRE SupersetClient is initialized with valid bearer token and environment base URL. @POST Chart created/updated/deleted in Superset. Dashboard position_json updated. @SIDE_EFFECT Modifies Superset dashboards via REST API. @RATIONALE Direct chart API faster than export-import cycle for single-chart ops.

Methods: create_markdown_chart, update_markdown_chart, update_dashboard_layout (insert at (0,0), 12 cols, shift existing down), remove_chart_from_layout, delete_chart, get_dashboard_layout.

[DEF:SqlTableExtractor:Module]

@COMPLEXITY 2 @PURPOSE Extract schema.table from virtual dataset SQL+Jinja. Two-phase: Jinja span detection, regex global extraction, sqlparse filtering only on SQL spans (string literals). @LAYER services @FILE backend/src/services/sql_table_extractor.py @RELATION DEPENDS_ON -> [sqlparse] @RATIONALE Table names in {% set %} blocks must survive; stripping Jinja first loses them.

[DEF:MaintenanceService:Class]

@COMPLEXITY 4 @PURPOSE Core business logic: discovery, banner placement/removal, text rebuild. @LAYER services @FILE backend/src/services/maintenance_service.py @RELATION DEPENDS_ON -> [SupersetClient:Class] @RELATION DEPENDS_ON -> [SupersetDashboardsWriteMixin:Class] @RELATION DEPENDS_ON -> [SqlTableExtractor:Module] @RELATION DEPENDS_ON -> [MaintenanceEvent:Model] @RELATION DEPENDS_ON -> [MaintenanceDashboardState:Model] @RELATION DEPENDS_ON -> [MaintenanceDashboardBanner:Model] @RELATION DEPENDS_ON -> [MaintenanceSettings:Model] @RELATION DEPENDS_ON -> [TaskManager:Class] @PRE Active DB session. Superset client initialized. @POST Event/state/banner records updated. Charts created/updated/deleted. @SIDE_EFFECT Superset mutations; DB writes; WebSocket progress events. @RATIONALE Single orchestrator ensures consistency between local state and Superset.

Methods: start_maintenance (idempotency by (tables, start, end)), end_maintenance, end_all_maintenance, find_affected_dashboards, ensure_banner_chart (shared chart per dashboard), build_banner_text (template substitution), rebuild_banner (update_markdown_chart).

[DEF:MaintenanceRoutes:Module]

@COMPLEXITY 4 @PURPOSE FastAPI route handlers for maintenance endpoints. Dual auth: JWT (existing) + API Key via require_api_key_or_jwt. Environment scoping enforced per FR-001 revision. @LAYER api @FILE backend/src/api/routes/maintenance/_routes.py @RELATION DEPENDS_ON -> [MaintenanceService:Class] @RELATION DEPENDS_ON -> [MaintenanceSchemas:Module] @RELATION DEPENDS_ON -> [TaskManager:Class] @RELATION DEPENDS_ON -> [AuthMiddleware:Class] @RELATION DEPENDS_ON -> [APIKeyPrincipal:Dependency] @RELATION DEPENDS_ON -> [require_api_key_or_jwt:Function]

8 endpoints:

• POST /start — dual auth (JWT or API key with maintenance:start), requires environment_id
• POST /{id}/end — dual auth (JWT or API key with maintenance:end), validates key scope against event's stored env
• POST /end-all — dual auth (JWT or API key with maintenance:end_all)
• GET /events — JWT only, auto-expires stale events
• GET /dashboard-banners — JWT only
• GET /settings — JWT only
• PUT /settings — JWT only (admin)

[DEF:MaintenanceRouter:Module]

@COMPLEXITY 2 @PURPOSE APIRouter assembly with prefix and tag. @LAYER api @FILE backend/src/api/routes/maintenance/_router.py @RELATION DEPENDS_ON -> [MaintenanceRoutes:Module]

---

Frontend Contracts

[DEF:MaintenanceStore:Module]

@COMPLEXITY 3 @PURPOSE Svelte 5 rune store for maintenance state. Shared by management page and Dashboard Hub badge. @LAYER store @FILE frontend/src/lib/stores/maintenance.svelte.js @RELATION DEPENDS_ON -> [requestApi:Function] @RATIONALE Shared store avoids prop drilling across routes. Uses $effect(subscribe) per ADR-0007.

State: events ($state), settings ($state), dashboardBanners ($state Map), isLoading, error. Auto-polls events every 30s; WebSocket covers task progress.

[DEF:MaintenanceApiClient:Module]

@COMPLEXITY 2 @PURPOSE Typed fetch wrappers for maintenance API. @LAYER api @FILE frontend/src/lib/api/maintenance.js @RELATION DEPENDS_ON -> [requestApi:Function]

7 functions mirroring the 7 API endpoints.

[DEF:MaintenanceBannerPage:Component]

@COMPLEXITY 3 @PURPOSE Management page at /maintenance. Compose settings panel + events table from store. @LAYER route @FILE frontend/src/routes/maintenance/+page.svelte @RELATION DEPENDS_ON -> [MaintenanceStore:Module] @RELATION DEPENDS_ON -> [MaintenanceSettingsPanel:Component] @RELATION DEPENDS_ON -> [MaintenanceEventsTable:Component] @UX_STATE idle/loading/action_in_progress/error/empty @UX_FEEDBACK Toast via addToast() from $lib/toasts.js

[DEF:MaintenanceSettingsPanel:Component]

@COMPLEXITY 3 @PURPOSE Collapsible settings form for maintenance-specific configuration. API key management is handled centrally in Settings (see [DEF:ApiKeySettingsPanel:Component]). @LAYER component @FILE frontend/src/lib/components/MaintenanceSettingsPanel.svelte @RELATION DEPENDS_ON -> [MaintenanceStore:Module] @RELATION DEPENDS_ON -> [Select:Component] (from $lib/ui/Select.svelte) @RELATION DEPENDS_ON -> [Input:Component] (from $lib/ui/Input.svelte) @RELATION DEPENDS_ON -> [SearchableMultiSelect:Component] (from $lib/components/ui/SearchableMultiSelect.svelte) @RATIONALE Reuses existing form atoms (Select, Input) and dashboard picker (SearchableMultiSelect) — zero new UI primitives needed.

Form fields:

• Environment: <Select> with env options
• Timezone: <Input> text
• Scope: native <input type="radio" bind:group> (matches ScheduleConfig pattern)
• Excluded/Forced: <SearchableMultiSelect> with dashboards as {id, name}
• Banner template: <textarea> with live preview div
• Save: <Button isLoading={isSaving}> from $lib/ui/Button.svelte

Collapsible via <details><summary> (matches migration page pattern).

@UX_STATE idle/saving/saved/error

[DEF:MaintenanceEventsTable:Component]

@COMPLEXITY 3 @PURPOSE Active/completed events table with removal actions. @LAYER component @FILE frontend/src/lib/components/MaintenanceEventsTable.svelte @RELATION DEPENDS_ON -> [MaintenanceStore:Module] @RELATION DEPENDS_ON -> [MaintenanceApiClient:Module] @RELATION DEPENDS_ON -> [Button:Component] (from $lib/ui/Button.svelte)

Uses inline table pattern from health page (min-w-full divide-y), skeleton rows (animate-pulse), empty state (border-dashed bg-gray-50), badges (inline Tailwind rounded-full), confirmation via native confirm(). Spinner via Button(isLoading={true}).

@UX_STATE idle/removing/error

[DEF:DashboardGridBannerIndicator:Component]

@COMPLEXITY 2 @PURPOSE Orange badge in Dashboard Hub row when maintenance active. @LAYER component @FILE frontend/src/lib/components/DashboardMaintenanceBadge.svelte @RELATION DEPENDS_ON -> [MaintenanceStore:Module]

Badge: rounded-full px-2.5 py-0.5 text-xs font-medium bg-orange-100 text-orange-700 (matches existing badge convention). Tooltip via native title attribute (matches codebase-wide pattern). No badge when inactive. Skeleton: animate-pulse bg-gray-200 h-5 w-24 rounded-full.

@UX_STATE no_maintenance/maintenance_active/loading

[DEF:ApiKeySettingsPanel:Component]

@COMPLEXITY 2 @PURPOSE Centralized admin section in System Settings (/settings) for managing API keys. Keys are cross-cutting infrastructure — any tool (maintenance, migration, translation) can consume them. NOT embedded in Maintenance panel. @LAYER component @FILE frontend/src/lib/components/settings/ApiKeySettingsPanel.svelte (new) or embedded in frontend/src/routes/settings/SystemSettings.svelte @RELATION DEPENDS_ON -> [requestApi:Function] @PRE User has admin role (admin:settings WRITE). @POST API key CRUD operations dispatched. New key raw value shown once in a copyable <code> block. @RATIONALE Read-once key display: raw key shown in a <pre> block with Copy button. After user dismisses, raw key is gone forever. List shows prefix only. @RATIONALE Centralized architecture: API keys live in Settings — not coupled to Maintenance. Future tools (migration API, data export, etc.) all use the same key infrastructure. Maintenance endpoints are just the first consumer.

UI elements:

• Table: columns Name, Prefix (monospace), Environment, Permissions, Active, Created, Revoke (button)
• "Generate Key" form: name input, environment select, permissions checkboxes (start/end/end_all), optional expiry date
• After generation: modal/expanding panel with raw key in <pre> block + "Copy to clipboard" button + warning "Copy this key now — it won't be shown again"
• Revoke: confirmation dialog, then DELETE /api/admin/api-keys/{id}

@UX_STATE idle/generating/generated/revoking/error