# BuildSaaS - Comprehensive Repository Analysis for LLM

> Product index for answer engines: https://www.buildsaas.dev/llms.txt
> Full extractable brief: https://www.buildsaas.dev/llms-full.txt
> Canonical site: https://www.buildsaas.dev/

## Repository Overview
BuildSaaS is a comprehensive SaaS boilerplate built with Next.js, featuring a complete admin panel, public marketing site, payment integration, and deployment pipeline. It provides everything needed to build and launch SaaS applications including authentication, payments, email campaigns, content management, and automated deployment.

## Architecture Overview

### Tech Stack
- **Framework**: Next.js 15 with React 18 (Pages Router)
- **Frontend**: React, Tailwind CSS, Framer Motion animations
- **Backend**: Next.js API routes, Firebase Firestore
- **Authentication**: Firebase Auth (Email/Password + Google OAuth)
- **Payments**: Polar.sh (subscriptions, payments, webhooks)
- **Email**: Resend API (transactional emails, campaigns)
- **Deployment**: Vercel + GitHub integration
- **State Management**: Redux Toolkit + TanStack Query
- **Rich Text**: Tiptap editor with custom extensions
- **Search**: Fuse.js for fuzzy search
- **File Storage**: Firebase Storage + Polar Files API
- **Analytics**: PostHog + Vercel Analytics

### Project Structure
```
buildsaas/
├── pages/                 # Next.js pages (public routes)
│   ├── api/              # Backend API routes
│   ├── admin/            # Admin panel routes
│   └── public pages      # Homepage, blog, pricing, etc.
├── app/                  # App components
│   ├── components/       # Public components (Navbar, Footer)
│   └── admin/            # Admin panel (21 tabs)
├── lib/                  # Utilities and configurations
│   ├── api/             # Firestore operations
│   ├── ui/              # Reusable UI components
│   └── utils/           # Helper functions
├── content/              # Documentation (MDX files)
├── public/               # Static assets
└── scripts/              # Configuration scripts
```

---

## ADMIN PANEL ANALYSIS

### Core Entry Point: `/app/admin/index.jsx`
**Purpose**: Main admin dashboard orchestrator with role-based access control.

**Key Features**:
- Authentication state management via Firebase Auth
- Role-based permissions (Admin, Editor, Author, Viewer)
- Global search modal (Cmd/Ctrl+K)
- Tab-based navigation with 21 admin sections
- Mobile-responsive design
- Email sending capabilities (to subscribers/users)
- Global state: activeTab, sidebarOpen, searchModal, loginModal

**Components Used**:
- Sidebar.jsx (navigation with drag-and-drop reordering)
- SearchModal.jsx (global search across all data)
- ConfirmationModal, LoginModal
- 21 admin tab components

### Admin Components Breakdown

#### 1. HomeTab.jsx - Dashboard Overview
**Features**:
- KPI cards: Revenue, Active Customers, Blog Posts, Subscribers
- Content activity chart (Recharts AreaChart)
- Recent users list with roles
- Unread messages and unpaid invoices alerts
- Quick actions: New Blog, New Email, Create Invoice

**Data Sources**: All collections (blogs, emails, customers, payments, etc.)

#### 2. BlogTab.jsx - Content Management
**Features**:
- CRUD operations for blog posts
- Rich text editor (TiptapEditor)
- Image upload capabilities
- Status management (Draft, Published, Scheduled)
- Search and filtering
- Export functionality (CSV/JSON)

**API Integration**: `lib/api/blog.js` functions

#### 3. EmailTab.jsx - Email Campaigns
**Features**:
- Email composition with TiptapEditor
- Send to all subscribers or individual users
- Scheduling functionality
- Preview modal with HTML rendering
- Status tracking and analytics

**Integrations**: Resend API for sending

#### 4. KanbanBoardTab.jsx - Task Management
**Features**:
- Drag-and-drop Kanban board (Backlog, In Progress, Done)
- Task creation with assignees
- Priority levels and categories
- Integration with IdeaDatabaseTab
- Search and filtering with Fuse.js

#### 5. PaymentsTab.jsx - Financial Tracking
**Features**:
- Payment transaction listing
- Status filtering (succeeded, failed, pending)
- Customer and plan information
- Invoice generation
- Export capabilities

**Data**: Polar webhook-synchronized payments

#### 6. CustomersTab.jsx - Subscription Management
**Features**:
- Customer listing with subscription details
- Status tracking (active, cancelled, etc.)
- Plan information and billing amounts
- Polar integration for subscription management

