Architecture

Slidefactory Core is a FastAPI backend + Vue 3 SPA + N8N workflow engine. This page explains how the pieces communicate.

High-Level View

graph TB
    subgraph "Frontend"
        SPA[Vue 3 SPA<br/>TypeScript + Vite + Pinia]
    end

    subgraph "Backend"
        API[FastAPI :8080]
        Worker[Celery Workers]
    end

    subgraph "External Services"
        N8N[N8N Workflow Engine]
        AI[AI Providers<br/>OpenAI / Anthropic / Mistral / ...]
        DB[(PostgreSQL + pgvector)]
        Redis[(Redis)]
        Storage[MinIO / Azure Blob]
    end

    SPA -->|JWT auth, REST calls| API
    API -->|task queue| Redis
    Redis -->|consume tasks| Worker
    API --> DB
    Worker --> DB
    API --> Storage
    Worker --> Storage
    API -->|execute workflow| N8N
    N8N -->|webhook callback| API
    N8N --> AI
    API --> AI

SPA (Vue 3 Frontend)

The SPA is served by FastAPI at /app/ and communicates exclusively via REST API.

Stack: Vue 3, TypeScript, Vite 5, Pinia (state), Vue Router 4

Pages: Dashboard, Presentations, Templates, Workflows, Collections, Settings, Login

Key patterns:

• Auth store (stores/auth.ts) — manages JWT tokens, user info, auto-refresh
• API client (api/) — typed HTTP client with auth interceptors
• Router guard — checks JWT validity before each protected route

Auth flow:

User login → POST /api/auth/login → JWT access + refresh token
             (or Azure Entra OAuth flow)
SPA stores token → includes in Authorization header
Token expires → auto-refresh via POST /api/auth/refresh

Build & serve:

• Dev: Vite dev server on :5173, proxies /api to FastAPI on :8080
• Prod: npm run build → frontend/dist/ → served by FastAPI as static files

Backend (FastAPI)

Router Structure

/api/auth/*              → login, logout, profile, Azure OAuth
/api/presentations/*     → generate, list, download, progress (SSE)
/api/templates/*         → upload, list, download, placeholders
/api/workflows/*         → list, execute, preview, favorites
/api/context/*           → document upload, RAG search
/api/results/*           → workflow result storage
/api/images/*            → image upload/management
/api/scraping/*          → web content extraction
/api/n8n-bridge/*        → context bridge for N8N workflows
/v1/chat/completions     → OpenAI-compatible proxy
/app/*                   → SPA static files

Authentication Middleware

All /api/* routes go through require_api_scope() which accepts:

1. API Key — X-API-Key header or Authorization: Bearer sf_...
2. JWT — Authorization: Bearer eyJ... (issued by /api/auth/login)
3. Session cookie — for web UI

Each method resolves to a user with scopes. Scopes control access (* = admin, or granular like presentations:read).

Celery Workers

Long-running tasks (presentation generation, thumbnails, Office365 ops) run in Celery workers via Redis broker.

Queue	Purpose	Rate limit
process_queue	Presentation generation	10/min
workflow_queue	Workflow execution	5/min
office365_queue	Microsoft Graph operations	2/min

Progress is streamed to clients via Server-Sent Events (SSE).

N8N Integration

N8N is the primary workflow engine. Slidefactory doesn't run business logic internally — it delegates to N8N workflows.

Execution Flow

sequenceDiagram
    participant Client
    participant API as FastAPI
    participant N8N
    participant AI as AI Provider
    participant Store as Storage

    Client->>API: POST /api/workflows/n8n/{id}/execute
    API->>N8N: Execute workflow via N8N API
    N8N->>AI: Generate content (GPT-4, Claude, etc.)
    AI-->>N8N: AI response
    N8N->>Store: Upload generated presentation
    N8N->>API: Webhook callback (execution complete)
    API-->>Client: Result available (via SSE or polling)

How It Connects

• API client (n8nmanager/core.py) — talks to N8N REST API for workflow CRUD and execution
• Webhook callbacks — N8N calls back to Slidefactory when workflows complete
• Variable interpolation — Slidefactory injects template data, context, and user info into workflow variables
• Result collection — execution results are fetched from N8N API and stored in results_data table
• Direct DB access — optional: query N8N's PostgreSQL for vector collections

Workflow Engine Registry

Multiple engines can be registered (N8N is primary, stubs exist for Prefect and Windmill):

workflow_registry.get_engine("n8n")       # primary engine
workflow_registry.list_all_workflows()     # across all engines

Engines are configured in the database or via environment variables.

Storage

Factory pattern abstracts MinIO (local/Docker) and Azure Blob (production):

storage = get_storage_client()              # returns MinIO or Azure client
storage.upload_file(bucket, key, data)
url = storage.get_presigned_url(bucket, key, expires=timedelta(hours=1))

14 buckets organize content: templates, presentations, images, context documents, caches, logs, workflow outputs, etc.

AI Providers

Unified interface supporting OpenAI, Azure OpenAI, Anthropic, Mistral, Ollama, OpenRouter, Cohere. Provider selection is per-request — the system auto-detects provider from model name or accepts an explicit override.

An OpenAI-compatible proxy at /v1/chat/completions lets N8N (or any OpenAI client) route through Slidefactory to any provider.

Data Flow: Full Request Lifecycle

User clicks "Generate" in SPA:

1. SPA sends POST /api/presentations/generate with JWT
2. FastAPI validates auth, creates process record in PostgreSQL
3. Task queued to Celery via Redis (process_queue)
4. Worker picks up task, triggers N8N workflow
5. N8N calls AI provider, generates content
6. N8N uploads result to MinIO/Azure, calls webhook
7. FastAPI updates process status in DB
8. SPA receives completion via SSE, fetches download URL

Package Structure

src/slidefactory/
├── app/
│   ├── main.py              # FastAPI app, router registration, lifespan
│   ├── config.py            # All env var configuration
│   ├── celery_app.py        # Celery setup
│   ├── ai/                  # AI provider abstraction + OpenAI proxy
│   ├── api/                 # REST endpoints (presentations, templates, etc.)
│   ├── auth/                # JWT, session, API key auth + user management
│   ├── context/             # RAG: documents, chunks, embeddings, vector search
│   ├── filemanager/         # Storage abstraction (MinIO/Azure) + file ops
│   ├── workflowengine/      # Engine registry + N8N/Prefect/Windmill engines
│   ├── n8nmanager/          # N8N API client + direct DB access
│   ├── scraping/            # Web scraping (Jina, Firecrawl, Google)
│   ├── results/             # Workflow result storage
│   ├── office365/           # Microsoft Graph integration
│   └── util/                # Database, Redis, logging, caching, PPT utils
├── cli/                     # CLI commands (init, user, template, presentation, ...)
└── alembic/                 # Database migrations