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 ) { 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

| Risk | Impact | Mitigation |

|------|--------|------------|

| [Risk 1] | [High/Med/Low] | [How to handle] |

Next Steps

[First actionable task]
[Second task]
[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.

安装