ss-tools/.ai/standards/architecture.md

[DEF:Std:Architecture:Standard]

@TIER: CRITICAL

@PURPOSE: Core architectural decisions and service boundaries.

@LAYER: Infra

@INVARIANT: ss-tools MUST remain a standalone service (Orchestrator).

@INVARIANT: Backend: FastAPI, Frontend: SvelteKit.

1. ORCHESTRATOR VS INSTANCE

• Role: ss-tools is a "Manager of Managers". It sits ABOVE Superset environments.
• Isolation: Do not integrate directly into Superset as a plugin to maintain multi-environment management capability.
• Tech Stack:
  • Backend: Python 3.9+ with FastAPI (Asynchronous logic).
  • Frontend: SvelteKit + Tailwind CSS (Reactive UX).

2. COMPONENT BOUNDARIES

• Plugins: All business logic must be encapsulated in Plugins (backend/src/plugins/).
• TaskManager: All long-running operations MUST be handled by the TaskManager.
• Security: Independent RBAC system managed in auth.db.

3. INTEGRATION STRATEGY

• Superset API: Communication via REST API.
• Database: Local SQLite for metadata (tasks.db, auth.db, migrations.db).
• Filesystem: Local storage for backups and git repositories.

[/DEF:Std:Architecture]