SaaS Architect - Next.js + Supabase Edition

Purpose

This skill transforms SaaS ideas into executable technical architectures optimized for Next.js 15 + Supabase stack. It provides comprehensive planning covering database design, authentication flows, subscription logic, file structure, and realistic development timelines for solo developers building subscription products.

Core Philosophy

1. Subscription-First Architecture

• Design for recurring revenue from day one

• Plan for multiple pricing tiers

• Build upgrade/downgrade flows early

• Consider trial periods and grace periods

2. Multi-Tenant by Default

• Row Level Security (RLS) is mandatory

• Organizations/Teams structure built-in

• User roles and permissions from start

• Data isolation is non-negotiable

3. Next.js 15 + Supabase Optimized

• Use Server Components for data fetching

• Leverage Server Actions for mutations

• Utilize Supabase's built-in features (Auth, Storage, Realtime)

• Minimize custom backend code

4. Production-Ready from Start

• Security considerations upfront

• Scalability patterns built-in

• Monitoring and error tracking planned

• Deployment strategy defined

How This Skill Works

Phase 1: SaaS Product Definition

1.1 Core Value Proposition

Product Name: [Name] One-Line Pitch: [What it does in one sentence] Target Market: [Who pays for this] Primary Use Case: [Main problem solved] Success Metric: [How you measure value]

1.2 Revenue Model

Pricing Strategy: [Freemium / Trial / Pay-to-start] Tiers: [How many pricing tiers] Key Differentiators: [What makes higher tiers worth it] Billing Cycle: [Monthly / Annual / Both]

Example (Project Management SaaS):

Product Name: TaskFlow One-Line Pitch: Project management for distributed teams with AI-powered task prioritization Target Market: Remote teams, 10-50 employees, tech companies Primary Use Case: Coordinate async work across timezones Success Metric: Teams complete 30% more tasks on time

Pricing Strategy: Freemium with 14-day trial on paid plans Tiers:

• Free: 1 project, 5 users, basic features
• Pro ($29/mo): Unlimited projects, 25 users, AI features
• Enterprise ($99/mo): Unlimited users, advanced integrations, priority support Key Differentiators:
• Pro: AI task prioritization, integrations
• Enterprise: SSO, custom workflows, dedicated support Billing Cycle: Monthly + Annual (2 months free)

Phase 2: Technical Architecture Planning

2.1 Database Schema Design

The skill generates complete PostgreSQL schemas with RLS policies:

Core Tables for Every SaaS:

-- ============================================ -- USERS & AUTHENTICATION -- ============================================ -- Note: Supabase Auth handles auth.users table -- We extend it with profiles

CREATE TABLE profiles ( id UUID REFERENCES auth.users PRIMARY KEY, email TEXT NOT NULL, full_name TEXT, avatar_url TEXT, created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() );

-- RLS Policies ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view own profile" ON profiles FOR SELECT USING (auth.uid() = id);

CREATE POLICY "Users can update own profile" ON profiles FOR UPDATE USING (auth.uid() = id);

-- ============================================ -- ORGANIZATIONS (Multi-Tenant Core) -- ============================================ CREATE TABLE organizations ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), name TEXT NOT NULL, slug TEXT UNIQUE NOT NULL, logo_url TEXT, subscription_tier TEXT DEFAULT 'free', subscription_status TEXT DEFAULT 'active', trial_ends_at TIMESTAMPTZ, created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() );

ALTER TABLE organizations ENABLE ROW LEVEL SECURITY;

-- ============================================ -- ORGANIZATION MEMBERS (Team Management) -- ============================================ CREATE TYPE member_role AS ENUM ('owner', 'admin', 'member');

CREATE TABLE organization_members ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE, user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE, role member_role DEFAULT 'member', invited_by UUID REFERENCES auth.users(id), joined_at TIMESTAMPTZ DEFAULT NOW(), UNIQUE(organization_id, user_id) );

ALTER TABLE organization_members ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Members can view own org members" ON organization_members FOR SELECT USING ( organization_id IN ( SELECT organization_id FROM organization_members WHERE user_id = auth.uid() ) );

