📋 OPINIONATED SCAFFOLD: Modern Supabase + Edge Functions stack

Default Stack:

Backend: Supabase Edge Functions (Deno runtime)

Database: Supabase PostgreSQL + Row-Level Security

Auth: Supabase Auth (JWT-based)

Storage: Supabase Storage

Email: Resend (transactional emails)

Payments: Stripe (subscriptions + one-time)

Language: TypeScript

Deployment: Git push to Supabase

To customize: Run /customize-scaffold backend or use the scaffold-customizer agent to adapt for Express, NestJS, Fastify, Django, Rails, Go, or other frameworks.

Backend Development Guidelines

Purpose

Establish consistency and best practices for Supabase-powered backends using Edge Functions, PostgreSQL with Row-Level Security, and TypeScript. This skill covers database design, authentication flows, API patterns, email integration, and payment processing.

When to Use This Skill

Automatically activates when working on:

Creating or modifying Supabase Edge Functions
Designing PostgreSQL database schemas
Implementing Row-Level Security (RLS) policies
Building authentication flows with Supabase Auth
Integrating Supabase Storage for file uploads
Sending transactional emails with Resend
Processing payments with Stripe
Input validation with Zod
Testing with Supabase CLI
Backend deployment and configuration

Quick Start

New Edge Function Checklist

Function: Create in supabase/functions/[name]/index.ts
Validation: Zod schema for input
Auth: JWT verification with Supabase client
Database: Use Supabase client with RLS
Error handling: Try/catch with proper responses
CORS: Configure allowed origins
Tests: Local testing with Supabase CLI
Deploy: supabase functions deploy [name]

New Feature Checklist

Database: Create migration with schema changes
RLS: Add appropriate security policies
Edge Function: Implement API endpoint
Frontend Integration: Update Supabase client calls
Testing: Test locally before deploy
Monitoring: Check logs after deployment

Architecture Overview

Supabase Stack Architecture

HTTP Request
    ↓
Edge Function (Deno runtime)
    ↓
Supabase Client (Auth + validation)
    ↓
PostgreSQL Database (with RLS)
    ↓
Response with JSON

Key Principle: Edge Functions are stateless, RLS enforces data security.

Integrations:

Supabase Auth → JWT-based authentication
Supabase Storage → File uploads and CDN
Supabase Realtime → WebSocket subscriptions
Resend → Transactional emails
Stripe → Payment processing

See architecture-overview.md for complete details.

Directory Structure

project/
├── supabase/
│   ├── functions/           # Edge Functions
│   │   ├── create-user/
│   │   │   └── index.ts
│   │   ├── send-email/
│   │   │   └── index.ts
│   │   └── process-payment/
│   │       └── index.ts
│   ├── migrations/          # Database migrations
│   │   ├── 001_initial_schema.sql
│   │   ├── 002_add_rls.sql
│   │   └── 003_add_indexes.sql
│   ├── seed.sql             # Test data
│   └── config.toml          # Supabase config
├── lib/
│   └── supabase/
│       ├── client.ts        # Supabase client setup
│       ├── auth.ts          # Auth utilities
│       └── types.ts         # Database types
└── types/
    └── database.types.ts    # Generated from schema

Naming Conventions:

Edge Functions: kebab-case - create-user, send-email
Database tables: snake_case - user_profiles, subscription_plans
RLS policies: snake_case - users_select_own, posts_insert_authenticated
TypeScript types: PascalCase - UserProfile, SubscriptionPlan

Core Principles (7 Key Rules)

1. Edge Functions are Simple and Focused

// ❌ NEVER: 500-line Edge Function
Deno.serve(async (req) => {
    // Massive logic...
});

// ✅ ALWAYS: Focused, single-purpose functions
Deno.serve(async (req) => {
    const user = await getUserFromRequest(req);
    const result = await createPost(user.id, req);
    return new Response(JSON.stringify(result), { status: 201 });
});

2. Always Verify JWT Tokens

import { createClient } from '@supabase/supabase-js';

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

const { data: { user }, error } = await supabase.auth.getUser();
if (error || !user) {
    return new Response('Unauthorized', { status: 401 });
}

3. Use RLS for Data Security

-- Enable RLS on all tables
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- Users can only read their own data
CREATE POLICY "users_select_own" ON posts
    FOR SELECT
    USING (auth.uid() = user_id);

-- Users can only insert their own data
CREATE POLICY "posts_insert_own" ON posts
    FOR INSERT
    WITH CHECK (auth.uid() = user_id);

