How elliott-chong/normalhuman works
Project type and purpose
• This is a full-stack, serverless-friendly Next.js 14 application that serves as an AI-powered email client with subscription/payments.
• It combines a React/Tailwind frontend, Next.js App Router for routing and server-side logic, Prisma ORM for PostgreSQL persistence, Clerk for user auth, Stripe for payments, and various AI/external integrations (OpenAI, Pinecone, AWS SDK, “Aurinko,” etc.).
File structure
• Top-level: next.config.mjs, package.json, Prisma folder, public/static assets, src/
• src/app: Next.js App Router pages and serverless API route directories (e.g., /api/chat, /api/stripe/webhook).
• src/components & src/app/mail/components: shared UI and mail-specific UI.
• src/server & src/trpc: tRPC routers and server setup for type-safe RPC.
• src/lib: thin service wrappers for external APIs (OpenAI embeddings, Stripe actions, Nylas/Aurinko, AWS S3, etc.).
• Config files for Tailwind, ESLint, Prettier, Prisma schema, tsconfig, .env.example.
README
• Confirms full-stack Next.js setup, Prisma + PostgreSQL (Neon), Clerk auth, Stripe subscriptions, OpenAI + Pinecone for AI features.
• Deploys on Vercel; uses serverless functions for API and webhook handling.
Main components
a. Client (Browser / Next.js front end)
b. Next.js App Router & React components (UI, SSR/SSG pages)
c. Next.js API Routes & tRPC Server (serverless functions)
d. Business Logic / Service Layer (src/lib wrappers, src/server/routers)
e. Database (PostgreSQL via Prisma ORM)
f. External/Auth Services:
• Clerk (Auth)
• Stripe (Payments & Webhooks)
• OpenAI (Chat & embeddings)
• Pinecone (Vector DB)
• AWS S3 (Attachments/storage)
• Aurinko (calendar/email sync)
g. CI/CD / Hosting (Vercel serverless platform)
• Client → Next.js UI → Next.js server (SSR/data fetching)
• Client → API/tRPC endpoints → Business Logic
• Business Logic → Prisma → PostgreSQL
• Business Logic → External API wrappers (OpenAI, Pinecone, Stripe, Aurinko, AWS, Clerk)
• Webhook endpoints (Stripe, Clerk, Aurinko) → Next.js API → Business Logic → Database/Notifications
Architectural patterns & design principles
• Monorepo, file-based routing (Next.js App Router)
• Serverless functions for each API route/webhook
• Separation of concerns: UI components, service wrappers (src/lib), tRPC/REST API, persistence
• Type safety end-to-end: TypeScript + tRPC + Prisma
• Event-driven hooks (Stripe, Clerk, Aurinko) for async updates
Essential elements
• Data flows with arrowheads and labels