SaaS Boilerplate Architecture Overview¶

Document Type: Brownfield Project Documentation Generated: 2026-02-12 | Last Full Rescan: 2026-03-26 | Scan Level: Exhaustive | Workflow: document-project v1.2.0 Project Type: Multi-Part SaaS Application (Backend + Frontend + Docs)

Executive Summary¶

This is a production-ready SaaS boilerplate consisting of two independently deployable applications:

High-Level Architecture¶

                    +------------------+
                    |    Netlify CDN   |
                    |   (Frontend)     |
                    +--------+---------+
                             |
                    HTTPS REST API calls
                             |
                    +--------v---------+
                    |  Vercel Edge     |
                    |   (Backend)      |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
        +-----v-----+  +-----v-----+  +-----v-----+
        | PostgreSQL|  | Cloudinary|  |  Stripe   |
        | (TypeORM) |  |  (Files)  |  | (Payments)|
        +-----------+  +-----------+  +-----------+

Key Features¶

Authentication & Authorization¶

• Multi-provider authentication (Email/Password, Google OAuth, OTP-based login)
• JWT access tokens with refresh token rotation
• Two-factor authentication (Email OTP, Google Authenticator)
• Role-Based Access Control (RBAC) with route-level permissions
• Login attempt tracking with account lockout

Subscription & Payments¶

• Stripe integration for recurring subscriptions
• LemonSqueezy as alternative payment provider
• Package-based subscription tiers (Trial, Monthly, Yearly)
• Coupon/discount code support

Content Management¶

• Blog system with categories, tags, and SEO (M:M categories, blog tags, view tracking)
• Generic pages with rich text (BlockNote editor)
• Dynamic menu builder v2 with drag-and-drop nested items (@dnd-kit)
• Product catalog with categories
• Email template visual builder (disconnected from email sending pipeline)

Admin Dashboard¶

• User management with invite-only mode
• Role and permission management UI
• Site settings with edit-in-place and theme customization (Google Fonts, colors, dark mode)
• Analytics dashboard
• Contact message management
• Cache revalidation management (tag-based, bulk, all)
• AI voice integration module (experimental)

Technology Stack Summary¶

Backend Technologies¶

Frontend Technologies¶

Codebase Metrics (2026-03-26)¶

Documentation Index¶

• Backend Architecture — Express.js API structure, 30 modules, 212 endpoints, 14 middleware, event system
• Frontend Architecture — Next.js app structure, 74 pages, 239 components, 139 API hooks
• Database Schema — 29 entities, ~233 columns, 30 relations, 11 enums
• API Reference — 212 REST endpoints across 30 modules, authentication, response formats
• Integration Guide — Frontend-backend communication, auth flow, cache revalidation, payments

Quick Start¶

Backend¶

cd saas-boilerplate
yarn install
# Configure .env from .env.example
yarn dev  # Starts on port 5500

Frontend¶

cd Sass-boilerplate-frontend-v1
npm install
# Set NEXT_PUBLIC_API_URL=http://localhost:5500/api/v1
npm run dev  # Starts on port 3000

Environment Dependencies¶

Runtime Requirements¶

• Node.js 18.17+ (required for both backend and frontend)
• PostgreSQL 14+

Backend Required Services¶

• SMTP server (or Resend/Brevo API key)
• Stripe account (for payments)
• Cloudinary account (for file uploads)

Frontend Required¶

• Backend API URL configured
• Cookie domain configuration for auth

Generated by BMAD Document Project workflow v1.2.0 — Exhaustive scan, 2026-02-12 | Last full rescan: 2026-03-26