Skip to main content

LVL Up Performance Documentation

Complete guide to building and deploying AI-powered SAAS applications with our comprehensive starter kit

Next.js 15
TypeScript
Tailwind CSS
PostgreSQL
Stripe
Table of Contents
Project Overview
LVL Up Performance is a production-ready, feature-complete performance management platform built with Next.js 15, designed to help organizations manage employee performance, goals, feedback, and recognition.

This comprehensive starter kit provides everything you need to build a modern SAAS application, including authentication, payment processing, AI integration, user management, and a beautiful responsive interface.

What makes it special?

  • • Complete authentication system with Google OAuth
  • • Integrated payment processing with Stripe
  • • AI-powered chat interface with multiple models
  • • Admin panel with analytics and user management
  • • Modern UI with dark/light theme support
  • • Production-ready with comprehensive error handling
Features

Authentication & Security

NextAuth.js with Google OAuth, protected routes, session management, and role-based access control.

Payment & Billing

Stripe integration with Pro plan subscriptions, billing dashboard, and webhook handling.

AI Integration

OpenRouter API with multiple AI models, interactive chat interface, and credit-based usage system.

Analytics & Dashboard

User analytics, revenue tracking, credit monitoring, and comprehensive admin panel.

Modern UI/UX

Tailwind CSS v4, ShadCN UI components, dark/light themes, and responsive design.

Database

Neon PostgreSQL with custom functions, user management, and subscription tracking.

Technology Stack

Frontend

  • Next.js 15 with App Router
  • TypeScript
  • Tailwind CSS v4
  • ShadCN UI Components
  • Framer Motion

Backend & Database

  • NextAuth.js
  • Neon PostgreSQL
  • API Routes
  • Middleware Protection

Integrations

  • Stripe Payments
  • OpenRouter AI
  • Google OAuth
  • Vercel Deployment
Prerequisites
Before you begin, ensure you have the following installed and accounts created

Required Software

  • Node.js (version 18 or higher)
  • npm, yarn, or pnpm
  • Git
  • Code editor (VS Code recommended)
Quick Start Installation
Get your SAAS application running in minutes with these simple steps

1Clone the Repository

git clone https://github.com/zainulabedeen123/Best-Saas-Kit--V2.git
cd Best-Saas-Kit--V2

2Install Dependencies

npm install
# or
yarn install
# or
pnpm install

3Environment Setup

cp .env.example .env.local

Fill in your environment variables in .env.local (see detailed setup below)

4Start Development Server

npm run dev

Open http://localhost:3000 to see your application

Detailed Setup Guide
Configure all integrations and services for your SAAS application

Database Setup (Neon)

1. Create Neon Account

  • • Go to neon.tech
  • • Sign up for a free account
  • • Create a new project

2. Get Connection String

  • • In your Neon dashboard, go to "Connection Details"
  • • Copy the connection string
  • • Add it to your .env.local as DATABASE_URL

3. Initialize Database

The database tables will be created automatically when you first run the app.

Google OAuth Setup

1. Google Cloud Console Setup

  • • Go to Google Cloud Console
  • • Create a new project or select existing one
  • • Enable the Google+ API

2. Create OAuth Credentials

  • • Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
  • • Choose "Web application"
  • • Add authorized redirect URIs:
  • - http://localhost:3000/api/auth/callback/google (development)
  • - https://yourdomain.com/api/auth/callback/google (production)

3. Add to Environment

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Stripe Setup

1. Create Stripe Account

  • • Sign up at stripe.com
  • • Complete account verification

2. Get API Keys

  • • Go to Developers → API Keys
  • • Copy your publishable and secret keys
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...

3. Setup Webhooks

  • • Go to Developers → Webhooks
  • • Add endpoint: https://yourdomain.com/api/stripe/webhook
  • • Select events: checkout.session.completed, payment_intent.succeeded
  • • Copy webhook secret to .env.local

OpenRouter Setup

1. Create OpenRouter Account

2. Get API Key

  • • Go to Keys section
  • • Create a new API key
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=qwen/qwen3-235b-a22b-2507

Email Setup (Mailgun)

1. Create Resend Account

  • • Sign up at resend.com
  • • Verify your email address
  • • Add and verify your domain for sending emails

2. Get API Key

  • • Go to API Keys section
  • • Create a new API key
RESEND_API_KEY=re_your-resend-api-key
FROM_EMAIL=noreply@lvlupperformance.com
SUPPORT_EMAIL=support@lvlupperformance.com

3. Email Features

  • • Welcome emails for new users
  • • Subscription confirmation emails
  • • Contact form submissions
  • • Password reset emails
Project Structure
Understanding the organization and architecture of the codebase
lvl-up-performance/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── admin/             # Admin panel pages
│   │   ├── api/               # API routes
│   │   ├── auth/              # Authentication pages
│   │   ├── dashboard/         # User dashboard
│   │   ├── demo/              # Demo page
│   │   └── page.tsx           # Landing page
│   ├── components/            # React components
│   │   ├── admin/             # Admin components
│   │   ├── auth/              # Auth components
│   │   ├── billing/           # Billing components
│   │   ├── chat/              # AI chat components
│   │   ├── dashboard/         # Dashboard components
│   │   ├── landing/           # Landing page components
│   │   └── ui/                # UI components (ShadCN)
│   ├── lib/                   # Utility functions
│   │   ├── auth.ts            # NextAuth configuration
│   │   ├── database.ts        # Database functions
│   │   ├── stripe.ts          # Stripe utilities
│   │   └── ...
│   ├── hooks/                 # Custom React hooks
│   ├── types/                 # TypeScript type definitions
│   └── middleware.ts          # Next.js middleware
├── public/                    # Static assets
├── .env.example              # Environment variables template
├── .env.local                # Your environment variables (not in git)
├── package.json              # Dependencies and scripts
├── tailwind.config.js        # Tailwind CSS configuration
└── tsconfig.json             # TypeScript configuration

