project logoREADME.md

Services

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

Architecture Principles

Separation of Concerns

  • 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

Service Boundaries

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

Available Services

Email Service (email.service.ts)

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)

Notion Service (notion.service.ts)

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

OpenAI Service (openai.service.ts)

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

Usage Examples

Email Service

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

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

Testing

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