# [DEF:ADR-0003:ADR]
# @STATUS ACTIVE
# @PURPOSE Definitively establish ss-tools as a standalone orchestrator service operating *above* Apache Superset environments rather than integrating into them. This is a repo‑shaping architectural decision that governs deployment topology, security boundary, release cycle independence, and technology stack freedom.
# @RELATION DEPENDS_ON -> [ADR-0001:ADR]
# @RELATION CALLS -> [ADR-0004:ADR]
# @RELATION CALLS -> [ADR-0005:ADR]
# @RATIONALE The core value proposition of ss-tools is multi‑environment orchestration: moving dashboards, datasets, and configurations between independent Superset instances (Dev → Stage → Prod). Embedding this logic inside any single Superset instance would immediately create a "master controller" dependency — if that instance fails, all environment management is lost. An external orchestrator treats all Superset instances as equal endpoints.
# @RATIONALE Technology stack mismatch is irreversible: Superset uses Flask + React, ss-tools uses FastAPI + SvelteKit. Integration would require rewriting the entire Svelte frontend into React components and refactoring FastAPI dependency injection into Flask-AppBuilder patterns — a multi‑month effort with zero business value and high regression risk.
# @RATIONALE Release cycle independence is non‑negotiable: Superset has a slow, complex release cadence. ss-tools must ship LLM plugins, Git integrations, and backup features on its own schedule without waiting for upstream Superset releases or maintaining a fork with perpetual merge conflicts.
# @RATIONALE Security isolation: ss-tools manages DevOps privileges (deployment, backup, migration) while Superset manages BI privileges (data viewing, chart creation). Mixing these in one system expands the blast radius of any security incident.
# @REJECTED Integration as a Superset plugin/extension — rejected for the four reasons above (orchestrator topology break, 100% frontend rewrite, Superset release cycle coupling, privilege boundary collapse).
# @REJECTED Superset fork with ss-tools baked in — rejected because maintaining a fork requires rebase on every Superset release, creating perpetual merge conflicts and making security patch adoption dangerously slow.
# @REJECTED Shared database with Superset — rejected because it couples ss-tools migrations to Superset's Alembic migration chain, preventing independent schema evolution and creating a single point of failure for both systems.

## Decision

ss-tools operates as a **standalone orchestrator microservice** with these defined boundaries:

### Deployment Topology

```
                       ┌─────────────┐
                       │  ss-tools   │  ← FastAPI + SvelteKit
                       │  PostgreSQL │  ← Own database
                       └──────┬──────┘
                              │ REST API calls
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
       ┌──────────┐   ┌──────────┐   ┌──────────┐
       │Superset  │   │Superset  │   │Superset  │
       │  (Dev)   │   │ (Stage)  │   │  (Prod)  │
       └──────────┘   └──────────┘   └──────────┘
```

### Key Architectural Properties

| Property | Decision |
|----------|----------|
| **Topology** | External orchestrator above all Superset instances |
| **Communication** | Superset REST API (bearer token auth per environment) |
| **Database** | Dedicated PostgreSQL 16 instance (not Superset metadata DB) |
| **Frontend** | SvelteKit SPA (not integrated into Superset UI) |
| **Release cadence** | Independent Docker image releases |
| **Auth** | Own RBAC system with optional ADFS SSO (see ADR-0005) |
| **Plugins** | Own plugin lifecycle (see ADR-0004) |

### Consequences

- **Positive:** Fast independent development, modern stack, no Superset coupling, clear security boundary.
- **Negative:** Users have two separate UIs (Superset for BI, ss-tools for DevOps). Mitigated by consistent UX design and cross‑linking.
- **Risk:** API compatibility if Superset changes its REST API. Mitigated by versioned API client with automated compatibility tests.

## Migration from Existing Document

This ADR supersedes and formalizes `docs/architecture_decision_superset_migration.md`. The original document contained the same recommendation and rationale but lacked the `[DEF:id:ADR]` contract structure, making it invisible to the semantic index and decision‑memory audit chain.

# [/DEF:ADR-0003:ADR]