Reports · Notifications Module

The Report Writes
Itself. Then It
Emails Itself.

Once the extraction engine has scored every discipline, this module takes over: a styled HTML report is generated, converted to PDF, and pushed out over email and Telegram — while the web dashboard and mobile app update in real time over the same WebSocket connection.

Core Capabilities

What Reports · Notifications Does

A single webhook call from the automation workflow triggers the entire distribution chain — report, PDF, email, Telegram, dashboard broadcast, and a database log entry — with each step running independently so a failed email doesn't block the Telegram send.

📄
HTML Report Generator
Executive summary, performance rankings table, per-discipline breakdown, and priority-sorted recommendations — assembled from the extraction engine's output automatically.
🖨️
PDF Conversion
The HTML report is converted to a print-ready PDF via the html2pdf API, with retry logic and a fallback path if the conversion service is unreachable.
✉️
Email Distribution
Nodemailer sends a formatted HTML email with the PDF attached to a configurable recipient list — Gmail, SendGrid, or any standard SMTP provider.
✈️
Telegram Bot
A Markdown-formatted summary message goes out first, followed by the PDF as a document — useful for anyone checking updates from a phone on-site.
🔔
Live Broadcast
A WebSocket broadcast fires the moment a report finishes, updating the web dashboard and triggering a push notification on mobile without a page refresh.
🗄️
Notification Logging
Every send — success or failure, email or Telegram — is logged to MySQL, giving an audit trail and the data behind the success-rate views.

Audience

Who Receives What

Project Managers

Get the full PDF report by email the moment it's generated — no need to log into the dashboard to see whether last week's numbers moved.

Site Supervisors

Receive the Telegram summary on their phone, with the option to open the attached PDF if the headline numbers warrant a closer look.

Owners & Sponsors

Are added to the email distribution list without needing any dashboard access at all — the report comes to them.

Ops / IT Admins

Use the notification history endpoint and MySQL views to confirm delivery rates and troubleshoot a missed send.

Integration Points

Where This Plugs In

This module is the backend half of the pipeline — it doesn't process documents itself, it receives already-classified, already-scored data from the automation workflow and turns it into something a person actually reads.

Webhook Endpoint POST /api/notifications/webhook — authenticated with an API key, receives disciplineData, crossDiscipline, and metadata from the n8n workflow.
Report → PDF → Notify Report generation, PDF conversion, and both notification channels run via Promise.allSettled so one failure doesn't block the others.
WebSocket Broadcast Uses the same WebSocket server instance shared with the backend's core API, so no separate real-time infrastructure is needed.
Mobile & Web Consumers Both the web dashboard and the mobile app listen for the report_generated and alert broadcast types to refresh their views.

Next Module

The report just landed — now what?

See how the same data reaches a phone in the field through the Mobile App module.

Explore Mobile App → Back to Monitor