#### 7. UsersTab.jsx - User Management
**Features**:
- Authenticated user listing
- Provider information (Google/Email)
- Email verification status
- Creation and last sign-in dates

#### 8. SubscribersTab.jsx - Email List Management
**Features**:
- Subscriber CRUD operations
- Status management (active/inactive)
- Email sending capabilities
- Newsletter subscription handling

#### 9. TeamsTab.jsx - Access Control
**Features**:
- Role-based access control (Admin, Editor, Author, Viewer)
- Team member management
- Permission checking throughout the app
- First user becomes admin automatically

#### 10. FormsTab.jsx - Dynamic Form Builder
**Features**:
- Form creation with multiple field types
- Live preview
- Submission management
- URL generation for public forms

#### 11. AnalyticsTab.jsx - Web Analytics
**Features**:
- Geographic visitor mapping (Leaflet)
- Time-based filtering
- Page view and visitor statistics
- Country-based data visualization

#### 12. CronJobsTab.jsx - Scheduled Tasks
**Features**:
- Blog and email scheduling
- CRON job management
- Manual execution capabilities
- Status tracking (scheduled, completed, failed)

#### 13. AssetsTab.jsx - Digital Asset Library
**Features**:
- File upload with progress tracking
- Multiple file type support
- Storage usage tracking
- Download and sharing capabilities

#### 14. ProductsTab.jsx - Digital Product Management
**Features**:
- Product creation and management
- Pricing configuration
- Checkout link generation
- Polar product synchronization

#### 15. MessagesTab.jsx - Customer Support
**Features**:
- Contact form submissions
- Reply functionality
- Status tracking (read, replied)
- Search and filtering

#### 16. DocsEditorTab.jsx - Documentation Management
**Features**:
- MDX file editing
- Version control
- Category organization
- Live preview

#### 17. ChangelogTab.jsx - Release Notes
**Features**:
- Product update tracking
- Category-based organization
- Rich content editing

#### 18. IdeaDatabaseTab.jsx - Idea Management
**Features**:
- Idea capture and organization
- Kanban integration
- Rich text content
- Task conversion capabilities

#### 19. InvoiceTab.jsx - Billing Management
**Features**:
- Invoice creation and editing
- PDF generation capabilities
- Payment status tracking
- Customer information

#### 20. ReportIssuesTab.jsx - Issue Tracking
**Features**:
- User-reported issue management
- Status updates (pending, fixed)
- Categorization and filtering

#### 21. WaitlistTab.jsx - Product Waitlist
**Features**:
- Waitlist management
- Email communication
- Status tracking

### Shared Admin Components

#### TiptapEditor.jsx - Rich Text Editor
**Extensions**:
- StarterKit, CustomImage, CustomTable, Youtube, Details
- TextAlign, Link, Highlight, TextStyle, Color, Typography
- CharacterCount, Underline, TaskList, TaskItem
- CodeBlock, CodeGroup, Markdown support

**Features**:
- Slash commands for quick insertion
- Image upload and embedding
- Table creation and editing
- Code syntax highlighting
- Markdown/HTML conversion

#### Sidebar.jsx - Navigation
**Features**:
- Drag-and-drop reordering (@dnd-kit)
- Collapsible sections
- Mobile overlay
- Search integration
- Icon mapping for all tabs

#### SearchModal.jsx - Global Search
**Features**:
- Fuzzy search across all admin data
- Categorized results
- Direct navigation links
- Keyboard shortcuts (Cmd/Ctrl+K)

---

## FRONTEND ANALYSIS

### Public Pages Structure

#### 1. Homepage (`/pages/index.js`)
**Features**:
- Hero section with CTA
- Feature grid (8 features)
- Pricing preview cards
- FAQ accordion
- Contact form submission
- Newsletter signup

**Components**: Navbar, Footer

#### 2. Blog System
- **Blog Listing** (`/pages/blog.js`): Grid layout with search
- **Blog Post** (`/pages/blog/[slug].js`): Markdown rendering, syntax highlighting, social sharing
- **Features**: SEO optimization, reading time, author info

#### 3. Pricing Page (`/pages/pricing.js`)
**Features**:
- Subscription plan display
- Current subscription status
- Polar checkout integration
- Cancellation functionality
- Authentication required for upgrades

#### 4. Features Page (`/pages/features.js`)
**Features**:
- 8 feature showcase cards
- Scroll animations
- Clear value propositions

#### 5. Documentation (`/pages/docs.js`)
**Features**:
- Sidebar navigation with categories
- Markdown rendering with syntax highlighting
- Search functionality (Fuse.js)
- Dark/light theme toggle
- Table of contents generation
- Mobile-responsive design
- FAQ section (21 questions)

