BetterMail : Email Management System

▶️ Preview Demo

Run on Local Machine

Follow these steps to set up and run the project locally:

1. Clone the repository

   git clone https://github.com/nerdyabhi/betterMail.git
   cd betterMail

2. Create a .env file

   • Create .env in backend folders with your environment variables.

   # LOCAL SETTINGS
    PORT = 3000
    # NODE_ENV = 'development'
    ENCRYPTION_KEY=''
    JWT_SECRET = ''
    STATE_SECRET =''
    DATABASE_URL=''
   
   
    # Google OAuth
    GOOGLE_AUTH_CLIENT_ID = ''
    GOOGLE_AUTH_CLIENT_SECRET = ''
   
    # Outlook OAuth
    OUTLOOK_AUTH_CLIENT_ID = ''
    OUTLOOK_AUTH_CLIENT_SECRET=''
   
   
    # ELASTIC SEARCH
    ELASTICSEARCH_API = ''
    ELASTICSEARCH_URL=''
    ELASTICSEARCH_INDEX =''
   
   
    # GEMINI
    # GEMINI_API_KEY=''
   
    # SLACK
    SLACK_WEBHOOK_URL=''
    SLACK_CLIENT_ID=''
    SLACK_CLIENT_SECRET=''
    SLACK_REDIRECT_URI=''
   
    # PINECONE
    PINECONE_HOST=''
    PINE_CONE_API=''

3. Start the Frontend

   cd frontend
   npm install
   npm run dev

4. Start the Backend

   cd ../backend
   npm install
   npm run start

5. Drizzle Kit Commands (Database)

   • Generate migrations:

     npm run db:generate

   • Run migrations:

     npm run db:migrate

   • Open Drizzle Studio:

     npm run db:studio

Flow of the APP

Main Application Flow

The complete application workflow includes:

User Authentication & IMAP Setup

1. User Login: User logs into the system
2. IMAP Account: User adds their IMAP account credentials
3. Email Categorization: Gemini AI categorizes incoming emails
4. Elastic Search: Emails are stored in Elasticsearch database with indexing

Email Processing Pipeline

5. Pinecone Embeddings: Create and store vector embeddings for sent emails
6. Background Monitoring: System runs in IDLE mode, listening for new emails
7. New Email Handler: When new emails arrive, the system processes them
8. AI Suggestions: Generate intelligent reply suggestions
9. Elasticsearch Storage: Classify and store emails with proper indexing
10. Slack Integration: Send notifications via Slack webhook

Email Data Structure

{
  "email_data": {
    "subject": "string",
    "category": "string",
    "content": "string"
  },
  "category": "interested/spam/work etc",
  "type": "sent/received",
  "userId": "user's uniqueID",
  "emailAddress": "string"
}

AI Suggestions Flow

The AI suggestions system works in three main steps:

1. User Action: User clicks on an email
2. Pinecone Integration: Find related embeddings from Pinecone database based on previous replies by the user
3. Gemini AI: Use those embeddings to generate 3-5 appropriate reply suggestions using GEMINI

Tech Stack

• Backend: Node.js with Express & TypeScript
• Database: PostgreSQL with Drizzle ORM
• Vector Database: Pinecone for embeddings
• Search Engine: Elasticsearch
• AI Services: Google Gemini AI
• Email Protocol: IMAP for email fetching
• Notifications: Slack Webhook integration
• Package Manager: Bun