Service layer with proper separation of concerns. Each service handles a specific domain:

• Email Service (email.service.ts): Email communication and template formatting
• Notion Service (notion.service.ts): Notion API integration for database and file operations
• OpenAI Service (openai.service.ts): AI/ML processing and analysis

Services should:

• ✅ Have a single responsibility
• ✅ Be reusable across different controllers
• ✅ Handle their own error cases gracefully
• ✅ Return consistent response formats
• ❌ Not call controllers or handlers directly
• ❌ Not mix presentation logic with business logic

Purpose: Centralized email communication with template management

Key Functions:

• sendProcessingAcknowledgment() - Immediate user feedback
• sendProcessingCompletion() - Final status notification
• sendProcessingError() - Error notifications

Features:

• Text and HTML email templates
• Consistent styling and branding
• Graceful error handling (email failures don't break processing)

Purpose: Notion API integration for database queries and page updates

Key Functions:

• Generic functions: updatePageProperties() for any property updates
• Content management: Page content creation, updates, and deletion
• Database operations: Query databases and retrieve pages
• File Upload API: 3-step file upload process implementation
  • createNotionFileUpload() - Step 1: Create upload object
  • uploadFileToNotionUrl() - Step 2: Upload file contents via FormData
  • attachFileUploadToPage() - Step 3: Attach file to page with "file_upload" type

Purpose: OpenAI API integration with two-stage consensus analysis

Key Functions:

• Stage 1: Individual transcript analysis using gpt-4o-mini for cost efficiency
• Stage 2: Consensus synthesis using gpt-4o for high-quality reasoning

Features:

• Structured JSON output, confidence scoring, disagreement tracking, evidence tables
• Configurable parallel processing with rate limiting
• Graceful error handling with fallback consensus calculation

import { sendProcessingAcknowledgment } from "../services/email.service.ts";

await sendProcessingAcknowledgment({
  originalEmail: email,
  processingId: "abc123",
  pdfCount: 5
});

Use /test-async-email-processing?email=your@email.com&count=3 to test the complete workflow.