Skip to main content

Supabase

Supabase is the foundational layer of the NearSync platform. Every app in the platform -- admin dashboard, client portal, and marketing website -- connects to Supabase for data storage, user authentication, file handling, server-side logic, and live updates.

What Supabase Provides​

PostgreSQL Database​

NearSync stores all application data in a PostgreSQL database managed by Supabase. This includes CRM records, HR data, finance transactions, project information, AI configuration, and system settings.

Row-Level Security (RLS) policies enforce data isolation at the database level. In multi-tenant Managed deployments, RLS ensures each organization can only access its own data. In BYOK deployments, the client has their own dedicated Supabase project.

Authentication​

Supabase Auth handles all user authentication across the platform:

  • Email/password login with configurable password policies
  • Magic link (passwordless) login via email
  • Multi-factor authentication (MFA) support, configurable per-organization via the system manifest
  • JWT-based sessions that work across subdomains (admin, portal, marketing)
  • Role-based access control (RBAC) using custom claims and the app_roles, app_permissions, and role_permissions tables

Session tokens are stored in chunked cookies scoped to the root domain, enabling seamless cross-subdomain authentication between the admin dashboard and client portal without requiring users to log in again.

Storage​

Supabase Storage manages file uploads throughout the platform:

  • Brand assets (logos, favicons) uploaded through the Design Studio
  • Document attachments on projects, invoices, and contracts
  • Profile images and organizational media
  • Generated exports (PDFs, reports)

Storage buckets are configured with appropriate access policies so that files respect the same organizational boundaries as the database.

Edge Functions​

NearSync's server-side logic runs on Supabase Edge Functions. The primary edge function, called the hyper-worker, is a unified request router that handles:

  • AI service requests (chat completions, embeddings, RAG queries)
  • Email delivery (transactional notifications via Resend)
  • Voice token generation (Twilio WebRTC tokens)
  • WhatsApp message sending and webhook processing
  • Document generation (contracts, invoices via Google Docs templates)
  • Payment processing (Stripe, Razorpay)
  • CRM sync operations (HubSpot, Salesforce)
  • Booking management (calendar events, availability checks)

Additional edge functions handle OAuth callback flows for integrations like Canva, HubSpot, and Salesforce.

Realtime​

Supabase Realtime powers live features across the platform:

  • Notifications that appear without page refresh
  • Live data updates when multiple users are working in the same module
  • Status changes that propagate immediately (deal stage changes, approval decisions)

The platform subscribes to Realtime channels for tables where live updates improve the user experience, while using standard polling for less time-sensitive data.

Client Configuration​

NearSync uses two Supabase client instances:

  1. Public client (anon key): Used by the browser. All requests go through RLS policies, so the client can only read and write data the current user is authorized to access.
  2. Service role client: Used exclusively by edge functions for administrative operations that need to bypass RLS (sending emails on behalf of users, processing webhooks, running scheduled jobs).

The public client is initialized in the @nearsync/supabase-client package and shared across all apps. It handles session management, token refresh, and the cookie-based storage strategy for cross-domain auth.

Credentials Required​

To connect a NearSync instance to Supabase, you need:

  • Project URL -- The base URL of your Supabase project
  • Anon (public) key -- The public API key used by browser clients (safe to expose, protected by RLS)
  • Service role key -- The privileged API key used by edge functions (must remain secret, never exposed to browsers)

For Managed deployments, NearSync provisions and manages these credentials. For BYOK deployments, these are provided during the setup process in the client portal.

If Supabase Is Unavailable​

Supabase is a critical-path dependency. If it goes down:

  • The entire application is non-functional (no auth, no data, no backend operations)
  • The frontend will render a minimal UI with styled warnings indicating the service is unavailable
  • No data operations are possible until the connection is restored

Supabase Pro tier provides a 99.9% uptime SLA. NearSync monitors Supabase health as part of its operational monitoring.