Skip to content

Latest commit

 

History

History
187 lines (127 loc) · 4.4 KB

README.md

File metadata and controls

187 lines (127 loc) · 4.4 KB

Mailplain

Mailplain is a modern, AI-powered email client built with Next.js 14, featuring real-time mail processing, third-party integrations (Aurinko, Stripe, OpenAI), and a secure role-based system backed by Clerk. This document serves as comprehensive technical documentation including setup, structure, architecture, APIs, and deployment.

🚀 Project Setup

Clone & Install

git clone https://github.com/zdemirgithub/mailplain.git
cd mailplain
npm install
cp .env.example .env

Run Locally

npm run dev

Environment Variables

NEXT_PUBLIC_URL=http://localhost:3000

CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

AURINKO_CLIENT_ID=
AURINKO_CLIENT_SECRET=

OPENAI_API_KEY=
DATABASE_URL=

🧱 Project Structure

mailplain/
├── src/
│   ├── app/               # Next.js App Router pages
│   ├── components/        # UI components
│   ├── lib/               # Business logic (Aurinko, Stripe, OpenAI)
│   ├── hooks/             # Custom React hooks
│   ├── server/            # tRPC routers and DB access
│   ├── styles/            # Global styles
│   ├── trpc/              # tRPC utils (context, router)
│   └── middleware.ts      # Clerk route protection middleware
│
├── prisma/                # Prisma schema + migrations
├── public/                # Public static assets
├── .env.example           # Environment config
└── README.md

📐 Architecture Diagram

     +--------------+      +---------------+
     |   Frontend   | <--> |  Next.js App  |
     | (React/Tail) |      |   (API + UI)  |
     +--------------+      +---------------+
            |                      |
            v                      v
    Clerk (Auth)          tRPC Routers (Server)
            |                      |
            v                      v
  Stripe <--> Webhooks <--> Business Logic (lib)
            |                      |
            v                      v
         OpenAI                Aurinko (Mail API)
            |                      |
            v                      v
        Role/Auth           Prisma + Neon DB

📦 Feature Overview

  • Authentication: Clerk (JWT, RBAC)
  • Subscriptions: Stripe (Webhook + Limits)
  • Mail Integration: Aurinko API
  • AI Summaries: OpenAI Completion API
  • Email Parsing: Custom logic via lib/aurinko.ts
  • Database Management: NeonDB, PostgreSQL, Prisma
  • Search Engine: Orama (semantic email search)

📚 Technical API Reference

🔹 tRPC API (Server Only)

Mail Router

  • listAccounts() → List all connected email accounts
  • sendMail({to, subject, body}) → Send new email
  • syncMail() → Trigger a full sync

Webhooks Router

  • getWebhooks({ accountId }) → List active webhooks
  • createWebhook({ accountId, notificationUrl }) → Register new webhook
  • deleteWebhook({ accountId, webhookId }) → Remove webhook

Search Router

  • search({ query }) → Semantic full-text search over mail using Pinecone

🔹 REST Webhooks

  • POST /api/stripe/webhook

    • Stripe payment and subscription webhook handler

  • POST /api/aurinko/webhook

    • Handles new email events from Aurinko

🔎 Tests

Unit Tests: src/__tests__/unit

  • Isolated logic: middleware, utility functions, auth

Integration Tests: src/__tests__/integration

  • API calls, DB queries, multi-module workflows

E2E Tests: __tests__/e2e

  • Simulate user login, dashboard navigation, Stripe payment

☁️ Deployment (Vercel)

1. Push to GitHub

git init
git remote add origin https://github.com/yourname/mailplain.git
git push -u origin main

2. Connect to Vercel

  • Go to vercel.com
  • Import project from GitHub
  • Set environment variables

3. Configure Webhooks

  • Stripe: Dashboard → Webhooks → Add endpoint https://yourdomain.com/api/stripe/webhook
  • Aurinko: Auth during email setup triggers internal /api/aurinko/webhook

🧠 Contributors Guide

  • Prefer tRPC over REST for internal APIs
  • Use Clerk's auth() in server-only environments
  • Follow consistent error handling using try/catch and zod
  • All PRs should include unit or integration tests

📌 License

MIT

For issues, contact zdemirgithub.