ss-tools/specs/001-plugin-arch-svelte-ui/research.md

Research: Plugin Architecture & Svelte Web UI

Decisions

1. Web Framework: FastAPI

• Decision: Use FastAPI for the Python backend.
• Rationale:
  • Native support for Pydantic models (crucial for plugin schema validation).
  • Async support (essential for handling long-running tasks and log streaming via WebSockets/SSE).
  • Automatic OpenAPI documentation generation (simplifies frontend integration).
  • High performance and modern ecosystem.
• Alternatives Considered:
  • Flask: Mature but requires extensions for validation (Marshmallow) and async support is less native. Slower for high-concurrency API calls.
  • Django: Too heavy for this use case; brings unnecessary ORM and template engine overhead.

2. Plugin System: importlib + Abstract Base Classes (ABC)

• Decision: Use Python's built-in importlib for dynamic loading and abc for defining the plugin interface.
• Rationale:
  • importlib provides a standard, secure way to load modules from a path.
  • ABCs ensure plugins implement required methods (execute, get_schema) at load time.
  • Lightweight, no external dependencies required.
• Alternatives Considered:
  • Pluggy: Used by pytest, powerful but adds complexity and dependency overhead.
  • Stevedore: OpenStack's plugin loader, too complex for this scope.

3. Authentication: authlib + ADFS (OIDC/SAML)

• Decision: Use authlib to handle ADFS authentication via OpenID Connect (OIDC) or SAML.
• Rationale:
  • authlib is the modern standard for OAuth/OIDC in Python.
  • Supports integration with FastAPI via middleware.
  • ADFS is the required identity provider (IdP).
• Alternatives Considered:
  • python-social-auth: Older, harder to integrate with FastAPI.
  • Manual JWT implementation: Risky and reinvents the wheel; ADFS handles the token issuance.

4. Frontend: Svelte + Vite

• Decision: Use Svelte for the UI framework and Vite as the build tool.
• Rationale:
  • Svelte's compiler-based approach results in small bundles and high performance.
  • Reactive model maps well to real-time log updates.
  • Vite provides a fast development experience and easy integration with backend proxies.

Unknowns Resolved

• Deployment Context: Hosted multi-user service with ADFS.
• Plugin Interface: Will use Pydantic models to define input schemas, allowing the frontend to generate forms dynamically.