-- ============================================ -- STRIPE INTEGRATION (Subscriptions) -- ============================================ CREATE TABLE customers ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE, stripe_customer_id TEXT UNIQUE, email TEXT, created_at TIMESTAMPTZ DEFAULT NOW() );

CREATE TABLE products ( id TEXT PRIMARY KEY, -- Stripe product ID active BOOLEAN DEFAULT true, name TEXT NOT NULL, description TEXT, image TEXT, metadata JSONB, created_at TIMESTAMPTZ DEFAULT NOW() );

CREATE TABLE prices ( id TEXT PRIMARY KEY, -- Stripe price ID product_id TEXT REFERENCES products(id), active BOOLEAN DEFAULT true, currency TEXT DEFAULT 'usd', type TEXT CHECK (type IN ('one_time', 'recurring')), unit_amount BIGINT, interval TEXT CHECK (interval IN ('day', 'week', 'month', 'year')), interval_count INTEGER, trial_period_days INTEGER, metadata JSONB, created_at TIMESTAMPTZ DEFAULT NOW() );

CREATE TABLE subscriptions ( id TEXT PRIMARY KEY, -- Stripe subscription ID organization_id UUID REFERENCES organizations(id), customer_id TEXT REFERENCES customers(stripe_customer_id), status TEXT NOT NULL, price_id TEXT REFERENCES prices(id), quantity INTEGER, cancel_at_period_end BOOLEAN DEFAULT false, current_period_start TIMESTAMPTZ, current_period_end TIMESTAMPTZ, trial_start TIMESTAMPTZ, trial_end TIMESTAMPTZ, canceled_at TIMESTAMPTZ, ended_at TIMESTAMPTZ, created_at TIMESTAMPTZ DEFAULT NOW() );

-- RLS for subscription data ALTER TABLE customers ENABLE ROW LEVEL SECURITY; ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Org owners can view own subscription" ON subscriptions FOR SELECT USING ( organization_id IN ( SELECT organization_id FROM organization_members WHERE user_id = auth.uid() AND role IN ('owner', 'admin') ) );

-- ============================================ -- FEATURE-SPECIFIC TABLES -- ============================================ -- This section is customized based on your SaaS features -- Example: Project Management SaaS

CREATE TABLE projects ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE, name TEXT NOT NULL, description TEXT, status TEXT DEFAULT 'active', created_by UUID REFERENCES auth.users(id), created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() );

ALTER TABLE projects ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Org members can view org projects" ON projects FOR SELECT USING ( organization_id IN ( SELECT organization_id FROM organization_members WHERE user_id = auth.uid() ) );

CREATE POLICY "Org members can create projects" ON projects FOR INSERT WITH CHECK ( organization_id IN ( SELECT organization_id FROM organization_members WHERE user_id = auth.uid() ) );

CREATE TABLE tasks ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), project_id UUID REFERENCES projects(id) ON DELETE CASCADE, title TEXT NOT NULL, description TEXT, status TEXT DEFAULT 'todo', priority TEXT DEFAULT 'medium', assigned_to UUID REFERENCES auth.users(id), due_date TIMESTAMPTZ, created_by UUID REFERENCES auth.users(id), created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() );

ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Org members can view org tasks" ON tasks FOR SELECT USING ( project_id IN ( SELECT id FROM projects WHERE organization_id IN ( SELECT organization_id FROM organization_members WHERE user_id = auth.uid() ) ) );

2.2 Next.js File Structure

The skill generates production-ready file structures:

