# elliott-chong/normalhuman architecture

> Architecture diagram of the GitHub repository elliott-chong/normalhuman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elliott-chong/normalhuman
- Repository: https://github.com/elliott-chong/normalhuman

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Frontend Layer
  subgraph "Frontend / Client" 
    direction TB
    Browser["Client Browser"]:::frontend
    AppRouter["Next.js App Router & React UI"]:::frontend
    UIComponents["UI Component Library"]:::frontend
  end

  %% API / Serverless Layer
  subgraph "API / Serverless Functions"
    direction TB
    APIRoutes["Next.js API Routes"]:::api
    TRPCServer["tRPC Server & Routes"]:::api
  end

  %% Business Logic Layer
  subgraph "Business Logic / Service Layer"
    direction TB
    ServiceWrappers["Service Wrappers (src/lib)"]:::service
  end

  %% Database Layer
  subgraph "Database / ORM"
    direction TB
    PrismaClient["Prisma ORM / PostgreSQL"]:::db
    DBClient["Database Client"]:::db
  end

  %% External Services
  subgraph "External / Auth / Integrations"
    direction TB
    Clerk["Clerk (Auth)"]:::external
    Stripe["Stripe (Payments)"]:::external
    OpenAI["OpenAI"]:::external
    Pinecone["Pinecone / Vector DB"]:::external
    AWS["AWS S3"]:::external
    Aurinko["Aurinko (Email Sync)"]:::external
  end

  %% CI/CD / Hosting
  Vercel["Vercel (Hosting & CI/CD)"]:::external

  %% Relationships
  Browser -->|"renders UI"| AppRouter
  AppRouter -->|"uses components"| UIComponents
  AppRouter -->|"SSR / Data Fetch"| APIRoutes
  Browser -->|"calls RPC"| TRPCServer

  APIRoutes -->|"calls business logic"| ServiceWrappers
  TRPCServer -->|"calls business logic"| ServiceWrappers

  ServiceWrappers -->|"Prisma queries"| PrismaClient
  ServiceWrappers -->|"DB client"| DBClient

  ServiceWrappers -->|"Auth calls"| Clerk
  ServiceWrappers -->|"Create Payment Intent"| Stripe
  ServiceWrappers -->|"Fetch embeddings"| OpenAI
  ServiceWrappers -->|"Store vectors"| Pinecone
  ServiceWrappers -->|"Upload attachments"| AWS
  ServiceWrappers -->|"Sync email/calendar"| Aurinko

  %% Webhooks (dashed)
  Stripe -.->|"webhook event"| APIRoutes
  Clerk -.->|"webhook event"| APIRoutes
  Aurinko -.->|"webhook event"| APIRoutes

  %% Hosting
  APIRoutes -->|"deployed as serverless"| Vercel
  TRPCServer -->|"deployed as serverless"| Vercel
  AppRouter -->|"deployed as serverless"| Vercel

  %% Click Events
  click Browser "https://github.com/elliott-chong/normalhuman/tree/main/src/app"
  click UIComponents "https://github.com/elliott-chong/normalhuman/tree/main/src/components/ui"
  click AppRouter "https://github.com/elliott-chong/normalhuman/blob/main/src/app/page.tsx"
  click APIRoutes "https://github.com/elliott-chong/normalhuman/tree/main/src/app/api"
  click TRPCServer "https://github.com/elliott-chong/normalhuman/blob/main/src/app/api/trpc/[trpc]/route.ts"
  click ServiceWrappers "https://github.com/elliott-chong/normalhuman/tree/main/src/lib"
  click PrismaClient "https://github.com/elliott-chong/normalhuman/blob/main/prisma/schema.prisma"
  click DBClient "https://github.com/elliott-chong/normalhuman/blob/main/src/server/db.ts"

  %% Styles
  classDef frontend fill:#E0F2FE,stroke:#0284C7,color:#0369A1
  classDef api fill:#ECFDF5,stroke:#10B981,color:#065F46
  classDef service fill:#FEF3C7,stroke:#FBBF24,color:#92400E
  classDef db fill:#FFF7ED,stroke:#F97316,color:#C2410C
  classDef external fill:#F3F4F6,stroke:#9CA3AF,color:#4B5563
```
