EZCV SaaS - Professional CV Builder

Status: Production Ready | Last Updated: 2026-03-20 Context: Main project entry point and local development guide.
Source of Truth: ARCHITECTURE.md (System Design), DEPLOYMENT.md (Production)

---

A modern, elegant CV builder SaaS platform with WYSIWYG editing, multiple templates, and high-quality PDF export.

Overview

EZCV SaaS is a web-based application that allows users to create professional CVs through an intuitive interface. Users can build their CV manually in a split-view editor, customize from a selection of modern templates, and export watermark-free PDFs after a one-time flexible donation.

Core Philosophy: Simple, elegant, and focused. Do one thing well: help people create professional CVs.

Key Features

• Split-View Editor - Real-time preview alongside editing with "Move" tool support and debounced form reactivity
• 5 Professional Templates - Classic, Modern, Minimal, Executive, Creative
• Cover Letters - Create tailored cover letters per CV with inherited styling and configurable limits (controlled by admin)
• Command Menu (Spotlight Search) - Global command palette (Cmd/Ctrl+K) for rapid navigation, theme switching, and document search
• Help Center - Integrated support documentation accessible via the Command Menu for instant guidance
• Articles Hub - Public long-form articles at /articles with admin-managed publishing, protected preview, and an AI-backed planning workflow
• Public CV Links - Share CVs via unique public links with custom slugs for paid users
• Rich Text Editing - TipTap-based editor with native multi-language spellchecking for EFIGS (English US/UK, French, Italian, German, Spanish)
• Performance Optimized - Instant tab switching, granular Next.js server caching, and Smart Tab-Focus Refresh to ensure data freshness after inactivity.
• Rendering Resiliency - Granular error boundaries isolate template crashes to prevent broken PDF exports
• Drag-and-Drop Sections - Reorder CV sections as needed
• Deep Customization - 8 color themes, 8 fonts, 3 spacing presets
• Customizable Section Labels - Pseudo-multilingual support by customizing section headers
• SEO & Web Optimized - OpenGraph branding, canonical WWW redirect, and font-loading optimizations for LCP
• Auto-Save - Never lose your work with intelligent auto-save
• GDPR Data Export - Download all your personal data (profile, CVs, error logs, activity history, and reviews) in one click
• User Review System - Integrated feedback mechanism with internal moderation and landing page testimonials.
• Security Hardened - Real-time session verification (auth-guards), user-linked audit trails (account_linked), non-root containers (PDF Worker), automated secret scanning (Gitleaks), and DAST (OWASP ZAP).
• Strict CSP by Default - Nonce-based script-src, strict style-src, and externalized live template theming for safer preview rendering without inline browser styles
• Modern Infrastructure - Multi-instance horizontal scaling (8 replicas) with hardened sticky sessions, cross-origin protection (COOP/CORP), and advanced Edge-level caching for public CV assets.
• Performance Monitoring - Self-contained Core Web Vitals storage with admin dashboard visualization, plus Sentry reporting and CI-integrated bundle analysis.
• Email Notifications - Welcome, payment, and magic link emails with dynamic provider support (SMTP, Resend, SendGrid) and native dark mode.
• Unified System Monitor - Infrastructure health, runtime metrics, PDF stats, webhook audit with replay, Web Vitals dashboard, and activity pulse — all in one admin page
• AI-Assisted Articles - Admin-only idea generation, briefing, drafting, metadata generation, voice anchors, and settings-driven writer identity/product context
• AI-Driven Changelog - Automated summaries of app updates extracted from Git commits using Google Gemini API
• AI Starter Content - Gemini-powered role-tailored CV drafts (summary, experience, skills) generated during creation with static fallback
• First Free Export - One uninterrupted watermarked PDF export for new users before any payment prompt, with post-export upgrade nudge
• Editor Progress Checklist - Guided first-session checklist showing minimum steps to a usable CV, reactive to editor data
• Activation Funnel Analytics - Stage-based funnel instrumentation from marketing CTA through payment, with admin reporting
• Public Template Gallery - Browse template previews before signup at /templates
• Dark Mode - Full system-based support across web and email templates
• Magic Link & Google OAuth - Frictionless passwordless login with automatic account linking
• Dedicated PDF Worker - High-quality exports via an isolated Puppeteer microservice with Redis caching
• Horizontal Scaling - Native multi-instance support (8 replicas) with sticky sessions and global rate limits

Technology Stack (Summary)

• Frontend: Next.js 16 (App Router), TypeScript, Tailwind CSS 4, shadcn/ui wrappers on Base UI primitives.
• Backend: Server Actions, Prisma 7, PostgreSQL 16, Valibot.
• Infrastructure: Docker, Redis 7 (Rate limiting/Idempotency).
• Monitoring: GlitchTip/Sentry (Error tracking), Health endpoints.
• PDF Core: Puppeteer inside a dedicated Fastify microservice.
• Testing: Vitest (Unit), Playwright (E2E).

For detailed technical specifications, design rationale, and full dependency list, see ARCHITECTURE.md.

Project Structure

ezcv-saas/
├── app/                  # Next.js app directory (pages, layouts, middleware)
├── src/
│   ├── actions/          # Next.js Server Actions
│   ├── components/       # React components (UI, CV, editors, templates)
│   └── lib/              # Utility functions, validations, Prisma client
├── prisma/
│   └── schema.prisma     # Database schema
├── docs/
│   ├── ARCHITECTURE.md   # System design and rationale
│   ├── ROADMAP.md        # Development status and implementation plan
│   └── archive/          # Past session reviews and legacy designs
├── public/               # Static assets
├── docker-compose.yml     # Docker services configuration
└── Dockerfile           # Multi-stage Docker build

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 24+ (We recommend using NVM or nvm-windows)
• Docker & Docker Compose (for running services)
• Git (Download)