your-saas-app/ ├── app/ │ ├── (auth)/ # Auth layout group │ │ ├── login/ │ │ │ └── page.tsx # Login page │ │ ├── signup/ │ │ │ └── page.tsx # Signup page │ │ ├── forgot-password/ │ │ │ └── page.tsx │ │ └── layout.tsx # Auth pages layout │ │ │ ├── (dashboard)/ # Protected dashboard routes │ │ ├── layout.tsx # Dashboard shell (sidebar, nav) │ │ ├── page.tsx # Dashboard home │ │ │ │ │ ├── [orgSlug]/ # Organization-specific routes │ │ │ ├── projects/ │ │ │ │ ├── page.tsx # Projects list │ │ │ │ ├── [id]/ │ │ │ │ │ └── page.tsx # Single project view │ │ │ │ └── new/ │ │ │ │ └── page.tsx # Create project │ │ │ │ │ │ │ ├── tasks/ │ │ │ │ ├── page.tsx │ │ │ │ └── [id]/page.tsx │ │ │ │ │ │ │ ├── team/ │ │ │ │ ├── page.tsx # Team members │ │ │ │ └── invite/page.tsx # Invite flow │ │ │ │ │ │ │ └── settings/ │ │ │ ├── page.tsx # Org settings │ │ │ ├── billing/ │ │ │ │ └── page.tsx # Subscription management │ │ │ └── members/ │ │ │ └── page.tsx # Member management │ │ │ │ │ └── onboarding/ # Post-signup onboarding │ │ ├── page.tsx │ │ └── create-org/page.tsx │ │ │ ├── (marketing)/ # Public pages │ │ ├── page.tsx # Landing page │ │ ├── pricing/ │ │ │ └── page.tsx # Pricing page │ │ ├── about/ │ │ │ └── page.tsx │ │ └── layout.tsx # Marketing layout │ │ │ ├── api/ # API routes │ │ ├── stripe/ │ │ │ ├── checkout/ │ │ │ │ └── route.ts # Create checkout session │ │ │ ├── portal/ │ │ │ │ └── route.ts # Customer portal │ │ │ └── webhook/ │ │ │ └── route.ts # Stripe webhooks │ │ │ │ │ └── webhooks/ │ │ └── supabase/ │ │ └── route.ts # Supabase webhooks │ │ │ ├── globals.css │ └── layout.tsx # Root layout │ ├── components/ │ ├── ui/ # shadcn/ui components │ │ ├── button.tsx │ │ ├── card.tsx │ │ ├── dialog.tsx │ │ ├── dropdown-menu.tsx │ │ ├── form.tsx │ │ ├── input.tsx │ │ ├── table.tsx │ │ └── ... │ │ │ ├── layouts/ │ │ ├── dashboard-shell.tsx # Dashboard wrapper │ │ ├── marketing-header.tsx │ │ └── marketing-footer.tsx │ │ │ ├── auth/ │ │ ├── login-form.tsx │ │ ├── signup-form.tsx │ │ └── auth-guard.tsx # Protected route wrapper │ │ │ ├── billing/ │ │ ├── pricing-card.tsx │ │ ├── subscription-status.tsx │ │ └── usage-meter.tsx │ │ │ ├── organizations/ │ │ ├── org-switcher.tsx # Switch between orgs │ │ ├── org-selector.tsx │ │ └── invite-member-dialog.tsx │ │ │ └── features/ # Feature-specific components │ ├── projects/ │ │ ├── project-list.tsx │ │ ├── project-card.tsx │ │ └── create-project-dialog.tsx │ └── tasks/ │ ├── task-list.tsx │ ├── task-card.tsx │ └── task-form.tsx │ ├── lib/ │ ├── supabase/ │ │ ├── client.ts # Browser client │ │ ├── server.ts # Server client │ │ ├── middleware.ts # Auth middleware │ │ └── types.ts # Generated types │ │ │ ├── stripe/ │ │ ├── client.ts # Stripe initialization │ │ ├── products.ts # Product/price helpers │ │ └── webhooks.ts # Webhook handlers │ │ │ ├── hooks/ │ │ ├── use-user.ts # Get current user │ │ ├── use-organization.ts # Get current org │ │ ├── use-subscription.ts # Get subscription status │ │ └── use-permissions.ts # Check user permissions │ │ │ ├── actions/ # Server Actions │ │ ├── auth.actions.ts │ │ ├── org.actions.ts │ │ ├── subscription.actions.ts │ │ └── features/ │ │ ├── projects.actions.ts │ │ └── tasks.actions.ts │ │ │ └── utils/ │ ├── permissions.ts # Permission checking │ ├── rate-limit.ts # Rate limiting │ └── errors.ts # Error handling │ ├── types/ │ ├── database.types.ts # Generated from Supabase │ ├── stripe.types.ts │ └── app.types.ts │ ├── middleware.ts # Next.js middleware (auth) ├── .env.local ├── .env.example ├── next.config.js ├── package.json ├── tailwind.config.ts └── tsconfig.json