#### 6. Contact Page (`/pages/contact.js`)
**Features**:
- Contact form with validation
- Company information display
- API submission to `/api/messages/create`

#### 7. Forms (`/pages/forms/[slug].js`)
**Features**:
- Dynamic form rendering
- Multiple field types (text, email, select, checkbox, radio, rating, date, signature, image)
- File upload capabilities
- Canvas signature
- Validation and submission

#### 8. Builder (`/pages/builder.js`)
**Features**:
- GitHub OAuth integration
- Repository creation from templates
- Environment variable configuration
- Vercel deployment pipeline
- Firebase, Supabase, Polar, Resend setup

#### 9. Legal Pages
- Privacy Policy, Terms of Service, Legal Center

### Shared Components

#### Navbar.jsx
**Features**:
- Responsive navigation
- Authentication state display
- User dropdown with subscription info
- Login modal integration
- Active route highlighting

#### Footer.jsx
**Features**:
- Newsletter subscription
- Link organization (Product, Company, Legal)
- Social media links
- Status indicator

---

## BACKEND API ANALYSIS

### Authentication APIs (`/pages/api/auth/`)

#### GitHub OAuth Flow
- **`/api/auth/github/start`**: Initiates OAuth with CSRF protection
- **`/api/auth/github/status`**: Checks connection status
- **`/api/auth/callback`**: Handles OAuth callback and token storage

**Security**: HttpOnly cookies, state validation, CSRF protection

### Documentation APIs (`/pages/api/docs/`)

#### Content Management
- **`/api/docs/list`**: Lists documentation files with frontmatter
- **`/api/docs/read`**: Reads individual files with metadata
- **`/api/docs/create`**: Creates new documentation files
- **`/api/docs/save`**: Saves/updates content
- **`/api/docs/rename`**: Renames files
- **`/api/docs/duplicate`**: Duplicates files
- **`/api/docs/delete`**: Deletes files
- **`/api/docs/versions`**: Lists available versions

**Features**: MDX support, frontmatter parsing, directory management

### Email APIs (`/pages/api/emails/`)

#### Campaign Management
- **`/api/emails/send`**: Bulk email to subscribers (batches of 50)
- **`/api/emails/send-to-users`**: Email to authenticated users
- **`/api/emails/send-single`**: Individual email sending

**Integration**: Resend API with rate limiting

### Payment APIs (`/pages/api/polar/`)

#### Subscription Management
- **`/api/polar/checkout`**: Creates checkout sessions
- **`/api/polar/cancel-subscription`**: Cancels subscriptions
- **`/api/polar/webhook`**: Handles payment webhooks with signature verification

#### Product Management
- **`/api/polar/products/create`**: Creates products with file uploads
- **`/api/polar/products/update`**: Updates products
- **`/api/polar/products/delete`**: Deletes products
- **`/api/polar/products/checkout-link`**: Generates checkout links

**Features**: Webhook signature verification, data enrichment, transactional emails

### Message APIs (`/pages/api/messages/`)

#### Contact Forms
- **`/api/messages/create`**: Creates contact form submissions
- **`/api/messages/reply`**: Sends reply emails to submitters

### Builder APIs (`/pages/api/builder/`)

#### Code Analysis
- **`/api/builder/generate-ast`**: Generates AST tree of codebase
- **`/api/builder/download-zip`**: Creates ZIP archives for download

### Deployment APIs (`/pages/api/deploy/`, `/pages/api/publish/`)

#### CI/CD Pipeline
- **`/api/deploy/index`**: Full pipeline (GitHub + Vercel)
- **`/api/publish/github`**: GitHub repository creation
- **`/api/publish/vercel`**: Vercel deployment

**Integrations**: GitHub API (Octokit), Vercel API

### CRON APIs (`/pages/api/cron/`)

#### Scheduled Tasks
- **`/api/cron/execute`**: Executes due CRON jobs for blogs and emails

---

## DATABASE SCHEMA (Firebase Firestore)

### Collections

#### Core Content
- **blogs**: title, slug, content, status, author, publishedAt, createdAt, updatedAt
- **emails**: subject, content, status, recipients, scheduledDate, publishedAt
- **subscribers**: email, name, status, subscribedAt, unsubscribedAt

#### User Management
- **users**: uid, email, name, emailVerified, lastSignIn, createdAt
- **teams**: email, username, role, createdAt (RBAC)

