Quick Start Guide

Quick Start with Supabase

This guide will help you set up Supabase for your AIMatrix project in under 30 minutes, covering all essential components needed for AI-powered applications.

Prerequisites

  • Node.js 16+ installed
  • A Supabase account (free tier available)
  • Basic knowledge of JavaScript/TypeScript
  • Git for version control

Step 1: Project Setup

Create Supabase Project

  1. Visit supabase.com and sign in
  2. Click “New Project”
  3. Choose your organization
  4. Fill in project details:
    • Name: aimatrix-platform
    • Database Password: Generate a strong password
    • Region: Choose closest to your users
    • Pricing Plan: Start with Free tier

Install Supabase CLI 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Install Supabase CLI
npm install -g supabase

# Login to Supabase
supabase login

# Initialize project locally
mkdir aimatrix-supabase
cd aimatrix-supabase
supabase init

Connect to Remote Project 

1
2
3
4
5

# Link to your remote project
supabase link --project-ref your-project-ref

# Pull remote schema
supabase db pull

Step 2: Database Schema Design

Create Core Tables 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

-- Enable necessary extensions
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "vector";

-- Organizations table for multi-tenancy
CREATE TABLE organizations (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name TEXT NOT NULL,
    slug TEXT UNIQUE NOT NULL,
    settings JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enhanced users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email TEXT UNIQUE NOT NULL,
    full_name TEXT,
    avatar_url TEXT,
    organization_id UUID REFERENCES organizations(id),
    role TEXT DEFAULT 'member' CHECK (role IN ('admin', 'member', 'viewer')),
    preferences JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- AI Agents table
CREATE TABLE ai_agents (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    organization_id UUID REFERENCES organizations(id) NOT NULL,
    name TEXT NOT NULL,
    description TEXT,
    type TEXT NOT NULL CHECK (type IN ('assistant', 'analyst', 'automation', 'monitoring')),
    config JSONB NOT NULL DEFAULT '{}',
    status TEXT DEFAULT 'inactive' CHECK (status IN ('active', 'inactive', 'error')),
    created_by UUID REFERENCES users(id),
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Knowledge base for RAG
CREATE TABLE knowledge_base (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    organization_id UUID REFERENCES organizations(id) NOT NULL,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    metadata JSONB DEFAULT '{}',
    embedding VECTOR(1536), -- OpenAI embedding dimension
    source_url TEXT,
    created_by UUID REFERENCES users(id),
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Agent conversations
CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    organization_id UUID REFERENCES organizations(id) NOT NULL,
    agent_id UUID REFERENCES ai_agents(id),
    user_id UUID REFERENCES users(id),
    title TEXT,
    context JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Messages table
CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    conversation_id UUID REFERENCES conversations(id) NOT NULL,
    role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
    content TEXT NOT NULL,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create indexes for performance
CREATE INDEX idx_knowledge_base_embedding ON knowledge_base USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
CREATE INDEX idx_messages_conversation_id ON messages(conversation_id);
CREATE INDEX idx_conversations_organization_id ON conversations(organization_id);
CREATE INDEX idx_ai_agents_organization_id ON ai_agents(organization_id);
CREATE INDEX idx_users_organization_id ON users(organization_id);

Save this as supabase/migrations/001_initial_schema.sql and run:

1

supabase db push

Step 3: Authentication Configuration

Set up Auth Providers

In your Supabase dashboard:

  1. Go to Authentication > Settings
  2. Configure Site URL: http://localhost:3000 (development)
  3. Add redirect URLs for production
  4. Enable desired providers:
1
2
3
4
5
6
7

{
  "SITE_URL": "https://your-app.com",
  "REDIRECT_URLS": [
    "http://localhost:3000/auth/callback",
    "https://your-app.com/auth/callback"
  ]
}

Enable Social Authentication 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// OAuth providers configuration
const authConfig = {
  google: {
    enabled: true,
    client_id: "your-google-client-id"
  },
  github: {
    enabled: true,
    client_id: "your-github-client-id"
  },
  microsoft: {
    enabled: true,
    client_id: "your-microsoft-client-id"
  }
}

Row Level Security (RLS) 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

-- Enable RLS on all tables
ALTER TABLE organizations ENABLE ROW LEVEL SECURITY;
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE ai_agents ENABLE ROW LEVEL SECURITY;
ALTER TABLE knowledge_base ENABLE ROW LEVEL SECURITY;
ALTER TABLE conversations ENABLE ROW LEVEL SECURITY;
ALTER TABLE messages ENABLE ROW LEVEL SECURITY;

-- Create policies for multi-tenant access
CREATE POLICY "Users can view their own organization" ON organizations
    FOR SELECT USING (
        auth.uid() IN (
            SELECT id FROM users WHERE organization_id = organizations.id
        )
    );

CREATE POLICY "Users can view organization members" ON users
    FOR SELECT USING (
        organization_id = (
            SELECT organization_id FROM users WHERE id = auth.uid()
        )
    );

-- Agent access policies
CREATE POLICY "Users can manage organization agents" ON ai_agents
    FOR ALL USING (
        organization_id = (
            SELECT organization_id FROM users WHERE id = auth.uid()
        )
    );

-- Knowledge base policies  
CREATE POLICY "Users can access organization knowledge" ON knowledge_base
    FOR ALL USING (
        organization_id = (
            SELECT organization_id FROM users WHERE id = auth.uid()
        )
    );

Step 4: Storage Setup

Configure Storage Buckets 

1
2
3
4
5
6

-- Create storage buckets
INSERT INTO storage.buckets (id, name, public)
VALUES 
  ('avatars', 'avatars', true),
  ('documents', 'documents', false),
  ('agent-assets', 'agent-assets', false);

Storage Policies 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

-- Avatar policies
CREATE POLICY "Users can upload their own avatar" ON storage.objects
    FOR INSERT WITH CHECK (bucket_id = 'avatars' AND auth.uid()::text = (storage.foldername(name))[1]);

CREATE POLICY "Anyone can view avatars" ON storage.objects
    FOR SELECT USING (bucket_id = 'avatars');

-- Document policies
CREATE POLICY "Users can manage organization documents" ON storage.objects
    FOR ALL USING (
        bucket_id = 'documents' AND
        (storage.foldername(name))[1] = (
            SELECT organization_id::text FROM users WHERE id = auth.uid()
        )
    );

Step 5: Real-time Configuration

Enable Real-time 

1
2
3
4

-- Enable real-time for tables
ALTER publication supabase_realtime ADD TABLE messages;
ALTER publication supabase_realtime ADD TABLE conversations;
ALTER publication supabase_realtime ADD TABLE ai_agents;

Real-time Policies 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

-- Real-time policies
CREATE POLICY "Users can listen to organization messages" ON messages
    FOR SELECT USING (
        conversation_id IN (
            SELECT id FROM conversations 
            WHERE organization_id = (
                SELECT organization_id FROM users WHERE id = auth.uid()
            )
        )
    );

Step 6: Edge Functions Setup

Create Edge Function 

1
2
3
4
5
6

# Create edge function for AI integration
supabase functions new ai-chat

# Install dependencies
cd supabase/functions/ai-chat
echo '{"imports": {"https://deno.land/x/supabase@1.0.0/mod.ts": "https://deno.land/x/supabase@1.0.0/mod.ts"}}' > import_map.json

Basic AI Chat Function 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

// supabase/functions/ai-chat/index.ts
import { serve } from "https://deno.land/std@0.177.0/http/server.ts"
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2.38.4'

const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
}

serve(async (req) => {
  if (req.method === 'OPTIONS') {
    return new Response('ok', { headers: corsHeaders })
  }

  try {
    const supabaseClient = createClient(
      Deno.env.get('SUPABASE_URL') ?? '',
      Deno.env.get('SUPABASE_ANON_KEY') ?? '',
      { global: { headers: { Authorization: req.headers.get('Authorization')! } } }
    )

    const { conversation_id, message } = await req.json()

    // Get user from JWT
    const { data: { user } } = await supabaseClient.auth.getUser()
    
    if (!user) {
      return new Response('Unauthorized', { status: 401, headers: corsHeaders })
    }

    // Save user message
    const { data: userMessage } = await supabaseClient
      .from('messages')
      .insert({
        conversation_id,
        role: 'user',
        content: message
      })
      .select()
      .single()

    // TODO: Add AI processing here
    const aiResponse = "I'm an AI assistant ready to help!"

    // Save AI response
    const { data: aiMessage } = await supabaseClient
      .from('messages')
      .insert({
        conversation_id,
        role: 'assistant',
        content: aiResponse
      })
      .select()
      .single()

    return new Response(
      JSON.stringify({ success: true, message: aiMessage }),
      { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
    )

  } catch (error) {
    return new Response(
      JSON.stringify({ error: error.message }),
      { headers: { ...corsHeaders, 'Content-Type': 'application/json' }, status: 500 }
    )
  }
})

Deploy Edge Function 

1

supabase functions deploy ai-chat --no-verify-jwt

Step 7: Client Integration

Install Client Libraries 

1
2

npm install @supabase/supabase-js
npm install @supabase/auth-helpers-nextjs # if using Next.js

Initialize Client 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!

export const supabase = createClient(supabaseUrl, supabaseAnonKey)

// Database types (auto-generated)
export type Database = {
  public: {
    Tables: {
      organizations: {
        Row: {
          id: string
          name: string
          slug: string
          settings: any
          created_at: string
          updated_at: string
        }
        Insert: {
          id?: string
          name: string
          slug: string
          settings?: any
          created_at?: string
          updated_at?: string
        }
        Update: {
          id?: string
          name?: string
          slug?: string
          settings?: any
          updated_at?: string
        }
      }
      // ... other table types
    }
  }
}

Environment Variables 

1
2
3
4

# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Step 8: Basic Usage Examples

Authentication 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// Sign up
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'password123',
  options: {
    data: {
      full_name: 'John Doe'
    }
  }
})

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'password123'
})