Phase 3: Feature Planning & Breakdown

The skill breaks down SaaS features into implementable chunks:

3.1 Core SaaS Features (Must Have)

Authentication & User Management

Auth Flow

User Stories:

• As a user, I can sign up with email/password
• As a user, I can sign in with OAuth (Google, GitHub)
• As a user, I can reset my password
• As a user, I can update my profile

Technical Implementation:

• Supabase Auth handles all authentication
• Magic link email for password reset
• OAuth providers configured in Supabase dashboard
• Profile updates via Server Actions

Acceptance Criteria:

• Users can create accounts
• Email verification works
• Password reset flow functional
• OAuth providers work
• Sessions persist across refreshes
• Logout clears session

Time Estimate: 2-3 days

Organization Management

Multi-Tenant Organizations

User Stories:

• As a user, I can create an organization
• As an owner, I can invite team members
• As a member, I can accept invitations
• As an owner, I can manage member roles
• As a user, I can switch between organizations

Technical Implementation:

• Organizations table with RLS
• Invitation system via email
• Role-based access control (owner, admin, member)
• Organization switcher component
• Invites expire after 7 days

Acceptance Criteria:

• Users can create orgs with unique slugs
• Owners can invite via email
• Invites create pending records
• Members can accept/decline
• Role changes reflect immediately
• Users can switch orgs via dropdown

Time Estimate: 3-4 days

Subscription & Billing

Stripe Subscription Flow

User Stories:

• As a user, I can view pricing plans
• As an org owner, I can subscribe to a plan
• As an org owner, I can upgrade/downgrade
• As an org owner, I can manage billing
• As an org owner, I can cancel subscription

Technical Implementation:

• Stripe Checkout for subscriptions
• Webhook handler for subscription events
• Customer Portal for self-service billing
• Trial period (14 days)
• Graceful downgrade handling

Acceptance Criteria:

• Pricing page shows all plans
• Checkout flow works end-to-end
• Webhooks update subscription status
• Features respect subscription tier
• Portal allows plan changes
• Cancellation handles end of period

Time Estimate: 4-5 days

3.2 Feature-Specific Planning

The skill generates custom feature breakdowns based on your SaaS:

Example: Project Management Features

Projects Feature

User Stories:

• As a member, I can view all org projects
• As a member, I can create new projects
• As a member, I can update project details
• As an admin, I can archive projects

Database:

• projects table with org relationship
• RLS policies for org-based access

Components:

• ProjectList (with search/filter)
• ProjectCard (preview)
• CreateProjectDialog (form)
• ProjectSettings (edit)

API:

• GET /api/projects?orgId=xxx
• POST /api/projects
• PATCH /api/projects/:id
• DELETE /api/projects/:id

Time Estimate: 3 days

Tasks Feature

User Stories:

• As a member, I can create tasks in projects
• As a member, I can assign tasks
• As an assignee, I can update task status
• As a member, I can set due dates

Database:

• tasks table with project relationship
• Status enum (todo, in_progress, done)
• Priority enum (low, medium, high)

Components:

• TaskList (kanban or table view)
• TaskCard (draggable)
• CreateTaskDialog (form)
• TaskDetailView (modal)

Time Estimate: 3-4 days

Phase 4: Development Roadmap

The skill generates realistic week-by-week plans:

Week 1: Foundation & Auth

Days 1-2: Project Setup

Tasks:

• Create Next.js 15 project with TypeScript
• Install dependencies (Supabase, Stripe, shadcn/ui, Zod)
• Set up Supabase project
• Configure environment variables
• Set up database schema (run SQL)
• Configure RLS policies
• Generate TypeScript types from database

