backend-dev-guidelines

📋 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 ✅