Notification & Email Service

Relevant source files

The following files were used as context for generating this wiki page:

• server/services/email.ts
• server/routers/projects.ts
• client/src/pages/ProjectDetail.tsx
• client/src/pages/Estimator.tsx
• README.md
• todo.md

The Notification & Email Service is a backend utility within the Driveway Estimator Pro platform designed to facilitate communication between homeowners and contractors. Its primary purpose is to deliver project estimates, summaries, and sharing links via email to ensure all stakeholders have access to the generated driveway data.

Within the current architecture, the service acts as a bridge between the Project Management System and external users. While the current implementation is a mock service that logs notifications to the console, it is structured to support production integration with providers like SendGrid, AWS SES, or Postmark.
Sources: server/services/email.ts:7-11, README.md:14-15, todo.md:61

System Architecture

The service operates as a downstream dependency of the tRPC project router. Notifications are triggered either automatically during project creation or manually when a user initiates a sharing action from the client interface.

Data Flow Overview

The following diagram illustrates how project data flows from the user interface through the backend routers into the email service.

A flowchart showing the progression of notification data from the UI to the final transport layer.
Sources: server/routers/projects.ts:250-280, server/services/email.ts:133-145

Core Service Components

The service is built around three primary functional areas: notification templates, the core sending engine, and data formatting utilities.

1. Notification Templates

The service provides two distinct templates tailored for different recipients:

• Homeowner Estimates: Focused on providing the project owner with a summary of their area, material choice, and total cost.
• Contractor Notifications: Designed to provide contractors with professional project details and a direct "View Project Details" link to prepare quotes.

2. The Sending Engine

All notifications are processed through a centralized, internal sendEmail function that handles the asynchronous delivery logic.

Function	Recipient	Trigger Event
sendEstimateNotification	Project Owner	Successful project creation via projects.create
sendContractorNotification	Contractor	Share link generation or initial project creation
sendEmail	Internal Utility	Executes the actual network/log request

Sources: server/services/email.ts:21-72, server/services/email.ts:76-127, server/services/email.ts:133-157

Integration Points

Backend Triggers (tRPC)

The projectsRouter integrates the email service at critical points in the project lifecycle:

• Project Creation: When projects.create is invoked, the router automatically attempts to send an estimate notification to the owner's email. If a contractorEmail was provided during the estimation phase, a notification is also dispatched to the contractor.
• Manual Sharing: The createShareLink procedure allows users to generate a unique shareToken. If an optional contractor email is provided in this request, the service immediately dispatches the project details to that recipient.

A sequence diagram showing the manual sharing flow and the resulting notification.
Sources: server/routers/projects.ts:327-356, server/routers/projects.ts:250-280

Frontend Interface

The client-side implementation leverages these triggers through dedicated UI components:

• Estimator Page: Captures the initial project name and optional contractor email to be stored and notified upon saving.
• Project Detail Page: Features a "Share" dialog where users can input a contractor's email specifically to trigger the createShareLink notification.

Sources: client/src/pages/Estimator.tsx:311-331, client/src/pages/ProjectDetail.tsx:84-118

Technical Implementation Details

Data Structures

The service utilizes a standard interface for all outgoing messages to ensure consistency across different transport implementations.

// server/services/email.ts:13-18
export interface EmailNotification {
  to: string;
  subject: string;
  html: string;
  text?: string;
}

Material Formatting

To ensure professional presentation in email templates, the service includes a private utility to map internal material keys (e.g., hotmix) to human-readable strings.

Internal Key	Display Name
hotmix	Hot Mix Asphalt
millings	Asphalt Millings
tar_and_chip	Tar and Chip
gravel	Gravel

Sources: server/services/email.ts:162-171

Production Readiness

As outlined in the project roadmap, the service currently utilizes a mock implementation. For production deployment, the following adjustments are required:

• Provider Integration: Replace the console.log in the sendEmail function with an API call to a provider like SendGrid or AWS SES.
• Environment Configuration: The baseUrl for share links is currently derived from process.env.VITE_FRONTEND_FORGE_API_URL, falling back to localhost:3000. This must be configured for the production domain.
• Error Handling: Current error handling logs to the console; production should include retries or failure alerts.

Sources: server/services/email.ts:133-145, server/routers/projects.ts:346-348, todo.md:61

Conclusion

The Notification & Email Service provides an essential communication layer for Driveway Estimator Pro. By decoupling template logic from the tRPC routers and centralizing the transport through a mock-able sendEmail function, the system maintains a clean separation of concerns while remaining prepared for high-scale production email providers.