# harshul14/blackpearl architecture

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

- Interactive diagram: https://gitdiagram.com/harshul14/blackpearl
- Repository: https://github.com/harshul14/blackpearl

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Browser (Client)"
    React["Next.js App (src/app)"]:::frontend
    UI["Shared UI Library (src/components/ui)"]:::frontend
    Hooks["Custom Hooks (src/hooks)"]:::frontend
    TRPCReact["tRPC React Client (src/trpc/react.tsx)"]:::frontend
    QueryClient["tRPC Query Client (src/trpc/query-client.ts)"]:::frontend
  end

  subgraph "Next.js Server"
    Middleware["Auth Middleware (src/middleware.ts)"]:::server
    TRPCServer["tRPC Server Setup (src/trpc/server.ts)"]:::server
    TRPCRoot["tRPC Root API (src/server/api/root.ts)"]:::server
    Routers["tRPC Routers (src/server/api/routers)"]:::server
    API_Process["Process Meeting API (src/app/api/process-meeting/route.ts)"]:::server
    API_Stripe["Stripe Webhook API (src/app/api/webhook/stripe/route.ts)"]:::server
    API_tRPCRoute["tRPC Endpoint (src/app/api/trpc/[trpc]/route.ts)"]:::server
  end

  subgraph "Data Layer"
    DBSchema["Prisma Schema (prisma/schema.prisma)"]:::db
    DBClient["Database Client (src/server/db.ts)"]:::db
  end

  subgraph "External Services"
    Stripe["Stripe"]:::external
    GitHubAPI["GitHub API"]:::external
    Firebase["Firebase"]:::external
    Gemini["Gemini AI"]:::external
  end

  %% Client flows
  React -->|uses| UI
  React -->|uses| Hooks
  React -->|uses| TRPCReact
  React -->|uses| QueryClient
  TRPCReact -->|calls| API_tRPCRoute
  QueryClient -->|calls| API_tRPCRoute

  %% API routing
  API_tRPCRoute -->|routes to| TRPCServer
  TRPCServer -->|imports| TRPCRoot
  TRPCRoot -->|includes| Routers
  Routers -->|queries| DBClient
  DBClient -->|defined by| DBSchema

  React -->|SSR data fetch| DBClient

  %% Billing flow
  React -->|POST /api/webhook/stripe| API_Stripe
  API_Stripe -->|updates| DBClient
  API_Stripe -->|notifies| Stripe

  %% Meeting processing
  React -->|POST /api/process-meeting| API_Process
  API_Process -->|invokes| Gemini
  Gemini -->|returns results| API_Process
  API_Process -->|writes| DBClient

  %% GitHub integration
  TRPCRoot -->|calls| GitHubAPI
  GitHubAPI -->|returns metadata| Routers

  %% Auth middleware
  React -->|edge auth| Middleware
  Middleware -->|protects| API_tRPCRoute

  classDef frontend fill:#ADD8E6,stroke:#000,color:#000;
  classDef server fill:#90EE90,stroke:#000,color:#000;
  classDef db fill:#FFA500,stroke:#000,color:#000;
  classDef external fill:#DDA0DD,stroke:#000,color:#000;

  %% Click events
  click React "https://github.com/harshul14/blackpearl/tree/master/src/app"
  click UI "https://github.com/harshul14/blackpearl/tree/master/src/components/ui"
  click Hooks "https://github.com/harshul14/blackpearl/tree/master/src/hooks"
  click TRPCReact "https://github.com/harshul14/blackpearl/blob/master/src/trpc/react.tsx"
  click QueryClient "https://github.com/harshul14/blackpearl/blob/master/src/trpc/query-client.ts"
  click Middleware "https://github.com/harshul14/blackpearl/blob/master/src/middleware.ts"
  click TRPCServer "https://github.com/harshul14/blackpearl/blob/master/src/trpc/server.ts"
  click TRPCRoot "https://github.com/harshul14/blackpearl/blob/master/src/server/api/root.ts"
  click Routers "https://github.com/harshul14/blackpearl/tree/master/src/server/api/routers"
  click API_Process "https://github.com/harshul14/blackpearl/blob/master/src/app/api/process-meeting/route.ts"
  click API_Stripe "https://github.com/harshul14/blackpearl/blob/master/src/app/api/webhook/stripe/route.ts"
  click API_tRPCRoute "https://github.com/harshul14/blackpearl/blob/master/src/app/api/trpc/[trpc]/route.ts"
  click DBSchema "https://github.com/harshul14/blackpearl/blob/master/prisma/schema.prisma"
  click DBClient "https://github.com/harshul14/blackpearl/blob/master/src/server/db.ts"
```
