Documentation

Everything you need to set up, customize, and deploy Brainboot.

Quick StartEnvironment VariablesFeaturesCustomization

Quick Start

01

Clone & Install

git clone <your-repo> my-saas
cd my-saas
npm install
02

Set Up Supabase

1. Create project at supabase.com
2. SQL Editor → run supabase-schema.sql
3. SQL Editor → run supabase-schema-v2.sql
4. Copy keys from Settings → API
03

Set Up Stripe

1. Create 2 products (Pro $29/mo, Unlimited $99/mo)
2. Copy Price IDs
3. Create webhook: yourdomain.com/api/stripe/webhook
4. Copy webhook signing secret
04

Configure Google OAuth

1. Google Cloud Console → APIs & Services → Credentials
2. Create OAuth Client ID → Web application
3. Add redirect: http://localhost:3000/auth/callback
4. In Supabase: Auth → Providers → Google → paste credentials
05

Configure Environment

cp .env.example .env.local
# Fill in all required variables
06

Run & Deploy

npm run dev          # localhost:3000
npx vercel            # deploy to production

Environment Variables

Copy .env.example to .env.local and fill in your values.

NEXT_PUBLIC_SUPABASE_URL
RequiredClient

Your Supabase project URL. Found in Project Settings > API.

NEXT_PUBLIC_SUPABASE_ANON_KEY
RequiredClient

Supabase anon/public key for client-side auth.

SUPABASE_SERVICE_ROLE_KEY
RequiredServer

Supabase service role key for server-side admin operations. Never expose to the client.

STRIPE_SECRET_KEY
RequiredServer

Stripe API secret key. Use test key (sk_test_) for development.

STRIPE_WEBHOOK_SECRET
RequiredServer

Signing secret for Stripe webhook verification.

STRIPE_PRO_PRICE_ID
RequiredServer

Stripe Price ID for Pro plan.

STRIPE_UNLIMITED_PRICE_ID
RequiredServer

Stripe Price ID for Unlimited plan.

NEXT_PUBLIC_STRIPE_PRO_PRICE_ID
RequiredClient

Same Pro price ID for client-side upgrade buttons.

NEXT_PUBLIC_STRIPE_UNLIMITED_PRICE_ID
RequiredClient

Same Unlimited price ID for client-side.

NEXT_PUBLIC_APP_URL
RequiredClient

Your app base URL for redirects and callbacks.

RESEND_API_KEY
OptionalServer

Resend API key. If not set, emails log to console.

EMAIL_FROM
OptionalServer

Sender address. Defaults to "Brainboot <noreply@yourdomain.com>".

EMAIL_REPLY_TO
OptionalServer

Reply-to address. Defaults to "support@yourdomain.com".

What's Included

Authentication

  • ✓Email/password signup & login
  • ✓Google OAuth
  • ✓Password reset flow
  • ✓Email verification gate
  • ✓Session refresh via middleware

Billing & Payments

  • ✓Stripe subscriptions (Free/Pro/Unlimited)
  • ✓Checkout + billing portal
  • ✓Webhook lifecycle handling
  • ✓7-day dunning with grace period
  • ✓Cancel at period end + reactivation
  • ✓Free trials with/without card

Multi-Tenant Teams

  • ✓Organizations with roles (owner/admin/member)
  • ✓Email invitations with 7-day expiry
  • ✓Org switcher for multi-org users
  • ✓Org-level usage pooling
  • ✓API key management (SHA-256 hashed)

Admin & Operations

  • ✓Admin panel with user/org management
  • ✓Webhook failure monitoring
  • ✓Audit logging for admin actions
  • ✓9 transactional email templates
  • ✓Rate limiting infrastructure
  • ✓Global error boundary

Customization Guide

Change branding

Update metadata in src/app/layout.tsx, text in src/components/nav.tsx, logo in src/components/logo.tsx, colors in src/app/globals.css, email branding in src/lib/email.ts.

Modify pricing plans

Edit PLAN_LIMITS and PLAN_PRICES in src/lib/supabase.ts. Create matching Stripe products and update env vars.

Add a new API route

Create src/app/api/your-feature/route.ts. Use withAuth() wrapper for automatic auth + rate limiting.

Track usage

Call incrementUsage(orgId, userId, tokens, action) from any API route. checkUsage(orgId) returns { allowed, remaining }.

Add email templates

Add to the templates object in src/lib/email.ts. Send with sendEmail({ to, template, data }).