Rails AI SaaS Kit

Getting Started

The Rails AI SaaS Kit is a production-ready boilerplate for building AI-powered web applications. It includes multi-provider AI chat, document search (RAG), payments, admin panel, and everything needed to run a SaaS business.

Requirements

• Ruby 3.4+ and Rails 8+
• PostgreSQL 15+ with pgvector extension
• Redis (for Sidekiq background jobs)
• Node.js 20+ (for asset compilation)

Quick Setup

git clone <your-repo> myapp
cd myapp
bundle install
cp .env.example .env    # Add your API keys
rails db:create db:migrate db:seed
bin/dev

Visit http://localhost:3000 — the first user to sign up automatically becomes the super admin.

Environment Variables

Variable	Description	Required
OPENAI_API_KEY	OpenAI API key for GPT models	At least one AI key
ANTHROPIC_API_KEY	Anthropic API key for Claude models	Optional
GEMINI_API_KEY	Google Gemini API key	Optional
STRIPE_SECRET_KEY	Stripe secret key for payments	For Stripe billing
PAYSTACK_SECRET_KEY	Paystack secret key	For Paystack billing
SMTP_ADDRESS	SMTP server (e.g. smtp-relay.brevo.com)	Yes
SMTP_USERNAME	SMTP login	Yes
SMTP_PASSWORD	SMTP password/key	Yes
APP_HOST	Your domain (e.g. myapp.com)	Yes
DISCORD_RELEASES_WEBHOOK_URL	Discord webhook for release notifications	Optional

AI Features

Multi-Provider Chat

The kit supports OpenAI (GPT-4o, GPT-4, GPT-3.5), Anthropic (Claude 3.5 Sonnet, Claude 3 Opus), and Google Gemini via the ruby_llm gem. Users can switch models mid-conversation.

Responses stream in real-time via Turbo Streams — no WebSocket configuration needed. Token usage is tracked per user and per model for cost analytics.

RAG Document Search

Upload PDFs, DOCX, or text files. Documents are automatically chunked, embedded using pgvector, and searchable via AI chat. The AI generates answers with citations from your documents.

AI Prompt Templates

Pre-built templates for common tasks: blog writing, code generation, translation, summarization, and more. Admins create templates from the admin panel with dynamic variables. Users fill in the blanks and get AI output.

Credit System

Pay-per-use credits for AI generations. Admins can gift credits. Automatic email alerts when credits are low or exhausted. Purchase credit packs from the billing page.

Payments & Billing

Supported Providers

• Stripe — International payments with Embedded Checkout. Supports promo codes, tax calculation, and any Stripe payment method.
• Paystack — African markets (Nigeria, Ghana, South Africa, Kenya). Automatic country detection routes users to the right provider.

Pricing Models

• One-time purchases — Kit license plans (1 Year, 5 Year, Lifetime)
• Recurring subscriptions — Monthly/Annual Pro and Premium tiers
• Credit packs — Pay-per-use AI credits

Webhook Verification

Both Stripe and Paystack webhooks are verified with signature checking. Payments are reconciled automatically — credits added, subscriptions activated, and confirmation emails sent.

Admin Panel

Role-Based Access

Four admin tiers with progressively fewer permissions:

1. Super Admin — Full access to everything including Founders Room and system settings
2. Admin — User management, marketing, content management
3. Support — View users, manage conversations, handle support tickets
4. Moderator — Basic moderation capabilities

Dashboard

Revenue metrics (total, monthly, daily), user growth charts, payment funnel, geographic breakdown, traffic sources. USD/NGN currency toggle. CSV exports for revenue, users, and subscriptions.

Features

• User Management — Search, filter, view profiles, toggle admin, change roles, disable accounts, gift credits, impersonate users
• Blog CMS — Rich text articles with Action Text, categories, publish/unpublish, SEO slugs
• Changelog — Version-based release notes with auto-post to Discord
• Marketing Campaigns — Targeted emails: upgrade nudge, trial ending, re-engagement, weekly tips, feature announcements
• Announcement Banners — Info/warning/success/maintenance banners, scheduled, dismissible per user
• Support Conversations — Reply, close, reopen support tickets
• AI Analytics — Token usage, model breakdown, cost tracking
• Webhook Management — Configure endpoints, select events, test delivery
• System Settings — Exchange rate, SMTP test email

Founders Room

Private space for co-founders (super admin only by default, partners with linked accounts can view):

• Revenue split dashboard with automatic per-partner earnings
• Payout tracker with running balances
• Expense tracking by category (deducted before splits)
• Shared decisions log (notes, decisions, proposals)
• Revenue goal tracker with progress bars
• Runway calculator with 6-month projections
• Activity feed (signups, purchases, subscriptions)
• Kit documentation and CSV export

Deployment

Recommended Platforms

• Hatchbox — Easiest. Push to GitHub, auto-deploys. Managed Puma + Sidekiq.
• Render — Free tier available. Add a Web Service + Worker + PostgreSQL + Redis.
• Fly.io — Edge deployment. Use the included fly.toml config.
• Any VPS — Kamal deployment config included for DigitalOcean, Linode, etc.

Post-Deploy Checklist

1. Set all environment variables
2. Run rails db:migrate
3. Verify Sidekiq is running (background jobs for AI streaming, emails, document processing)
4. Test SMTP from Admin > Settings > Send Test Email
5. Sign up — first user becomes super admin automatically
6. Configure API keys for AI providers in your env vars

Email System

21 premium email templates with consistent styling. Works with any SMTP provider — Brevo, SendGrid, Postmark, Mailgun, or Gmail.

Transactional Emails

• Welcome email, password reset, email confirmation, account unlock
• Payment confirmation / receipt, subscription activated/cancelled
• Credits low, credits exhausted, credits gifted
• Trial ending reminder, upgrade nudge
• Partner welcome, admin purchase notification, contact form alert

Marketing Campaigns

Send targeted campaigns from Admin > Marketing: upgrade nudge (free users), trial ending, credits low, re-engagement (inactive users), weekly tips, feature announcements with custom subject/body.

API & Webhooks

API Token Authentication

Users generate API tokens with sk_live_ prefix from their settings. Authenticate with Authorization: Bearer sk_live_... header. Tokens have optional expiry dates and last-used tracking.

Outbound Webhooks

Configure webhook endpoints from Admin > Webhooks. Available events:

• user.created — New user signup
• payment.completed — Successful payment
• subscription.created — New subscription
• subscription.cancelled — Subscription cancelled

Payloads are signed with HMAC SHA256. Verify with the X-Webhook-Signature header against your endpoint's secret.

Inbound Webhooks

Stripe and Paystack webhooks are verified and processed at /webhooks/stripe and /webhooks/paystack.