Supabase API Architecture - No Direct Client Calls

Overview

This document explains how the application is architected to ensure all database operations go through the backend API, not through direct Supabase client calls from the frontend.

✅ Architecture Pattern

Frontend (React)
      ↓
   API Calls (fetch)
      ↓
Backend API (Flask/Python)
      ↓
Supabase Service
      ↓
Supabase Database

🔒 Security Benefits

No Exposed Database Logic - Business logic stays on the server
Token Validation - Backend verifies auth tokens before database access
Centralized Access Control - All permissions checked in one place
Rate Limiting - Can add rate limiting at API level
Audit Logging - All database operations logged server-side
SQL Injection Prevention - Backend properly sanitizes inputs

📁 File Structure

Backend API Endpoints

/src/routes/enrollments.py - Enrollment operations
/src/routes/waitlist.py - Waitlist operations
/src/routes/content.py - Content management
/src/routes/user.py - User management

Frontend Services (API Clients)

/src/services/enrollments.js - Enrollment API calls
/src/services/waitlist.js - Waitlist API calls
/src/services/novaTracks.js - Track data API calls
/src/services/homepageContent.js - Content API calls
/src/services/footerContent.js - Footer content API calls
/src/services/marketingPages.js - Marketing pages API calls
/src/services/legalContent.js - Legal content API calls

Exception: Authentication

/src/context/AuthContext.jsx - ONLY place with direct Supabase auth calls
This is intentional - Supabase auth SDK handles sessions, OAuth, etc.
Auth operations (login, signup, logout) go directly to Supabase Auth service
Database operations still go through backend API

🚫 What to Avoid

❌ BAD - Direct Supabase Client Calls

// DON'T DO THIS
import { supabase } from '../lib/supabaseClient';

const fetchData = async () => {
  const { data } = await supabase
    .from('course_enrollments')
    .select('*')
    .eq('user_id', userId);
  
  return data;
};

✅ GOOD - API Endpoint Calls

// DO THIS INSTEAD
const fetchData = async () => {
  const token = await getAuthToken();
  
  const response = await fetch('/api/enrollments/dashboard', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
  });
  
  const data = await response.json();
  return data;
};

📋 Implementation Checklist

For Each New Feature:

Backend (Python/Flask)

Create route in /src/routes/[feature].py
Add authentication check (verify token)
Use SupabaseService for database operations
Add proper error handling
Register blueprint in main.py

Frontend (React/JavaScript)

Create service file in /src/services/[feature].js
Use fetch() to call backend API
Include auth token in headers
Handle errors properly
NO direct supabase.from() calls

🔍 How to Audit for Direct Calls

Search for Direct Supabase Usage

# Find all direct Supabase client imports
grep -r "from.*supabaseClient" src/

# Find direct database calls
grep -r "supabase\.from(" src/

# Find direct RPC calls
grep -r "supabase\.rpc(" src/

Expected Results

✅ src/context/AuthContext.jsx - Auth operations only
✅ src/lib/supabaseClient.js - Client initialization only
❌ No other files should import or use supabase client

📝 Current Implementation

Enrollments

✅ Backend: /src/routes/enrollments.py

GET /api/enrollments/dashboard - Get user dashboard
GET /api/enrollments/track/:id - Get enrollment for track
POST /api/enrollments - Enroll in track

✅ Frontend: /src/services/enrollments.js

All calls go through API endpoints
Auth token included in headers

Waitlist

✅ Backend: /src/routes/waitlist.py

GET /api/waitlist/check - Check waitlist status
POST /api/waitlist - Join waitlist
DELETE /api/waitlist - Remove from waitlist

✅ Frontend: /src/services/waitlist.js

All calls go through API endpoints

Content

✅ Backend: /src/routes/content.py

All content operations

✅ Frontend: Multiple service files

/src/services/homepageContent.js
/src/services/footerContent.js
/src/services/marketingPages.js
/src/services/legalContent.js

Tracks

✅ Backend: /src/routes/content.py (serves track data) ✅ Frontend: /src/services/novaTracks.js

🔐 Authentication Flow

1. User logs in via AuthContext
   ↓
2. Supabase Auth creates session
   ↓
3. Session token stored in browser
   ↓
4. Frontend gets token from session
   ↓
5. Frontend includes token in API requests
   ↓
6. Backend verifies token with Supabase Auth
   ↓
7. Backend performs database operations
   ↓
8. Backend returns data to frontend

Code Example

Frontend (Getting Token)

import { supabase } from '../lib/supabaseClient';

const getAuthToken = async () => {
  const { data: { session } } = await supabase.auth.getSession();
  if (!session?.access_token) {
    throw new Error('Not authenticated');
  }
  return session.access_token;
};

Backend (Verifying Token)

auth_header = request.headers.get('Authorization')
token = auth_header.replace('Bearer ', '')

user_response = supabase_service.client.auth.get_user(token)
user_id = user_response.user.id

# Now use user_id for database operations

🧪 Testing

Verify No Direct Calls

# Run this in project root
npm run check-supabase-usage

Or manually:

# Should only return AuthContext and supabaseClient
grep -r "supabase\." src/ --include="*.js" --include="*.jsx" | grep -v "auth\." | grep -v "supabaseClient.js"

Test API Endpoints

# Get auth token
TOKEN="your_token_here"

# Test dashboard
curl -H "Authorization: Bearer $TOKEN" http://localhost:5001/api/enrollments/dashboard

# Test enrollment
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"trackId":"track-id","pricingTier":"free"}' \
  http://localhost:5001/api/enrollments

📚 Benefits Summary

Aspect	Direct Supabase	Through API
Security	❌ Exposed logic	✅ Hidden logic
Scalability	❌ Hard to change	✅ Easy to modify
Monitoring	❌ Client-side only	✅ Server logging
Rate Limiting	❌ Limited	✅ Full control
Caching	❌ Browser only	✅ Server & CDN
Validation	❌ Client-side	✅ Server-side

🚀 Migration Strategy

If you find direct Supabase calls:

Identify the operation - What database table/operation?
Create backend route - Add to appropriate /src/routes/ file
Update frontend service - Change to API call
Test thoroughly - Ensure same functionality
Remove direct call - Delete old Supabase client code

📞 Questions?

If you need to add new database operations:

Start with backend API endpoint
Add authentication check
Implement database logic
Create frontend service function
Test end-to-end

Never start by adding supabase.from() calls in the frontend!

✅ Verification Checklist

All /src/services/*.js files use fetch() not supabase.from()
Only AuthContext.jsx uses supabase.auth.*
All database operations have backend API endpoints
All API calls include Authorization header
Backend verifies tokens before database access
No RLS policies bypassed
Error handling implemented end-to-end

Last Updated: October 2025 Architecture Status: ✅ All database calls through API

Overview​

✅ Architecture Pattern​

🔒 Security Benefits​

📁 File Structure​

Backend API Endpoints​

Frontend Services (API Clients)​

Exception: Authentication​

🚫 What to Avoid​

❌ BAD - Direct Supabase Client Calls​

✅ GOOD - API Endpoint Calls​

📋 Implementation Checklist​

For Each New Feature:​

Backend (Python/Flask)​

Frontend (React/JavaScript)​

🔍 How to Audit for Direct Calls​

Search for Direct Supabase Usage​

Expected Results​

📝 Current Implementation​

Enrollments​

Waitlist​

Content​

Tracks​

🔐 Authentication Flow​

Code Example​

🧪 Testing​

Verify No Direct Calls​

Test API Endpoints​

📚 Benefits Summary​

🚀 Migration Strategy​

📞 Questions?​

✅ Verification Checklist​