ss-tools/specs/011-git-integration-dashboard/plan.md

Implementation Plan: Git Integration Plugin for Dashboard Development

Branch: 011-git-integration-dashboard | Date: 2026-01-22 | Spec: spec.md Input: Feature specification from /specs/011-git-integration-dashboard/spec.md

Summary

Implement a Git integration plugin that allows dashboard developers to version control their Superset dashboards. The plugin will support GitLab, GitHub, and Gitea, enabling branch management, committing/pushing changes (as unpacked Superset exports), and deploying to target environments via the Superset API.

Technical Context

Language/Version: Python 3.9+ (Backend), Node.js 18+ (Frontend) Primary Dependencies: FastAPI, SvelteKit, GitPython (or CLI git), Pydantic, SQLAlchemy, Superset API Storage: SQLite (for config/history), Filesystem (local Git repositories) Testing: pytest (Backend), SvelteKit testing utilities (Frontend) Target Platform: Linux server Project Type: Web application (Frontend + Backend) Performance Goals: Branch switching < 5s, Search/Filter history < 2s Constraints: Offline mode support, Superset API dependency for deployment, PAT-based authentication Scale/Scope: 1 repository per dashboard, support for up to 1000 commits per repo

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

1. Semantic Protocol Compliance: All new modules must include headers, [DEF] anchors, and @RELATION tags as per semantic_protocol.md.
2. Causal Validity: API contracts and data models must be defined in specs/ before implementation.
3. Everything is a Plugin: The Git integration must be implemented as a PluginBase subclass in backend/src/plugins/.
4. Design by Contract: Use Pydantic models for request/response validation and internal state transitions.

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

backend/
├── src/
│   ├── api/routes/git.py        # Git integration endpoints
│   ├── models/git.py            # Git-specific Pydantic/SQLAlchemy models (GitServerConfig, DashboardChange)
│   ├── plugins/git_plugin.py    # PluginBase implementation (1 repo = 1 dashboard logic)
│   └── services/git_service.py  # Core Git logic (GitPython wrapper)
└── tests/
    └── plugins/test_git.py

frontend/
├── src/
│   ├── components/git/          # Git UI components (BranchSelector, CommitModal, ConflictResolver)
│   ├── routes/settings/git/     # Git configuration pages (+page.svelte)
│   └── services/gitService.js   # API client for Git operations

Structure Decision: Web application structure as the project has both FastAPI backend and SvelteKit frontend.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

Implementation Phases

Phase 2: Backend Implementation (Plugin & Service)

1. Data Models: Implement GitServerConfig, Branch, Commit, Environment, and DashboardChange in src/models/git.py.
2. Git Service: Implement GitService using GitPython. Focus on:
   • Repo initialization and cloning (1 repo per dashboard strategy).
   • Branch management (list, create, checkout).
   • Stage, commit, push, pull.
   • History retrieval and diff generation.
3. Git Plugin: Implement GitPlugin(PluginBase).
   • Integrate with superset_tool for exporting dashboards as unpacked YAML files (metadata, charts, datasets).
   • Handle unpacking ZIP exports into the repo structure.
4. API Routes: Implement /api/git/* endpoints for config, sync, and history.

Phase 3: Frontend Implementation

1. Configuration UI: Settings page for GitServerConfig (Provider selection, PAT validation).
2. Dashboard Integration: Add Git controls to the Dashboard view.
   • Branch selector (Create/Switch).
   • Commit/Push/Pull buttons with status indicators.
   • History viewer with search/filter.
3. Conflict Resolution UI: Implementation of "Keep Mine/Theirs" file picker for YAML content.

Phase 4: Deployment Integration

1. Environment Management: CRUD for Environment (Target Superset instances).
2. Deployment Logic: Implement deployment via Superset Import API (POST /api/v1/dashboard/import/).
   • Handle zip packing from Git repo state before import.