A modern, production-ready SaaS dashboard application with multi-tenant architecture, billing integration, and Google API integrations.

YustBoard is a fully-featured SaaS dashboard application built with Next.js 15, TypeScript, and PostgreSQL. It includes complete multi-tenant architecture, Stripe billing integration, RBAC system, and various dashboard widgets with Google API integrations.

• ✅ Multi-Tenant Architecture - Complete organization management with RBAC
• ✅ Stripe Billing - 4-tier subscription plans with usage tracking
• ✅ Authentication - NextAuth.js with Google OAuth & credentials
• ✅ Email System - Automated notifications via Resend
• ✅ Dashboard Widgets - Timeline, Gmail, Calendar, Weather, News, Banking, Files
• ✅ Organization Branding - Custom logos and color schemes
• ✅ Team Collaboration - Invite system with role management
• ✅ High Performance - React Query caching, HTTP caching, optimized database queries
• ✅ Production Ready - 88 passing tests, CI/CD pipeline, monitoring

• Node.js 18.x or higher
• PostgreSQL database (Neon/Supabase recommended)
• Google Cloud account (for Gmail/Calendar features)
• Stripe account (for billing features)

1. Clone the repository

git clone https://github.com/yustinTR/yustboard.git
cd yustboard

2. Install dependencies

npm install

3. Configure environment variables

Create a .env.local file:

# Database (Neon/Supabase)
DATABASE_URL="postgresql://..."
DIRECT_URL="postgresql://..."

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_secret_here  # Generate: openssl rand -base64 32

# Google OAuth (Optional)
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

# Stripe Billing
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Email (Resend)
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=[email protected]

# APIs (Optional)
NEWS_API_KEY=your_news_api_key
OPENWEATHER_API_KEY=your_weather_api_key

4. Setup database

npx prisma generate
npx prisma db push

5. Run development server

npm run dev

Visit http://localhost:3000 🎉

All documentation is located in the docs/ folder:

Before making any changes:

1. Development Guidelines (CLAUDE.md) - Pre-commit requirements, code standards
2. Production Readiness Report - Current status, deployment checklist

For deployment:

1. Deployment Guide - GitHub Actions + Vercel strategy
2. Production Readiness - Environment checklist

npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint
npm run typecheck    # TypeScript type checking

npm run test:unit      # Run unit tests (88 tests)
npm run test:coverage  # Run with coverage report
npm run test:e2e       # Run E2E tests (Playwright)

# Run ALL before committing:
npm run test:unit      # Must pass (88 tests)
npm run lint           # Must pass (0 errors)
npm run typecheck      # Must pass
npm run build          # Must pass

npm run storybook      # Start Storybook dev server
npm run build-storybook # Build Storybook static

yustboard/
├── app/                      # Next.js App Router
│   ├── api/                 # API routes (65+ endpoints)
│   ├── dashboard/           # Dashboard pages & widgets
│   ├── (auth)/             # Auth pages (login, register, etc.)
│   └── onboarding/         # Organization onboarding flow
├── components/              # React components
│   ├── ui/                 # Base UI components
│   ├── dashboard/          # Dashboard-specific components
│   ├── molecules/          # Composite components
│   └── billing/            # Billing components
├── lib/                     # Core libraries
│   ├── auth/               # Authentication logic
│   ├── database/           # Prisma client
│   ├── email/              # Email service (Resend)
│   ├── notifications/      # Notification system
│   ├── permissions/        # RBAC system
│   └── stripe/             # Stripe billing
├── prisma/                  # Database schema & migrations
├── docs/                    # All documentation
├── .github/workflows/       # CI/CD pipelines
└── tests/                   # Test files

• Framework: Next.js 15.5.2 (App Router)
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS (Glass morphism design)
• UI Components: Custom glass morphism components
• State: React Server Components + Client Components
• Caching: React Query (TanStack Query) for client-side caching

• Database: PostgreSQL (Neon/Supabase)
• ORM: Prisma 6.15.0
• Authentication: NextAuth.js (Google OAuth + Credentials)
• Email: Resend with React Email templates
• Billing: Stripe (4 subscription tiers)
• Storage: Supabase Storage (avatars, logos)

• Hosting: Vercel
• CI/CD: GitHub Actions (4 workflows)
• Monitoring: Health check endpoint
• Security: RBAC, CSRF protection, security headers
• Performance: HTTP caching, database indexing, code splitting

• Unit Tests: Vitest (88 tests)
• E2E Tests: Playwright
• Component Testing: Storybook
• Linting: ESLint (0 errors)
• Type Checking: TypeScript strict mode

