PeopleHub Documentation

Supporting Services ​

Overview ​

PeopleHub includes specialized services for notifications and document generation, providing essential supporting functionality for the main HRMS platform.

Notifications Service ​

Overview ​

Centralized email notification engine for the entire PeopleHub platform.

Purpose ​

Handles all email notifications across modules:

  • Leave approvals/rejections
  • Onboarding status updates
  • Performance review reminders
  • Separation workflows
  • System alerts

Technical Stack ​

  • Runtime: Node.js 18.x
  • Framework: Fastify 5.5.0
  • Email Provider: AWS SES (Simple Email Service)
  • Templates: Stored in database
  • Deployment: AWS Lambda

Architecture ​

Deployment: Single Lambda function Memory: 512 MB (lightweight service) Timeout: 10 seconds Trigger: HTTP API calls from other services

Notification Flow ​

  1. Trigger: Another service calls notification API
  2. Template Fetch: Retrieve email template from database
  3. Data Population: Replace placeholders with dynamic data
  4. Send Email: Use AWS SES to send
  5. Log Result: Record delivery status in database

API Endpoints ​

Trigger Notification: POST /api/notifications/trigger

Request Body Example:

json
{
  "templateId": "leave-approved",
  "recipientEmail": "employee@example.com",
  "data": {
    "employeeName": "John Doe",
    "leaveType": "Casual Leave",
    "fromDate": "2025-02-01",
    "toDate": "2025-02-03"
  }
}

Other Endpoints:

  • GET /api/notifications/templates - List all templates
  • POST /api/notifications/templates - Create template (Admin only)

Email Templates ​

Storage: Database table (notification_definition, notification_template)

Template Example:

Subject: Leave Application Approved

Hi {{employeeName}},

Your {{leaveType}} from {{fromDate}} to {{toDate}} has been approved.

Regards,
HR Team

Placeholders: replaced with actual data

Template Management ​

  • Who Creates: HR admins via main frontend
  • Categories: Leave, Performance, Onboarding, Separation, System
  • Languages: Currently English, future support for multiple languages
  • Testing: Preview feature before sending

AWS SES Configuration ​

Sender Email: Verified domain email

Sending Limits:

  • Sandbox: 200 emails/day (dev/staging)
  • Production: 50,000 emails/day (after verification)

Bounce/Complaint Handling: SNS topics configured for monitoring

Notification Types ​

Transactional:

  • Leave approved/rejected
  • Onboarding complete
  • Document uploaded
  • Separation initiated

Reminder:

  • Pending approvals
  • Incomplete onboarding
  • Performance review due

System:

  • Account created
  • Password reset
  • System maintenance alerts

Delivery Tracking ​

Database Logging:

  • Notification ID, recipient email
  • Template used, sent timestamp
  • Status (sent/failed)
  • SES message ID

Failure Handling:

  • Log error details
  • Retry mechanism (up to 3 times)
  • Alert admins if persistent failures

Performance ​

  • Email Sending: <1 second per email
  • Batch Sending: Up to 50 emails in single Lambda invocation
  • SES Latency: <200ms per send

Future Enhancements ​

Planned Features:

  • SMS notifications (AWS SNS)
  • In-app notifications
  • Push notifications (mobile app)
  • Notification preferences (user-configurable)
  • Digest emails (daily summary)

PDF Generation Service ​

Overview ​

Python-based service for generating PDF documents from HTML templates.

Purpose ​

Generates PDF documents for:

  • Offer letters
  • Appointment letters
  • Experience certificates
  • Relieving letters
  • Payslips (future)
  • Custom reports

Technical Stack ​

  • Runtime: Python 3.11+
  • Library: Weazy Print (HTML to PDF conversion)
  • Framework: Fastify wrapper (HTTP endpoint)
  • Deployment: AWS Lambda

Why Python?: Weazy Print is the best HTML-to-PDF library with full CSS support, only available in Python ecosystem.

Architecture ​

Deployment: Separate Lambda function (Python runtime) Memory: 1024 MB (PDF generation is memory-intensive) Timeout: 30 seconds (allow time for complex PDFs) Trigger: HTTP API calls from main API

API Endpoint ​

Generate PDF: POST /api/pdf/generate

Request Example:

json
{
  "templateName": "offer-letter",
  "data": {
    "candidateName": "John Doe",
    "position": "Software Engineer",
    "salary": "₹12,00,000",
    "joiningDate": "2025-02-01"
  },
  "uploadToS3": true,
  "s3Path": "documents/offer-letters/john-doe-offer.pdf"
}

Response:

  • If uploadToS3: Returns S3 file path
  • Otherwise: Returns PDF as binary (base64)

HTML Templates ​

Storage: Templates stored in service code repository

Format: HTML + CSS (full CSS3 support)

Template Example:

html
<!DOCTYPE html>
<html>
<head>
  <style>
    /* Company letterhead styling */
  </style>
</head>
<body>
  <h1>Offer Letter</h1>
  <p>Dear {{candidateName}},</p>
  <p>We are pleased to offer you the position of {{position}}...</p>
</body>
</html>

Weazy Print Features ​

CSS Support:

  • Page breaks (page-break-after, page-break-before)
  • Headers and footers (CSS @page)
  • Page numbering
  • Watermarks
  • Background images

Output Quality: Print-ready PDF (300 DPI)

S3 Integration ​

Workflow:

  1. Generate PDF in memory
  2. Upload to S3 bucket
  3. Return S3 file path
  4. Main API stores path in database

Alternative: Return PDF directly to main API (for immediate download)

Performance ​

  • Simple Document: 1-2 seconds
  • Complex Document (multi-page with images): 3-5 seconds
  • Optimization: Reuse Lambda instances for faster subsequent calls

Use Cases ​

Offer Letter Generation:

  1. HR fills offer details in frontend
  2. Main API calls PDF service with data
  3. PDF generated and uploaded to S3
  4. Link sent to candidate via email

Bulk Certificate Generation:

  1. HR selects multiple employees
  2. Main API calls PDF service for each
  3. Batch generation (parallel Lambda invocations)
  4. All PDFs uploaded to S3

Template Management ​

  • Current: Templates in code repository (requires deployment for changes)
  • Future: Database-stored templates for dynamic updates

Error Handling ​

  • Validation: Ensure all required data provided
  • Timeouts: Lambda timeout set to 30 seconds
  • Memory: Monitor memory usage (complex PDFs)
  • Retry: Main API retries on failure (up to 2 times)

Common Monitoring & Deployment ​

Monitoring ​

Notifications Service Metrics:

  • Emails sent per day
  • Delivery success rate
  • Bounce rate, complaint rate
  • Template usage stats

PDF Service Metrics:

  • PDF generation time
  • Success/failure rate
  • Memory usage
  • Template usage stats

Alarms:

  • High bounce rate (>5%)
  • SES sending quota approaching limit
  • Generation failures
  • Timeout/memory errors

Deployment ​

Tool: Serverless Framework

Notifications Service:

  • Node.js deployment
  • Standard 3-minute deployment time

PDF Service:

  • Python runtime
  • Lambda layer for dependencies
  • Deployment time: ~4 minutes (larger package due to Weazy Print)

Future Enhancements ​

Notifications:

  • Multi-channel support (SMS, push, in-app)
  • User notification preferences
  • Digest emails

PDF Generation:

  • Dynamic template editor (no-code HTML editor)
  • Template versioning
  • Multi-language support
  • Digital signatures on PDFs
  • PDF merging capabilities