Documentation

Overview

Credenza is a Next.js application for generating personalized certificates, previewing name placement, and sending certificates by email in bulk. Certificates are rendered from a template image, converted to PDF during email flow, uploaded to Supabase Storage, and shared using expiring signed links.

• Frontend: interactive template preview, style controls, and recipient management.
• Backend: streaming send API for live status updates while emails are sent.
• Storage: Supabase bucket for generated certificate PDFs.
• Email: Gmail SMTP via Nodemailer.

Quick Start

1. Install dependencies with npm install.
2. Create a .env file and set SMTP + Supabase values.
3. Run npm run dev and open http://localhost:3000.
4. Upload your certificate template image.
5. Set text position and style in the preview tab.
6. Add recipients manually or import CSV/TXT.
7. Generate downloads or send certificates by email.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-gmail-app-password
SMTP_FROM=your-email@gmail.com
SMTP_SECURE=false

NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Project Structure

Core areas of the codebase:

• app/page.tsx: main workflow and UI state orchestration.
• app/api/certificates/send/route.ts: streaming email send endpoint.
• components/: uploader, preview, style controls, recipient manager, generate panel, header, footer.
• lib/canvas.ts: draws participant names on uploaded template image.
• lib/pdf.ts: PDF generation and ZIP packing helpers.
• lib/supabase-storage.ts: upload and signed URL generation for certificate PDFs.

Certificate Generation

The generation flow renders one certificate per recipient using a shared template image and text styling.

• Template upload supports common image formats used for certificate designs.
• Preview tab supports click-to-place positioning plus guide/grid overlays.
• Style controls include x/y position, font size, family, color, weight, and italic toggle.
• Output options: PNG ZIP download and PDF ZIP download.

Rendering is performed per recipient and progress is displayed in the UI to keep long batches observable.

Email Integration

Email sending is handled by the server endpoint and streams live status updates back to the UI.

• Transport: Gmail SMTP through Nodemailer.
• Subject format: generated from project name.
• Body format: standardized congratulatory message with download button and fallback link.
• Links: signed Supabase URLs with expiry timestamp in the message.
• Retries: failed recipients can be resent from the Generate tab.

Batch Processing

Credenza supports high-volume runs with recipient-level progress and partial failure handling.

• Add recipients manually as name + email pairs.
• Import CSV/TXT for faster onboarding of large cohorts.
• Generation and send progress are shown per recipient.
• Completion summary includes sent, failed, and total counts.

API Reference

Primary endpoint used by the app:

Stream event types emitted by the endpoint:

• batch-created: confirms total certificates queued.
• recipient-status: pending, sending, sent, or failed for each recipient.
• complete: final batch summary including failed recipients.
• error: unrecoverable batch-level error details.

Security and Storage

• Certificates are uploaded to Supabase Storage, not local server disk.
• Signed URLs are time-bound and automatically expire.
• Service role key should only be used server-side and never exposed client-side.
• Use Gmail app passwords for SMTP authentication.

Troubleshooting

Deployment Notes

• Set all SMTP and Supabase environment variables in your deployment platform.
• Do not commit real secrets to version control.
• Use production-safe sender email and verify provider limits for your expected batch size.