#### Payments & Subscriptions
- **customers**: customerId, subscriptionId, email, name, planId, planName, status, amount, currency, expiresAt
- **payments**: paymentId, customerId, amount, currency, status, planId, planName, subscriptionId, createdAt
- **checkouts**: checkoutId, planId, customerId, status, createdAt

#### Communication
- **messages**: name, email, subject, message, read, replied, createdAt

#### Automation
- **cronJobs**: type, itemId, scheduledDate, status, itemData, createdAt, lastRunAt

#### Business Logic
- **forms**: Form configurations with fields and submissions
- **tasks**: Kanban board tasks with assignees
- **ideas**: Idea database with task conversion
- **analytics**: Web analytics data
- **assets**: Digital asset metadata
- **products**: Digital product configurations
- **invoices**: Billing invoice data
- **changelogs**: Product update logs
- **reportIssues**: User-reported issues
- **waitlist**: Product waitlist entries

---

## INTEGRATIONS & EXTERNAL SERVICES

### Payment Processing (Polar.sh)
- Subscription management
- One-time payments
- Webhook handling for real-time updates
- Product catalog management
- File upload capabilities

### Email Service (Resend)
- Transactional emails
- Bulk email campaigns
- Template support
- Rate limiting (50 recipients per batch)

### Authentication (Firebase Auth)
- Email/password authentication
- Google OAuth integration
- User session management
- Email verification

### Deployment (Vercel + GitHub)
- Repository creation from templates
- Automated deployment pipelines
- Environment variable management
- Custom domain support

### Analytics (PostHog + Vercel)
- User behavior tracking
- Conversion funnel analysis
- A/B testing capabilities
- Performance monitoring

---

## SECURITY FEATURES

### Authentication & Authorization
- Firebase Auth with secure token management
- Role-based access control (RBAC)
- HttpOnly cookies for sensitive data
- CSRF protection for OAuth flows

### API Security
- Input validation and sanitization
- Path traversal prevention
- Webhook signature verification
- Bearer token authentication for CRON jobs

### Data Protection
- Secure environment variable handling
- Firebase security rules
- Encrypted data transmission
- GDPR compliance features

---

## KEY WORKFLOWS

### User Registration & Onboarding
1. User signs up via Firebase Auth
2. Email verification sent
3. Profile completion
4. Subscription selection (optional)
5. Welcome email sent
6. Admin dashboard access

### Content Creation
1. Author creates content in admin
2. Rich text editing with Tiptap
3. Image/file uploads
4. Scheduling or immediate publishing
5. SEO optimization
6. Analytics tracking

### Payment Processing
1. User selects subscription plan
2. Polar checkout session created
3. Payment processing via Polar
4. Webhook updates database
5. Confirmation email sent
6. Access granted

### Deployment Pipeline
1. User configures project in builder
2. GitHub repository created
3. Environment variables set
4. Vercel project created
5. Deployment triggered
6. Live URL returned

### Email Campaign
1. Admin creates email campaign
2. Content composed with editor
3. Audience selected (subscribers/users)
4. Scheduled or sent immediately
5. Delivery tracking
6. Analytics and reporting

---

## CONFIGURATION & ENVIRONMENT

### Required Environment Variables
- **Firebase**: API keys, project configuration
- **Polar**: Access token, webhook secret, API URLs
- **Resend**: API key, from email address
- **GitHub**: OAuth credentials, template repository
- **Vercel**: API token for deployments
- **PostHog**: Project API key
- **Analytics**: Tracking IDs

### Build Configuration
- Next.js configuration with custom headers
- Tailwind CSS with custom design system
- PostCSS configuration
- Vercel deployment configuration

---

## DEVELOPMENT & DEPLOYMENT

### Development Setup
- npm/yarn for package management
- Firebase emulator for local development
- Environment variable configuration
- Hot reloading with Next.js

### Production Deployment
- Vercel for hosting and scaling
- GitHub for source control
- Automated CI/CD pipelines
- Environment-specific configurations

### Monitoring & Maintenance
- Error tracking and logging
- Performance monitoring
- Database backups
- Security updates

---

## CONCLUSION

BuildSaaS provides a complete foundation for building and launching SaaS applications. It includes everything from user authentication and payment processing to content management and automated deployment. The codebase is well-structured, follows best practices, and integrates with modern SaaS tools and services.

The admin panel offers comprehensive business management capabilities, while the frontend provides an excellent user experience. The backend APIs handle all the complex integrations and data processing needed for a production SaaS application.

This boilerplate significantly reduces development time and provides a solid foundation that can be customized and extended based on specific business requirements.