4. Validate All Input with Zod

import { z } from 'zod';

const CreatePostSchema = z.object({
    title: z.string().min(1).max(200),
    content: z.string().min(1),
    tags: z.array(z.string()).optional()
});

const body = await req.json();
const validated = CreatePostSchema.parse(body); // Throws if invalid

5. Use Environment Variables via Deno.env

// ❌ NEVER: Hardcode secrets
const apiKey = 'sk_live_abc123';

// ✅ ALWAYS: Use environment variables
const apiKey = Deno.env.get('STRIPE_API_KEY')!;
const resendKey = Deno.env.get('RESEND_API_KEY')!;

6. Handle Errors Gracefully

try {
    const result = await performOperation();
    return new Response(JSON.stringify({ success: true, data: result }), {
        status: 200,
        headers: { 'Content-Type': 'application/json' }
    });
} catch (error) {
    console.error('Operation failed:', error);
    return new Response(JSON.stringify({
        success: false,
        error: error.message
    }), {
        status: 500,
        headers: { 'Content-Type': 'application/json' }
    });
}

7. Test Locally Before Deploying

# Start Supabase locally
supabase start

# Test Edge Function locally
supabase functions serve create-user --env-file .env.local

# Run tests
curl -i http://localhost:54321/functions/v1/create-user \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"email":"test@example.com"}'

Common Imports

// Supabase
import { createClient } from '@supabase/supabase-js';
import type { Database } from '../types/database.types.ts';

// Validation
import { z } from 'zod';

// Email (Resend)
import { Resend } from 'resend';

// Payments (Stripe)
import Stripe from 'stripe';

// CORS helper
import { corsHeaders } from '../_shared/cors.ts';

Quick Reference

HTTP Status Codes

Code	Use Case
200	Success
201	Created
204	No Content (DELETE success)
400	Bad Request (validation error)
401	Unauthorized (no/invalid token)
403	Forbidden (valid token, no permission)
404	Not Found
500	Server Error

Common Edge Function Patterns

Auth Check → Verify JWT, get user CRUD Operations → Create, Read, Update, Delete with RLS Email Sending → Resend integration Payment Processing → Stripe webhooks and charges File Upload → Supabase Storage integration

Anti-Patterns to Avoid

❌ Skipping JWT verification ❌ Querying database without RLS ❌ No input validation ❌ Exposing secrets in code ❌ Missing error handling ❌ Deploying without local testing ❌ Direct database access (bypassing RLS) ❌ console.log for production errors (use proper logging)

Example Resource Files

📝 Note: This is a scaffold skill with example resources. The provided resources demonstrate the pattern - you should generate additional resources as needed for your specific project.

✅ Provided Examples

architecture-overview.md - Complete Supabase stack architecture edge-functions-guide.md - Edge Function patterns and deployment database-and-rls.md - Database design and RLS policies

📋 Generate On-Demand

When you need guidance on a specific topic, ask Claude to generate a resource file following the same pattern as the examples above. Common topics:

Validation patterns - Zod schemas and error handling
Auth patterns - JWT verification, session management
Storage patterns - File uploads, CDN, signed URLs
Email integration - Resend templates and sending
Stripe integration - Payments, subscriptions, webhooks
Testing guide - Local testing, integration tests
Complete examples - Full working Edge Function examples

How to request: "Generate a resource file for [topic] following the pattern in architecture-overview.md"

Customization Instructions

For Your Tech Stack

Not using Supabase? Use the scaffold-customizer agent or manual replacement:

# Option 1: Automated
# Claude will detect your stack and offer to customize

# Option 2: Manual find-and-replace
Supabase → Your database (Prisma, TypeORM, etc.)
Edge Functions → Your backend (Express, NestJS, etc.)
PostgreSQL → Your database (MySQL, MongoDB, etc.)
RLS → Your auth strategy

For Your Domain

Replace the generic examples with your domain:

Update "posts" table → your entities
Update "users" → your user model
Update business logic examples

For Your Patterns

Adapt the principles to your architecture:

Keep security-first approach
Keep validation patterns
Keep error handling patterns
Adjust structure to your needs

Related Skills

frontend-dev-guidelines - Next.js + React patterns for Supabase integration
memory-management - Track architectural decisions
skill-developer - Meta-skill for creating and managing skills

Skill Status: SCAFFOLD ✅ Line Count: < 500 ✅ Progressive Disclosure: Example resources + generation instructions ✅

backend-dev-guidelines