How nainish-rai/stupid-mails works
<explanation>
1. Project Type and Purpose
- This is a full‑stack web application built on Next.js (App Router) that serves as an AI‑powered email management tool.
- Users connect their Gmail account via OAuth (Better‑Auth), the app pulls emails, uses OpenAI to classify them, stores metadata in PostgreSQL (via Prisma), and surfaces a focused dashboard in the browser.
2. File‑Structure Analysis
- app/ – Next.js pages & API routes (auth, Gmail endpoints, user preferences, waitlist, etc.)
- components/ & app/components/ – React UI building blocks (cards, lists, forms, ShadCN UI components)
- lib/ – Shared logic: Gmail API wrappers, classification helpers, Prisma client, auth utilities, React hooks
- prisma/ – Database schema & migration history
- public/ – Static assets
- memory‑bank/ – Project docs & architectural notes
3. README Insights
- Frontend: Next.js + React + Tailwind CSS + ShadCN UI
- Backend: Next.js API routes, Prisma ORM to PostgreSQL
- Integrations: Gmail API (read‑only OAuth), OpenAI API
- State management: React Query via QueryProvider
- Auth: Better‑Auth
4. How to Draw the System Design Diagram
a. Main Components (draw each as a container):
• Browser UI (Next.js React pages & components)
• API Layer (Next.js server functions under app/api/)
– Auth Module (/api/auth, callbacks, Better‑Auth flows)
– Gmail Service (/api/gmail/connection, /emails, /labels)
– Classification Service (/api/gmail/emails/classify)
– User Settings (/api/preferences, /api/user/classification-settings, /api/sync-preferences)
– Waitlist Endpoint (/api/waitlist)
• Business Logic Library (lib/)
• Database (PostgreSQL via Prisma)
• External Services
– Gmail API (OAuth + REST)
– OpenAI API (GPT classification)
b. Relationships & Data Flows (use directional arrows):
1. User → Browser UI → React Query → API Layer
2. API Layer ↔ Business Logic (lib functions)
3. API Layer → PostgreSQL (Prisma client)
4. API Layer → Gmail API (OAuth token, fetch emails/labels)
5. API Layer → OpenAI API (send email content, receive classification)
6. API Layer → Browser UI (classification results, user preferences)
c. Architectural Patterns & Principles:
– Layered Architecture: UI, API/Business Logic, Persistence, External Integrations
– File‑based Routing (Next.js App Router)
– Separation of Concerns: distinct modules for auth, data access, classification
– Serverless Functions: each API route can be deployed independently (Vercel/AWS Lambda)
– React Query for caching & asynchronous data fetching
d. Key Technologies/Frameworks:
– Next.js (App Router, Server Components, API routes)
– React + ShadCN UI + Tailwind CSS
– Better‑Auth for OAuth flows
– React Query (QueryProvider)
– Prisma ORM + PostgreSQL
– Gmail REST API
– OpenAI GPT API
5. Diagram Tailoring Guidelines (Full‑Stack Focus)
- Draw two primary tiers: Frontend vs. Backend
- Show clearly how the React UI calls API routes via React Query
- Illustrate the OAuth handshake (Browser ↔ Auth API ↔ Gmail API)
- Emphasize state management & caching (QueryProvider)
- Include DB persistence and migrations (Prisma)
- Highlight external API interactions (Gmail & OpenAI)
6. Visual Elements to Include
- Labels: Name each box (e.g., “Gmail Service”, “Classification Engine”)
- Arrows: Show direction of data flow (e.g., HTTP calls, DB reads/writes, API requests)
- Color Coding / Shapes:
• Blue rectangles for user‑facing components (UI)
• Green boxes for backend modules (API routes)
• Orange cylinder for the database
• Red hexagons for external services (Gmail, OpenAI)
- Notes/Annotations: Indicate authentication, error handling, batching steps
7. Final Tips
- Be exhaustive in mapping every API route cluster to its service responsibility.
- Capture the OAuth flow separately to show token retrieval and refresh.
- Show classification as a two‑step pipeline: fetch → clean → GPT classify → store.
- Don’t over‑compress modules; better to show more granular boxes (e.g., separate “Email Fetch” and “Email Classify”).
- Ensure the diagram can be followed top‑to‑bottom or left‑to‑right to reflect request flow.
By following these guidelines—identifying each core component, depicting its relationships, and using clear visual conventions—you will produce a system design diagram that accurately reflects the architecture of “Stupid Mails.”
</explanation>