Deliverable: Empty project with database ready

Days 3-4: Authentication

Tasks:

• Implement Supabase Auth
• Create login/signup pages
• Add OAuth providers (Google, GitHub)
• Build auth middleware
• Create protected route wrapper
• Add password reset flow
• Style auth pages with shadcn/ui

Deliverable: Working authentication system

Day 5: User Profiles

Tasks:

• Create profile page
• Implement profile update form
• Add avatar upload (Supabase Storage)
• Build user settings page

Deliverable: Users can manage profiles

Weekend: Buffer

• Fix any blocking issues
• Test auth flows
• Start organization setup

Week 2: Organizations & Teams

Days 1-2: Organization Core

Tasks:

• Create org creation flow
• Build org switcher component
• Implement org slug validation
• Add org settings page
• Create org context/provider

Deliverable: Organizations functional

Days 3-4: Team Management

Tasks:

• Build invitation system
• Create invite email templates
• Implement role management
• Add member list page
• Build invite acceptance flow

Deliverable: Team collaboration works

Day 5: Polish

Tasks:

• Add loading states
• Improve error handling
• Add toast notifications
• Test org workflows

Weekend: Integration testing

Week 3: Stripe Integration

Days 1-2: Stripe Setup

Tasks:

• Set up Stripe account
• Create products and prices
• Implement webhook endpoint
• Test webhook locally (Stripe CLI)
• Add webhook handlers for key events

Deliverable: Stripe connected

Days 3-4: Subscription Flow

Tasks:

• Build pricing page
• Implement checkout flow
• Create success/cancel pages
• Add subscription status indicator
• Implement Customer Portal link

Deliverable: Subscriptions work end-to-end

Day 5: Feature Gates

Tasks:

• Add subscription checking middleware
• Implement usage limits per tier
• Build upgrade prompts
• Add billing page to dashboard

Weekend: Test all subscription scenarios

Week 4: Core Features

Days 1-3: Primary Feature (e.g., Projects)

Tasks:

• Build CRUD operations
• Create list/detail views
• Add search and filtering
• Implement Server Actions
• Add optimistic updates

Deliverable: Primary feature functional

Days 4-5: Secondary Feature (e.g., Tasks)

Tasks:

• Build basic CRUD
• Create list view
• Add quick actions
• Implement status updates

Weekend: Feature testing and polish

Week 5: Polish & Launch Prep

Days 1-2: UX Polish

Tasks:

• Add loading skeletons
• Improve error messages
• Add empty states
• Implement toast notifications
• Add confirmation dialogs

Days 3-4: Testing & Bugs

Tasks:

• Test all user flows
• Fix critical bugs
• Test mobile responsiveness
• Check cross-browser compatibility

Day 5: Deploy

Tasks:

• Set up Vercel project
• Configure production environment variables
• Set up Stripe webhook in production
• Deploy to production
• Test production deployment

Weekend: Monitor, fix critical issues

Phase 5: Security & Best Practices

The skill enforces security patterns:

5.1 Row Level Security (RLS) Patterns

-- Pattern 1: User owns resource CREATE POLICY "Users can only access own data" ON table_name FOR ALL USING (user_id = auth.uid());

-- Pattern 2: Org member access CREATE POLICY "Org members can access org data" ON table_name FOR SELECT USING ( organization_id IN ( SELECT organization_id FROM organization_members WHERE user_id = auth.uid() ) );

-- Pattern 3: Role-based access CREATE POLICY "Only admins can delete" ON table_name FOR DELETE USING ( organization_id IN ( SELECT organization_id FROM organization_members WHERE user_id = auth.uid() AND role IN ('owner', 'admin') ) );

-- Pattern 4: Resource creator can update CREATE POLICY "Creator can update" ON table_name FOR UPDATE USING (created_by = auth.uid());

5.2 Server Action Security

// lib/actions/secure-action.ts import { createClient } from '@/lib/supabase/server'; import { redirect } from 'next/navigation';

