How harshul14/blackpearl works
Project Type and Purpose
• This is a full-stack, server-rendered React application built with Next.js (App Router)
• It uses tRPC for end-to-end typesafe APIs, NextAuth for authentication, Prisma/Drizzle for database access, and integrates with Stripe, GitHub, Firebase, and an AI service (“Gemini”).
• It provides user sign-up/sign-in, project creation/joining, billing, meeting management, Q&A, and code/commit insights.
a. Frontend (Next.js App)
– src/app: server and client React components, routing (public pages, protected pages under /(protected))
– src/components/ui: shared UI library (Tailwind-based)
– src/hooks & src/trpc/react.tsx: custom hooks, tRPC React client
b. Backend API Layer
– tRPC Server (src/server/api/root.ts, routers/*)
– Next.js API Routes
• /api/process-meeting (AI-driven meeting processing)
• /api/webhook/stripe (billing events)
• /api/trpc/[trpc]/route.ts (tRPC endpoint for App Router)
c. Database & ORM
– Prisma schema (prisma/schema.prisma) + Drizzle (if used)
– src/server/db.ts: DB client instantiation
d. Authentication & Session
– NextAuth in src/app/api/auth if present (or middleware.ts)
– Session storage in the database via Prisma adapter
e. External Services
– Stripe (billing webhooks, billing pages)
– GitHub (src/lib/github.ts, github-loader) for code references & commit logs
– Firebase (src/lib/firebase.ts) for any real-time features
– Gemini AI (src/lib/gemini.ts) for meeting summarization or Q&A
f. Utility Libraries
– src/lib/utils.ts, assembly.ts, etc.
g. DevOps / Deployment
– start-database.sh, Docker or Vercel/Netlify configs (next.config.js, env files)
• Client-side React → tRPC client (src/trpc/query-client.ts) → tRPC Server
• Server-side React (Next.js Server Components) → Direct DB reads via Prisma/Drizzle → Renders HTML
• Frontend forms → NextAuth (via middleware.ts) → Session cookie → Protected routes
• Billing page → Stripe Checkout → Stripe webhook → Next.js API → Update Billing record in DB
• “Process Meeting” action → Next.js API → Gemini AI → Persist results in DB → Rerender meeting page
• GitHub actions (commit-logs, code refs) → src/lib/github-loader → GitHub REST/GraphQL → Store/fetch metadata
• Firebase operations (if used) → Firestore/Realtime DB
Architectural Patterns & Principles
• Separation of concerns: UI, hooks, API, and database layers clearly separated in src/
• tRPC provides end-to-end typesafety—no REST controllers
• Next.js App Router for file-system routing & hybrid SSR/CSR
• Feature folders for each protected route (billing, dashboard, meetings)
• Middleware for auth gating at edge (middleware.ts)