MailWise 🦉 (Full-Stack Student Inbox Organizer)

MailWise is a premium, full-stack student organizer that aggregates a student's real-time Gmail inbox, categorizes every incoming mail using Claude 3.5 Sonnet (with automatic highly-accurate heuristic parsing fallback), tracks deliverables/deadlines, and visualizes sync history inside a task-management dashboard.

This guide provides the exact step-by-step walkthrough to create Google OAuth 2.0 credentials on the Google Cloud Console and plug them into your environment to unlock 100% real Google Sign-In and Live Gmail Synchronization!

---

🚀 Setting Up Google OAuth 2.0 & Gmail API

To connect the application to the real Google OAuth and Gmail servers, follow these steps to generate your unique credentials:

Step 1: Create a Google Cloud Project

1. Go to the Google Cloud Console.
2. Log in with your Google Account.
3. Click the Project Dropdown at the top left of the navbar and click New Project.
4. Name your project (e.g. MailWise) and click Create.

Step 2: Enable the Gmail API

1. In the Google Cloud Console sidebar, navigate to APIs & Services > Library.
2. Search for "Gmail API" in the search bar.
3. Click on the Gmail API card and click the blue Enable button.

Step 3: Configure the OAuth Consent Screen

Before creating credentials, you must describe the application's consent screen to Google:

1. In the sidebar, navigate to APIs & Services > OAuth Consent Screen.
2. Select External as the User Type and click Create.
3. Fill in the required fields:
   • App Name: MailWise
   • User Support Email: Select your Google email.
   • Developer Contact Information: Enter your email address.
4. Click Save and Continue.
5. Under Scopes, click Add or Remove Scopes.
6. Manually copy-paste or check the following three scopes:
   • .../auth/userinfo.email (Read email address)
   • .../auth/userinfo.profile (Read basic profile avatar & name)
   • https://www.googleapis.com/auth/gmail.readonly (Read-only access to your Gmail messages)
7. Click Save and Continue.
8. Under Test Users, click Add Users and enter your personal Google email address (this is required to authenticate while your app is in testing mode).
9. Click Save and Continue and review the summary.

Step 4: Create OAuth 2.0 Client Credentials

1. In the sidebar, navigate to APIs & Services > Credentials.
2. Click + Create Credentials at the top and select OAuth Client ID.
3. Under Application Type, select Web Application.
4. Configure the following redirect endpoints:
   • Authorized JavaScript Origins:
     • http://localhost:5000
     • http://localhost:5173
   • Authorized Redirect URIs:
     • http://localhost:5000/api/auth/google/callback
5. Click Create.
6. A modal will pop up displaying your Client ID and Client Secret. Copy these values!

---

⚙️ Configuring the Environment Variables

Open the backend configuration file located at server/.env and replace the placeholder values with your real Google credentials:

PORT=5000
MONGODB_URI=mongodb://127.0.0.1:27017/mailwise
JWT_SECRET=mailwise_super_secure_secret_token_jwt_2026

# Paste your Google Credentials here:
GOOGLE_CLIENT_ID=YOUR_REAL_GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET=YOUR_REAL_GOOGLE_CLIENT_SECRET
GOOGLE_REDIRECT_URI=http://localhost:5000/api/auth/google/callback

# Paste your Anthropic API Key for real-time Claude categorization (Optional):
# If left as placeholder, the app uses a highly accurate local heuristic categorizer
ANTHROPIC_API_KEY=your_anthropic_key

CLIENT_URL=http://localhost:5173

---

🏃 Launching the Application

Ensure your local MongoDB instance is active. Then launch the client and server services:

1. Start Backend Server

cd server
npm install
npm run dev

The server will boot on http://localhost:5000. You should see [DATABASE] MongoDB connected successfully. and [PASSPORT] Google OAuth strategy registered successfully. in the terminal logs.

2. Start Frontend Dev Client

cd client
npm install
npm run dev

The Vite development server will start on http://localhost:5173. Open your web browser and click "Continue with Google"!

Once you log in, Google will safely prompt you to authorize MailWise, issue security tokens, automatically start historical sync in the background, and redirect you to the main MailWise analytics workspace dashboard!