export async function secureAction( handler: (userId: string, orgId: string) => Promise<any> ) { const supabase = await createClient();

// 1. Verify authentication const { data: { user }, error } = await supabase.auth.getUser();

if (error || !user) { redirect('/login'); }

// 2. Get current organization const { data: membership } = await supabase .from('organization_members') .select('organization_id') .eq('user_id', user.id) .single();

if (!membership) { throw new Error('No organization access'); }

// 3. Execute handler with verified context return handler(user.id, membership.organization_id); }

// Usage in Server Actions export async function createProject(formData: FormData) { 'use server';

return secureAction(async (userId, orgId) => { const name = formData.get('name') as string;

// Validation
if (!name || name.length < 3) {
  return { error: 'Name must be at least 3 characters' };
}

// Database operation (RLS will further verify access)
const supabase = await createClient();
const { data, error } = await supabase
  .from('projects')
  .insert({
    name,
    organization_id: orgId,
    created_by: userId
  })
  .select()
  .single();
  
if (error) {
  return { error: error.message };
}

return { data };

}); }

5.3 API Route Security

// app/api/stripe/webhook/route.ts import { headers } from 'next/headers'; import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: Request) { const body = await req.text(); const signature = headers().get('stripe-signature');

if (!signature) { return new Response('No signature', { status: 400 }); }

try { // Verify webhook signature const event = stripe.webhooks.constructEvent( body, signature, webhookSecret );

// Handle different events
switch (event.type) {
  case 'checkout.session.completed':
    await handleCheckoutComplete(event.data.object);
    break;
  case 'customer.subscription.updated':
    await handleSubscriptionUpdate(event.data.object);
    break;
  case 'customer.subscription.deleted':
    await handleSubscriptionCancel(event.data.object);
    break;
}

return new Response(JSON.stringify({ received: true }));

} catch (err) { console.error('Webhook error:', err); return new Response('Webhook error', { status: 400 }); } }

Phase 6: Deployment & Monitoring

6.1 Environment Variables

.env.example

Supabase

NEXT_PUBLIC_SUPABASE_URL=your-project-url NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Stripe

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx STRIPE_SECRET_KEY=sk_test_xxx STRIPE_WEBHOOK_SECRET=whsec_xxx

App

NEXT_PUBLIC_APP_URL=http://localhost:3000 NEXT_PUBLIC_APP_NAME=YourSaaS

Email (optional)

RESEND_API_KEY=re_xxx

6.2 Vercel Deployment Checklist

Pre-Deploy

• All environment variables set in Vercel
• Supabase RLS policies tested
• Stripe webhook URL configured for production
• Production Stripe keys configured
• Error tracking set up (Sentry)
• Analytics configured (PostHog, Plausible)

Deploy

• Push to main branch
• Verify build succeeds
• Check production URL
• Test critical flows in production

Post-Deploy

• Monitor error rates
• Check webhook delivery
• Verify subscription flows
• Test on mobile devices

Output Format

When you request SaaS architecture planning, the skill provides:

[Your SaaS Name] - Technical Architecture Document

Executive Summary