// OAuth sign in
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: `${window.location.origin}/auth/callback`
  }
})

Database Operations 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// Create organization and user
const createOrganization = async (name: string, userEmail: string) => {
  const { data: org } = await supabase
    .from('organizations')
    .insert({ name, slug: name.toLowerCase().replace(/\s+/g, '-') })
    .select()
    .single()

  const { data: user } = await supabase
    .from('users')
    .update({ organization_id: org.id })
    .eq('email', userEmail)
    .select()
    .single()

  return { org, user }
}

// Create AI agent
const createAgent = async (name: string, type: string, config: any) => {
  const { data } = await supabase
    .from('ai_agents')
    .insert({
      name,
      type,
      config,
      organization_id: user.organization_id
    })
    .select()
    .single()

  return data
}

Real-time Subscriptions 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// Subscribe to new messages
const subscribeToMessages = (conversationId: string) => {
  return supabase
    .channel('messages')
    .on('postgres_changes', 
      { 
        event: 'INSERT', 
        schema: 'public', 
        table: 'messages',
        filter: `conversation_id=eq.${conversationId}`
      }, 
      (payload) => {
        console.log('New message:', payload.new)
      }
    )
    .subscribe()
}

Next Steps

Now that you have Supabase set up, explore these advanced topics:

  1. Authentication - Implement advanced auth patterns
  2. Real-time Features - Build collaborative experiences
  3. Vector AI - Add semantic search and RAG
  4. Edge Functions - Create serverless AI endpoints
  5. Storage & CDN - Handle files and media
  6. Monitoring - Set up production monitoring

Troubleshooting

Common Issues

Connection Issues

1
2
3
4
5

# Check connection
supabase status

# Reset local database
supabase db reset

RLS Policies Not Working

  • Ensure RLS is enabled on tables
  • Check policy conditions match your use case
  • Test policies with different user contexts

Edge Functions Timeout

  • Check function logs: supabase functions logs ai-chat
  • Increase timeout in function config
  • Optimize database queries

Getting Help

Your Supabase setup is now ready for building AI-powered applications with AIMatrix!