• ✅ HTTP Caching - Cache-Control headers on 10+ API routes (60-80% API reduction)
• ✅ React Query - Client-side caching with automatic deduplication (85-90% fewer duplicate requests)
• ✅ Database Indexing - 13 strategic indexes (40-70% faster queries)
• ✅ Code Splitting - Dynamic imports for heavy components (9% bundle reduction)
• ✅ Image Optimization - Next.js Image with WebP conversion & lazy loading
• ✅ Batch Operations - Optimized database writes (12x faster)
• ✅ Stale-While-Revalidate - Instant responses with background updates

Expected Lighthouse Score: 85-95 (Performance)

See Performance Optimizations for detailed benchmarks.

• ✅ bcryptjs password hashing (tested)
• ✅ NextAuth.js session management
• ✅ RBAC with 4 roles (OWNER, ADMIN, MEMBER, VIEWER)
• ✅ Multi-tenant database isolation
• ✅ Security headers (XSS, CSRF, Frame protection)
• ✅ Environment validation
• ✅ SQL injection protection (Prisma ORM)
• ✅ Secret scanning (TruffleHog in CI/CD)

• Organization management
• User onboarding flow (2-step wizard)
• RBAC system (29 permission tests)
• Team invitations with email
• Notification system

• Stripe integration (FREE, STARTER, PRO, ENTERPRISE)
• Organization branding (logos, colors)
• Usage tracking & limits
• Subscription management
• Customer portal

• Timeline (social posts with comments & likes)
• Gmail integration
• Google Calendar sync
• Weather widget
• News aggregator
• Banking transactions (via Gmail parsing)
• File management (Google Drive)
• Announcements system

The project includes a complete CI/CD pipeline with GitHub Actions:

1. Quality Gate - Type check, lint, tests, build
2. Security Scanning - NPM audit, CodeQL, secret scan
3. Performance Monitoring - Lighthouse CI
4. Automated Preview - Every PR gets a preview URL

See Deployment Guide for detailed instructions.

Required for production:

• ✅ DATABASE_URL (Neon/Supabase)
• ✅ DIRECT_URL (Direct connection)
• ✅ NEXTAUTH_URL (Production domain)
• ✅ NEXTAUTH_SECRET (Strong random secret)
• ✅ STRIPE_SECRET_KEY (Live mode)
• ✅ STRIPE_WEBHOOK_SECRET (Production webhook)
• ✅ RESEND_API_KEY (Production key)
• ✅ RESEND_FROM_EMAIL (Verified domain)

Optional:

• ⚠️ GOOGLE_CLIENT_ID (For Gmail/Calendar)
• ⚠️ GOOGLE_CLIENT_SECRET
• ⚠️ NEWS_API_KEY
• ⚠️ OPENWEATHER_API_KEY

88 unit tests covering critical functionality:

✓ lib/auth/auth-utils.test.ts (7 tests)      # Authentication
✓ lib/email/resend.test.ts (12 tests)        # Email service
✓ lib/notifications/create.test.ts (12 tests) # Notifications
✓ lib/permissions/check.test.ts (29 tests)   # RBAC
✓ lib/stripe/config.test.ts (28 tests)       # Billing

Run tests:

npm run test:unit      # All tests
npm run test:coverage  # With coverage report

See SAAS-ROADMAP.md for:

• ✅ Completed features (Phases 1.1-2.2)
• 🔄 In progress features
• 📋 Planned features (Team collaboration, Admin dashboard, Marketing website)

Before committing, run:

npm run test:unit  # 88 tests must pass
npm run lint       # 0 errors required
npm run typecheck  # Must pass
npm run build      # Must succeed

See Development Guidelines for detailed standards.

• ✅ TypeScript strict mode (no any types)
• ✅ ESLint compliance (0 errors, 0 warnings)
• ✅ Glass morphism design system
• ✅ Component-based architecture
• ✅ Comprehensive testing

Build Failures

rm -rf .next node_modules
npm install
npm run build

Database Issues

npx prisma generate
npx prisma db push

Vercel Deployment Fails

• Check environment variables are set
• Verify DATABASE_URL is accessible
• Check build logs for specific errors
• Try redeploying (sometimes transient issues)

See Deployment Guide for more troubleshooting.

This project is private and proprietary.

Lead Developer: Yustin Troost AI Assistant: Claude Code (Anthropic)

For issues or questions:

1. Check Documentation
2. Review Production Readiness Report
3. Check GitHub Issues

Status: ✅ Production Ready | Version: 1.0.0 | Last Updated: 2025-10-20