Supabase¶

The Supabase module integrates Supabase as a full infrastructure backend for Deepstaging applications. It provides authentication, file storage, database connectivity, realtime subscriptions, and vector search — all wired through the standard Deepstaging interfaces.

Complements, doesn't replace

Supabase provides the infrastructure (auth, storage, database). Deepstaging provides the application framework (effects, dispatch, event sourcing). They work together — Supabase handles what's below the API, Deepstaging handles what's above it.

Modules¶

Module	Provides	Interface
Authentication	GoTrue-backed user resolution and auth operations	`IUserContext`, `ISupabaseAuth`
File Storage	Supabase Storage-backed file and bucket operations	`IFileStore`, `ISupabaseStorage`
Database	Managed PostgreSQL with connection pooling	`DbContext` / connection string
Realtime	WebSocket subscriptions and declarative event handlers	`SupabaseRealtimeClient`, `ISupabaseRealtime`
Vector Search	pgvector-backed similarity search	`IVectorIndex<T>`

Installation¶

Add the NuGet packages:

# Runtime module
dotnet add package Deepstaging.Supabase

# Realtime source generator (optional)
dotnet add package Deepstaging.Supabase.Generators

Configuration¶

All modules share a common SupabaseOptions section:

appsettings.json

{
  "Deepstaging": {
    "Supabase": {
      "ProjectUrl": "https://your-project.supabase.co",
      "AnonKey": "eyJ...",
      "ServiceRoleKey": "eyJ..."
    }
  }
}

Protect your keys

AnonKey is safe for client-side use (with RLS enabled). ServiceRoleKey bypasses Row Level Security and must be kept secret. Use user-secrets or environment variables in production.

Each sub-module adds its own configuration section under Deepstaging:Supabase (e.g., Database, Realtime, Vectors).

Effects Composition¶

Supabase modules integrate with the Deepstaging effects system at two levels:

Standard interfaces — AuthModule, StorageModule, VectorModule<T> wrap the generic Deepstaging interfaces (IUserContext, IFileStore, IVectorIndex<T>). These work with any provider.

Supabase-specific effects — SupabaseAuthModule, SupabaseStorageModule, SupabaseRealtimeModule expose the full Supabase API surface as effects. Use these when you need Supabase-specific operations like OTP, MFA, buckets, or broadcast.

using Deepstaging.Effects;
using Deepstaging.Search;
using Deepstaging.Storage;
using Deepstaging.Web.Auth;
using Deepstaging.Supabase.Auth;
using Deepstaging.Supabase.Storage;
using Deepstaging.Supabase.Realtime;

// Standard interfaces — provider-agnostic
[EffectsModule(typeof(AuthModule))]
[EffectsModule(typeof(StorageModule))]
[EffectsModule(typeof(VectorModule<Document>))]

// Supabase-specific operations
[EffectsModule(typeof(SupabaseAuthModule))]
[EffectsModule(typeof(SupabaseStorageModule))]
[EffectsModule(typeof(SupabaseRealtimeModule))]
public partial class AppModule;

[Runtime]
[Uses(typeof(AppModule))]
public partial class AppRuntime;

Register Supabase as the backing provider:

builder.AddAppRuntime(options =>
{
    options
        .AddSupabaseAuth()
        .AddSupabaseAuthOperations()
        .AddSupabaseFileStore(bucketId: "uploads")
        .AddSupabaseStorageOperations()
        .AddSupabaseDatabase<AppRuntime, AppDbContext>()
        .AddSupabaseRealtime()
        .AddSupabaseVectorIndex<AppRuntime, Document>();
});

Registration¶

Each method is independent — register only the modules you need.