Neah/README.md

Neah Email Application

A modern email client built with Next.js, featuring email composition, viewing, and management capabilities.

Email Processing Workflow

The application handles email processing through a centralized workflow:

1. Email Fetching: Emails are fetched through the /api/courrier endpoints using user credentials stored in the database.

2. Email Parsing: Raw email content is parsed using:

   • Server-side: parseEmail function from lib/server/email-parser.ts (which uses simpleParser from the mailparser library)
   • API route: /api/parse-email provides a REST interface to the parser

3. HTML Sanitization: Email HTML content is sanitized and processed using:

   • sanitizeHtml function in lib/utils/email-utils.ts (centralized implementation)
   • DOMPurify with specific configuration to handle email content safely

4. Email Display: Sanitized content is rendered in the UI with proper styling and security measures

5. Email Composition: The ComposeEmail component handles email creation, replying, and forwarding

   • Email is sent through the /api/courrier/send endpoint

Key Features

• Email Fetching and Management: Connect to IMAP servers and manage email fetching and caching logic
• Email Composition: Rich text editor with reply and forwarding capabilities
• Email Display: Secure rendering of HTML emails
• Attachment Handling: View and download attachments

Project Structure

The project follows a modular structure:

• /app - Next.js App Router structure with routes and API endpoints
• /components - React components organized by domain
• /lib - Core library code:
  • /server - Server-only code like email parsing
  • /services - Domain-specific services, including email service
  • /reducers - State management logic
  • /utils - Utility functions including the centralized email formatter

Technologies

• Next.js 14+ with App Router
• React Server Components
• TailwindCSS for styling
• Mailparser for email parsing
• ImapFlow for email fetching
• DOMPurify for HTML sanitization
• Redis for caching

State Management

Email state is managed through React context and reducers, with server data fetched through React Server Components or client-side API calls as needed.

Email Formatting

Centralized Email Formatter

All email formatting is now handled by a centralized formatter in lib/utils/email-utils.ts. This ensures consistent handling of:

• Reply and forward formatting
• HTML sanitization
• RTL/LTR text direction
• MIME encoding and decoding for email composition

Key functions include:

• formatForwardedEmail: Format emails for forwarding
• formatReplyEmail: Format emails for replying
• sanitizeHtml: Safely sanitize HTML email content
• formatEmailForReplyOrForward: Compatibility function for both
• decodeComposeContent: Parse MIME content for email composition
• encodeComposeContent: Create MIME-formatted content for sending emails

This centralized approach prevents formatting inconsistencies and direction problems when dealing with emails in different languages.

Deprecated Functions

Several functions have been deprecated and removed in favor of centralized implementations:

• Check the DEPRECATED_FUNCTIONS.md file for a complete list of deprecated functions and their replacements.