[2-3 paragraphs: what you're building, for whom, tech stack]

Product Overview

Name: [Product Name] Target: [Target Audience] Value Prop: [One-liner] Revenue Model: [Pricing strategy]

Technical Stack

• Frontend: Next.js 15 (App Router) + TypeScript + Tailwind CSS
• UI Components: shadcn/ui
• Backend: Next.js Server Actions + API Routes
• Database: PostgreSQL (Supabase)
• Auth: Supabase Auth
• Payments: Stripe
• Storage: Supabase Storage
• Hosting: Vercel
• Email: Resend (optional)

Database Architecture

[Complete SQL schema with RLS policies]

File Structure

[Full Next.js directory structure]

Feature Breakdown

Core SaaS Features (Week 1-3)

[Authentication, Organizations, Subscriptions]

Product Features (Week 4-6)

[Your specific features broken down]

Development Roadmap

[Week-by-week plan with tasks and deliverables]

Security Considerations

[RLS patterns, authentication flows, API security]

Deployment Strategy

[Vercel setup, environment variables, monitoring]

Success Metrics

• Activation: [First meaningful action]
• Engagement: [Regular usage indicator]
• Retention: [Return behavior]
• Revenue: [MRR growth targets]

Risks & Mitigations

Next Steps

1. [First actionable task]
2. [Second task]
3. [Third task]

How to Use This Skill

Basic Usage

I need architecture for a SaaS product.

Use saas-architect skill.

Idea: [Your SaaS idea] Target Users: [Who] Pricing: [How you'll charge]

Detailed Planning

Create complete SaaS architecture plan using saas-architect.

Product: [Detailed description] Features: [List key features] Timeline: [Launch target] Constraints: [Any technical/business constraints]

Feature-Specific Planning

I have existing SaaS, need to add [feature].

Use saas-architect to plan:

• Database changes needed
• File structure for feature
• Implementation steps
• Timeline estimate

Existing Stack: Next.js 15 + Supabase

Integration with Development

With Claude Code

After generating architecture, use with Claude Code:

Generate starter code for this SaaS architecture:

[Paste architecture document]

Start with:

1. Database schema (run SQL in Supabase)
2. Initial project structure
3. Auth implementation
4. Organization setup

With Other Skills

Recommended workflow:

• idea-validator-pro → Validate market fit

• saas-architect → Technical planning

• modern-ui-designer → Design system

• Claude Code → Implementation

• code-quality-guardian → Code review

• deployment-automation → Launch

Best Practices

DO ✅

• Start with Core SaaS Features: Auth, Orgs, Subscriptions first

• Use RLS Everywhere: Never skip Row Level Security

• Test Subscriptions Early: Stripe webhooks are critical

• Plan for Multi-Tenancy: Even if starting single-tenant

• Document Decisions: Future you will thank you

DON'T ❌

• Skip RLS Policies: Data leaks are catastrophic

• Hardcode Stripe Keys: Use environment variables

• Ignore Webhook Testing: Test webhooks locally first

• Over-Engineer: Start simple, scale later

• Build Without Auth: Start with authentication

Common Scenarios

Scenario 1: Freemium SaaS

Challenge: Need free tier with upgrade path Solution:

• Free tier with feature limits
• Trial period for paid plans
• Usage tracking in database
• Upgrade prompts in UI

Scenario 2: Team Collaboration

Challenge: Multiple users per organization Solution:

• Organization-based RLS
• Role-based permissions
• Invitation system
• Activity logging

Scenario 3: Usage-Based Pricing

Challenge: Charge based on usage, not seats Solution:

• Usage tracking table
• Metered billing with Stripe
• Usage dashboards
• Overage handling

Technical Debt Prevention

Phase 1 (Weeks 1-2): None Expected

Focus on getting foundation right.

Phase 2 (Weeks 3-4): Monitor These

• Test coverage (aim for >70% on critical paths)

• Error handling consistency

• Loading state patterns

Phase 3 (Weeks 5-6): Refactor Time

• Extract reusable hooks

• Consolidate similar components

• Optimize database queries

• Add missing indexes

Launch Checklist

Pre-Launch (1 Week Before)

• All core features working

• Mobile responsive tested

• Cross-browser tested

• Payment flow tested end-to-end

• Error tracking configured

• Analytics set up

• Terms of Service ready

• Privacy Policy ready

• Support email configured

Launch Day

• Deploy to production

• Verify all webhooks working

• Test signup flow

• Test subscription flow

• Monitor error rates

• Check analytics tracking

Post-Launch (First Week)

• Daily monitoring

• Fix critical bugs

• Gather user feedback

• Iterate on pain points

Skill Metadata

Version: 1.0.0

Last Updated: November 2025

Optimized For: Next.js 15, Supabase, Stripe

Target: Solo Developers building SaaS products

Output: Complete technical architecture documentation

Key Insight: Great SaaS architecture isn't about having every feature—it's about building the right foundation that scales. Focus on authentication, multi-tenancy, and subscriptions first. Everything else can iterate.