58 lines
4.7 KiB
Markdown
58 lines
4.7 KiB
Markdown
# [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]
|