Quick Start

1. Start Docker Services

# Clone the repository
git clone <your-repo-url>
cd ezcv-saas

# Start all services
docker-compose up -d

This starts:

• PostgreSQL on port 5432
• Redis on port 6379

2. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration

Required environment variables:

• DATABASE_URL - PostgreSQL connection string

• DIRECT_URL - PostgreSQL direct connection string (optional, for migrations with PgBouncer)

• NEXTAUTH_URL - Your application URL

• NEXTAUTH_SECRET - Secret key for NextAuth.js (generate with openssl rand -base64 32)

• REDIS_URL - Redis connection string

• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

• STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET

Optional environment variables:

• GOOGLE_AI_STUDIO_API_KEY - Enables Gemini-powered changelog generation and article brief/draft assistance
• EMAIL_PROVIDER - Email provider: 'smtp' | 'resend' | 'sendgrid' | 'console' (default: console)
• EMAIL_FROM - From email address
• SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS - SMTP configuration for self-hosted email

For production-specific variables and deployment instructions, see DEPLOYMENT.md.

3. Install Dependencies & Setup Database

# Install npm dependencies
npm install

# Install Playwright browsers (for E2E tests)
npm run playwright:install

# Generate Prisma client
npx prisma generate

# Validate environment variables
npm run start:validate # Or: node scripts/validate-env.js

# Run migrations
npx prisma migrate dev

4. Start Development Server

npm run dev

Visit http://localhost:3000 to see the application.

Testing & Quality

EZCV maintains a high-quality codebase with 90%+ unit/integration test coverage and automated E2E browser testing. Our E2E suite is optimized for robustness across Chromium and WebKit.

npm run test             # Run Vitest test suites
npm run test:coverage    # Generate test coverage report
npm run test:e2e         # Run Playwright E2E tests
npm run test:e2e:ui      # Run Playwright with UI
npm run test:e2e:debug   # Debug Playwright tests

Development Commands

# Development
npm run dev              # Start Next.js development server
npm run build            # Build for production
npm run format           # Format code with Biome
npm run check            # Run Biome checks
npm run lint             # Run ESLint
npm run analyze          # Analyze production bundle size

# Database
npx prisma studio        # Open Prisma Studio (database GUI)
npx prisma generate      # Generate Prisma client
npx prisma migrate dev   # Create and run migrations
npx prisma db push       # Push schema to database

# Docker
docker-compose up        # Start all services
docker-compose up -d     # Start services in detached mode
docker-compose down      # Stop all services
docker-compose logs      # View service logs

Application URLs

Service	URL
Application	http://localhost:3000
Prisma Studio	http://localhost:5555
PostgreSQL	localhost:5432
Redis	localhost:6379

Architecture & Monitoring

The system features a centralized monitoring architecture that combines runtime instrumentation with a real-time status dashboard.

• Unified System Monitor - Real-time monitoring of Database, Redis, Email, PDF performance, Stripe webhooks, and activity audit within a single Admin page (/admin/system).
• Articles - Public knowledge hub at /articles with admin-managed drafts, protected preview, publication workflow, and typography-first article pages.
• AI Changelog - Chronological timeline of updates (/changelog) generated via Gemini AI during CI/CD.
• Centralized Error Logging - Database-backed error tracking (ErrorLog) with severity levels, CSV export, and metadata, accessible via the Admin panel.
• Webhook Replay - Failed Stripe webhooks can be retried directly from the System Monitor with a single click.
• GlitchTip/Sentry - External tracking for unhandled runtime exceptions.
• Automated Database Maintenance - Periodic purge of obsolete logs triggered via the Docker health-check sequence without external crons.

For in-depth documentation on system design, security, payment flows, and PDF generation logic, please refer to:

• ARCHITECTURE.md - System design & rationale
• DEPLOYMENT.md - Production & CI/CD guide
• ROADMAP.md - Project status & future plans
• GLOSSARY.md - Project-specific terminology

Environment Configuration

See DEPLOYMENT.md for production configuration examples and secrets management.

Troubleshooting

Docker Services Won't Start

# Check service status
docker-compose ps

# View logs
docker-compose logs postgres
docker-compose logs redis

# Restart services
docker-compose down
docker-compose up -d

Database Connection Issues

# Verify PostgreSQL is running
docker-compose ps postgres

# Check database logs
docker-compose logs postgres

# Test connection
docker-compose exec postgres psql -U cvsaas -d cvsaas

NextAuth Issues

• Ensure NEXTAUTH_URL matches your application URL exactly
• Generate a secure NEXTAUTH_SECRET:

  openssl rand -base64 32
  

PDF Generation Issues

• PDF generation uses Puppeteer. The node:24-alpine image in our Dockerfile is optimized for this.
• If running on Windows locally, Puppeteer should work out of the box with your installed Chrome.
• Check app logs for Puppeteer launch errors: docker-compose logs app

Documentation

• USER_GUIDE.md - End-user instructions for creating CVs
• DEPLOYMENT.md - Production deployment guide (GitLab CI + Portainer)
• ARCHITECTURE.md - System design, technology decisions, and rationale
• ROADMAP.md - Development status, completed phases, and next steps

Contributing

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes and commit: git commit -m "feat: add feature"
3. Push to branch: git push origin feature/your-feature
4. Open a pull request

License

Proprietary - All rights reserved

Support

For issues, questions, or contributions, please contact the development team.

---

Built with Next.js, TypeScript, Prisma, and Docker.