Key Directories

  • src/app/ - Next.js 15 App Router pages and layouts
  • src/components/ - Reusable React components
  • src/lib/ - Utility functions and configurations
  • src/hooks/ - Custom React hooks

Important Files

  • middleware.ts - Route protection and authentication
  • lib/auth.ts - NextAuth.js configuration
  • lib/database.ts - Database connection and queries
  • lib/stripe.ts - Payment processing utilities
Usage Guide
How to use and navigate the different features of your SAAS application

Landing Page

The landing page includes:

  • • Hero section with call-to-action
  • • Features showcase
  • • Pricing section
  • • Testimonials
  • • Footer with links

User Authentication

  • • Users can sign in with Google OAuth
  • • Automatic user creation in database
  • • Session management with NextAuth
  • • Protected routes for authenticated users

Dashboard Features

  • • Overview: User stats and quick actions
  • • Chat: AI-powered chat interface
  • • Analytics: Usage statistics and insights
  • • Billing: Subscription management
  • • Profile: User profile management
  • • Settings: Account preferences

Admin Panel

Admin users (configured via email) get access to:

  • • User management and analytics
  • • Revenue tracking
  • • System-wide statistics
  • • User activity monitoring

AI Chat

  • • Interactive chat interface
  • • Multiple AI models via OpenRouter
  • • Credit-based usage system
  • • Real-time streaming responses
Customization
How to customize and extend the application for your specific needs

Styling

  • • Modify src/app/globals.css for global styles
  • • Update tailwind.config.js for Tailwind customization
  • • Edit components in src/components/ui/ for UI changes
  • • Customize theme colors and fonts in the configuration files

Configuration

  • • Update src/lib/stripe.ts for pricing changes
  • • Modify src/lib/database.ts for database schema changes
  • • Edit src/middleware.ts for route protection
  • • Configure admin emails in environment variables

AI Models

  • • Change AI models in .env.local (OPENROUTER_MODEL)
  • • Modify chat interface in src/components/chat/
  • • Update credit costs in src/lib/database.ts
  • • Add new AI providers by extending the API routes
Deployment
Deploy your SAAS application to production

Vercel (Recommended)

1. Connect Repository
  • • Go to vercel.com
  • • Import your GitHub repository
2. Environment Variables
  • • Add all environment variables from .env.local
  • • Update NEXTAUTH_URL and NEXT_PUBLIC_SITE_URL to your domain
3. Deploy
  • • Vercel will automatically deploy your application
  • • Set up custom domain if needed

Other Platforms

The application can be deployed to any platform that supports Next.js:

  • • Netlify: Use npm run build and deploy the .next folder
  • • Railway: Connect your GitHub repository
  • • DigitalOcean App Platform: Use the Next.js template
  • • AWS Amplify: Connect your repository and configure build settings
Environment Variables
Complete reference for all required and optional environment variables
VariableDescriptionRequiredExample
NEXTAUTH_URLYour site URLhttp://localhost:3000
NEXTAUTH_SECRETNextAuth secret keyyour-secret-key
GOOGLE_CLIENT_IDGoogle OAuth client ID123456789.apps.googleusercontent.com
GOOGLE_CLIENT_SECRETGoogle OAuth client secretGOCSPX-...
DATABASE_URLNeon PostgreSQL connection stringpostgresql://user:pass@host/db
STRIPE_SECRET_KEYStripe secret keysk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYStripe publishable keypk_test_...
STRIPE_WEBHOOK_SECRETStripe webhook secretwhsec_...
OPENROUTER_API_KEYOpenRouter API keysk-or-v1-...
OPENROUTER_MODELAI model to useqwen/qwen3-235b-a22b-2507
RESEND_API_KEYResend email API keyre_your-resend-api-key
FROM_EMAILEmail address for sending emailsOptionalonboarding@yourdomain.com
SUPPORT_EMAILSupport email addressOptionalsupport@yourdomain.com
Troubleshooting
Common issues and their solutions

Common Issues

Database Connection Error
Error: connect ECONNREFUSED
  • • Check your DATABASE_URL in .env.local
  • • Ensure your Neon database is running
  • • Verify the connection string format
Google OAuth Error
OAuthCallback error
  • • Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
  • • Check authorized redirect URIs in Google Cloud Console
  • • Ensure NEXTAUTH_URL matches your domain
Stripe Webhook Error
Webhook signature verification failed
  • • Verify STRIPE_WEBHOOK_SECRET in .env.local
  • • Check webhook endpoint URL in Stripe dashboard
  • • Ensure webhook is receiving POST requests
AI Chat Not Working
OpenRouter API error
  • • Check OPENROUTER_API_KEY is valid
  • • Verify you have credits in your OpenRouter account
  • • Ensure OPENROUTER_MODEL is available

Built with ❤️ by the LVL Up Performance team

WebsiteGitHubDiscordTwitter