# dhakarraghu/gitbuddy architecture

> Architecture diagram of the GitHub repository dhakarraghu/gitbuddy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhakarraghu/gitbuddy
- Repository: https://github.com/dhakarraghu/gitbuddy

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with a clear split between public entry points and a protected workspace.
   - The public side contains the home page and login flow; the authenticated side is organized around a project workspace and project-management actions.

2. **Authentication and access control**
   - Authentication is handled through **NextAuth** in `src/app/api/auth/[...nextauth]/route.ts`.
   - `src/middleware.ts` and the `(protected)` route group enforce access boundaries so workspace pages only load for signed-in users.
   - `src/lib/auth.ts` is the central auth config/helper, and `src/components/Providers.tsx` likely wires session/theme/global client providers into the app shell.

3. **Persistent application state**
   - The app uses **Prisma** with a relational database, as shown by `src/lib/db.ts` and `prisma/schema.prisma`.
   - Migrations indicate the main stored entities include **users, projects, and repository indexing data**, plus at least one enum-based state model.
   - This database is the system of record for project membership, saved summaries, analytics, and meeting artifacts.

4. **Project-centric domain model**
   - The main workspace is organized around `src/app/project/[projectId]`, which is the primary domain boundary.
   - Subpages under a project include:
     - **dashboard** for overview/status
     - **analytics** for repository and activity insights
     - **meetings** for meeting lists and meeting detail
     - **prAndissue** for pull request / issue analysis
     - **qa** for question-answering over project context
   - `src/app/project/[projectId]/layout.tsx` suggests shared project-scoped navigation/state across these tabs.

5. **Project lifecycle and collaboration**
   - Project creation and membership are handled in the protected workspace via `create`, `join/[projectId]`, and `projects`.
   - Collaboration features are surfaced through components such as `invite-button.tsx`, `team-member.tsx`, and `archive-button.tsx`.
   - The `billing` page implies account or workspace-level plan management, even if it is not the core product flow.

6. **Repository ingestion and analysis pipeline**
   - Repository analysis appears to start from GitHub data and repo loading helpers in `src/lib/github.ts`, `src/lib/githubLoader.ts`, `src/lib/github-insights.ts`, and `src/lib/repoEmbedding.ts`.
   - `src/lib/query.ts` and `src/lib/retrival.ts` suggest a retrieval layer that turns indexed repository content into answerable context.
   - The architecture implies a pipeline of: **user supplies repo URL → repo is fetched/indexed → embeddings are generated → data is stored for search/QA/analytics**.

7. **Vector retrieval and AI assistant layer**
   - `src/lib/pineconedb.ts` indicates a **Pinecone**-backed vector store for semantic retrieval.
   - `src/lib/gemini.ts` and `src/lib/gemini2.ts` indicate **Gemini** is used for generation tasks such as summaries, explanations, and project Q&A.
   - This creates a retrieval-augmented workflow: the app fetches relevant project/repo context from Pinecone and passes it to the model for grounded responses.

8. **Meeting audio processing**
   - Meeting support is a separate ingestion path from repository analysis.
   - `src/components/upload-audio.tsx` and `src/lib/assembly.ts` indicate audio upload plus **AssemblyAI** transcription.
   - `src/lib/uploadToVercel.ts` suggests uploaded media is stored externally, likely via Vercel storage/asset handling, before transcription and summarization.
   - The resulting transcript, summary, and extracted issues feed the meetings pages and likely the project analytics layer.

9. **UI composition and state handling**
   - The UI is built from a shared design system in `src/components/ui/*`, with app-specific shell pieces like `app-sidebar.tsx`, `homeSidebar.tsx`, `mode-toggle.tsx`, and `ConfromDialog.tsx`.
   - Multiple `loading.tsx` files under project subroutes show that the workspace is designed around asynchronous data loading and progressive rendering.
   - Hooks such as `use-refetch.ts` and `use-mobile.ts` suggest client-side refresh and responsive behavior are part of the interaction model.

10. **Data flow across the system**
   - The two main ingestion streams are:
     - **GitHub repository data** flowing into database + embeddings + AI summaries
     - **Meeting audio** flowing into storage + transcription + extracted action items/issues
   - Both streams converge in the project workspace, where the UI reads persisted records and generated insights to render dashboards, analytics, Q&A, and meeting views.

11. **External service boundaries**
   - The architecture depends on several external services that materially shape the system:
     - **GitHub** for repository source data
     - **Gemini** for language generation and analysis
     - **AssemblyAI** for audio transcription
     - **Pinecone** for vector search / semantic retrieval
     - **Vercel** for deployment and likely file/storage handling
   - These are not just integrations; they define the major processing boundaries of the product.

12. **What to draw in an architecture diagram**
   - A useful diagram should center on the **project workspace** as the hub, with arrows to:
     - auth/middleware and session management
     - Prisma/Postgres persistence
     - GitHub ingestion/indexing
     - Pinecone retrieval
     - Gemini generation
     - AssemblyAI meeting transcription
     - external media upload/storage
   - The public login and protected project routes should be shown as separate entry paths into the same core workspace.

Main entry points: [`rampage/src/app/project/[projectId]/layout.tsx`](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/layout.tsx) (Project Hub), [`rampage/src/lib/githubLoader.ts`](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/lib/githubLoader.ts) (Repo Pipeline), [`rampage/src/components/upload-audio.tsx`](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/components/upload-audio.tsx) (Meeting Pipeline), [`rampage/src/app/(protected)/layout.tsx`](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/layout.tsx) (Protected Area)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Public entry"]
  node_n1["Home<br/>app route<br/>[page.tsx]"]
  node_n2["Login<br/>app route<br/>[page.tsx]"]
  node_n3["Auth API<br/>nextauth route<br/>[route.ts]"]
  node_n4["Middleware<br/>route guard<br/>[middleware.ts]"]
end

subgraph group_g2["Protected workspace"]
  node_n7["Protected Area<br/>workspace shell<br/>[layout.tsx]"]
  node_n8["Projects<br/>workspace route<br/>[page.tsx]"]
  node_n9["Create / Join<br/>workspace flows<br/>[page.tsx]"]
  node_n10["Billing<br/>workspace route<br/>[page.tsx]"]
end

subgraph group_g3["Project hub"]
  node_n11["Project Hub<br/>project shell<br/>[layout.tsx]"]
  node_n12["Dashboard<br/>project page<br/>[page.tsx]"]
  node_n13["Analytics<br/>project page<br/>[page.tsx]"]
  node_n14["Meetings<br/>project page<br/>[page.tsx]"]
  node_n15["PR / Issues<br/>project page<br/>[page.tsx]"]
  node_n16["Q&A<br/>project page<br/>[page.tsx]"]
end

subgraph group_g4["Ingestion and AI"]
  node_n17{{"Repo Pipeline<br/>ingestion pipeline<br/>[githubLoader.ts]"}}
  node_n18{{"Meeting Pipeline<br/>audio pipeline<br/>[upload-audio.tsx]"}}
end

subgraph group_g5["Persistence"]
  node_n19[("Prisma DB<br/>relational store<br/>[schema.prisma]")]
  node_n20[("Vector Store<br/>pinecone store<br/>[pineconedb.ts]")]
end

subgraph group_g6["External services"]
  node_n21(("GitHub<br/>external source"))
  node_n22(("Gemini<br/>llm service"))
  node_n23(("AssemblyAI<br/>transcription service"))
  node_n24(("Vercel Storage<br/>file storage<br/>[uploadToVercel.ts]"))
end

subgraph group_g7["Shared UI"]
  node_n5["App Shell<br/>root layout<br/>[layout.tsx]"]
  node_n6["Providers<br/>[Providers.tsx]"]
  node_n25["UI System<br/>shared components<br/>[button.tsx]"]
end

node_n1 -->|"renders via"| node_n5
node_n2 -->|"authenticates with"| node_n3
node_n4 -->|"guards"| node_n7
node_n5 -->|"provides"| node_n6
node_n7 -->|"shows"| node_n8
node_n7 -->|"offers"| node_n9
node_n7 -->|"includes"| node_n10
node_n8 -->|"opens"| node_n11
node_n11 -->|"navigates"| node_n12
node_n11 -->|"navigates"| node_n13
node_n11 -->|"navigates"| node_n14
node_n11 -->|"navigates"| node_n15
node_n11 -->|"navigates"| node_n16
node_n17 -->|"loads from"| node_n21
node_n17 -->|"persists to"| node_n19
node_n17 -->|"indexes in"| node_n20
node_n17 -->|"summarizes with"| node_n22
node_n18 -->|"uploads to"| node_n24
node_n18 -->|"transcribes with"| node_n23
node_n18 -->|"summarizes with"| node_n22
node_n12 -->|"reads"| node_n19
node_n13 -->|"queries"| node_n17
node_n14 -->|"shows"| node_n18
node_n15 -->|"analyzes"| node_n17
node_n16 -->|"retrieves from"| node_n17
node_n16 -->|"searches"| node_n20
node_n15 -->|"explains with"| node_n22
node_n14 -->|"stores"| node_n19
node_n18 -->|"stores"| node_n19
node_n25 -->|"supports"| node_n11
node_n25 -->|"supports"| node_n7

click node_n1 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/page.tsx"
click node_n2 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/login/page.tsx"
click node_n3 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/api/auth/[...nextauth]/route.ts"
click node_n4 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/middleware.ts"
click node_n5 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/layout.tsx"
click node_n6 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/components/Providers.tsx"
click node_n7 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/layout.tsx"
click node_n8 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/projects/page.tsx"
click node_n9 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/create/page.tsx"
click node_n10 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/billing/page.tsx"
click node_n11 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/layout.tsx"
click node_n12 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/dashboard/page.tsx"
click node_n13 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/analytics/page.tsx"
click node_n14 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/meetings/page.tsx"
click node_n15 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/prAndissue/page.tsx"
click node_n16 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/qa/page.tsx"
click node_n17 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/lib/githubLoader.ts"
click node_n18 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/components/upload-audio.tsx"
click node_n19 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/prisma/schema.prisma"
click node_n20 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/lib/pineconedb.ts"
click node_n24 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/lib/uploadToVercel.ts"
click node_n25 "https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/components/ui/button.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4,node_n5,node_n6,node_n25 toneBlue
class node_n7,node_n8,node_n9,node_n10 toneAmber
class node_n11,node_n12,node_n13,node_n14,node_n15,node_n16 toneMint
class node_n17,node_n18 toneRose
class node_n19,node_n20 toneIndigo
class node_n21,node_n22,node_n23,node_n24 toneTeal
```

## Components

### Public entry

Unauthenticated routes and login entry points.

- [Home](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/page.tsx): app route · Public landing page. · `rampage/src/app/page.tsx`
- [Login](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/login/page.tsx): app route · Sign-in entry page. · `rampage/src/app/login/page.tsx`
- [Auth API](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/api/auth/[...nextauth]/route.ts): nextauth route · NextAuth handler and session flow. · `rampage/src/app/api/auth/[...nextauth]/route.ts`
- [Middleware](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/middleware.ts): route guard · Protects signed-in areas and enforces access boundaries. · `rampage/src/middleware.ts`

### Protected workspace

Signed-in app shell and project management area.

- [Protected Area](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/layout.tsx): workspace shell · Authenticated route group and workspace entry. · `rampage/src/app/(protected)/layout.tsx`
- [Projects](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/projects/page.tsx): workspace route · Project list and workspace overview. · `rampage/src/app/(protected)/projects/page.tsx`
- [Create / Join](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/create/page.tsx): workspace flows · Project creation and membership entry points. · `rampage/src/app/(protected)/create/page.tsx`
- [Billing](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/(protected)/billing/page.tsx): workspace route · Plan or account management surface. · `rampage/src/app/(protected)/billing/page.tsx`

### Project hub

Project-scoped routes and shared navigation.

- [Project Hub](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/layout.tsx): project shell · Shared project-scoped layout and navigation. · `rampage/src/app/project/[projectId]/layout.tsx`
- [Dashboard](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/dashboard/page.tsx): project page · Project overview and status. · `rampage/src/app/project/[projectId]/dashboard/page.tsx`
- [Analytics](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/analytics/page.tsx): project page · Repository and activity insights. · `rampage/src/app/project/[projectId]/analytics/page.tsx`
- [Meetings](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/meetings/page.tsx): project page · Meeting list and detail views. · `rampage/src/app/project/[projectId]/meetings/page.tsx`
- [PR / Issues](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/prAndissue/page.tsx): project page · Pull request and issue analysis. · `rampage/src/app/project/[projectId]/prAndissue/page.tsx`
- [Q&A](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/project/[projectId]/qa/page.tsx): project page · Question answering over project context. · `rampage/src/app/project/[projectId]/qa/page.tsx`

### Ingestion and AI

Repository, retrieval, and meeting processing pipeline.

- [Repo Pipeline](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/lib/githubLoader.ts): ingestion pipeline · GitHub loading, indexing, embeddings, and retrieval prep. · `rampage/src/lib/githubLoader.ts`
- [Meeting Pipeline](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/components/upload-audio.tsx): audio pipeline · Upload, transcription, and meeting summary processing. · `rampage/src/components/upload-audio.tsx`

### Persistence

Database and vector storage backends.

- [Prisma DB](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/prisma/schema.prisma): relational store · Primary application database and schema. · `rampage/prisma/schema.prisma`
- [Vector Store](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/lib/pineconedb.ts): pinecone store · Semantic retrieval index for repository context. · `rampage/src/lib/pineconedb.ts`

### External services

Third-party systems the app depends on.

- **GitHub**: external source · Repository source data provider.
- **Gemini**: llm service · Generation and explanation model layer.
- **AssemblyAI**: transcription service · Audio transcription service.
- [Vercel Storage](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/lib/uploadToVercel.ts): file storage · External media upload and storage boundary. · `rampage/src/lib/uploadToVercel.ts`

### Shared UI

Cross-cutting UI components and client helpers.

- [App Shell](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/app/layout.tsx): root layout · Global app layout and provider wiring. · `rampage/src/app/layout.tsx`
- [Providers](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/components/Providers.tsx): client providers · Session, theme, and shared client context setup. · `rampage/src/components/Providers.tsx`
- [UI System](https://github.com/dhakarraghu/gitbuddy/blob/main/rampage/src/components/ui/button.tsx): shared components · Reusable design system and app-specific chrome. · `rampage/src/components/ui/button.tsx`

## Connections

- Home → App Shell: renders via · Public shell renders inside the global app layout.
- Login → Auth API: authenticates with · Login flow delegates to NextAuth.
- Middleware → Protected Area: guards · Middleware protects authenticated routes.
- App Shell → Providers: provides · Root layout wires shared providers.
- Protected Area → Projects: shows · Protected workspace exposes project list.
- Protected Area → Create / Join: offers · Workspace contains create and join flows.
- Protected Area → Billing: includes · Workspace includes billing settings.
- Projects → Project Hub: opens · Projects lead into a project-scoped hub.
- Project Hub → Dashboard: navigates · Shared project layout frames the dashboard.
- Project Hub → Analytics: navigates · Shared project layout frames analytics.
- Project Hub → Meetings: navigates · Shared project layout frames meetings.
- Project Hub → PR / Issues: navigates · Shared project layout frames PR and issue analysis.
- Project Hub → Q&A: navigates · Shared project layout frames Q&A.
- Repo Pipeline → GitHub: loads from · Repository pipeline starts with GitHub data.
- Repo Pipeline → Prisma DB: persists to · Indexed project data is stored in the relational database.
- Repo Pipeline → Vector Store: indexes in · Embeddings and retrieval state are stored in vector search.
- Repo Pipeline → Gemini: summarizes with · Gemini supports repo analysis and answer generation.
- Meeting Pipeline → Vercel Storage: uploads to · Meeting media is stored before processing.
- Meeting Pipeline → AssemblyAI: transcribes with · Audio is sent to AssemblyAI for transcription.
- Meeting Pipeline → Gemini: summarizes with · Transcript artifacts feed AI-generated summaries.
- Dashboard → Prisma DB: reads · Dashboard reads persisted project state.
- Analytics → Repo Pipeline: queries · Analytics depends on repo ingestion and retrieval.
- Meetings → Meeting Pipeline: shows · Meeting pages surface audio-derived artifacts.
- PR / Issues → Repo Pipeline: analyzes · PR and issue views use repository indexing data.
- Q&A → Repo Pipeline: retrieves from · Q&A uses retrieval over indexed project context.
- Q&A → Vector Store: searches · Semantic retrieval comes from the vector store.
- PR / Issues → Gemini: explains with · LLM generates issue and PR insights.
- Meetings → Prisma DB: stores · Meeting records and summaries persist in the database.
- Meeting Pipeline → Prisma DB: stores · Transcripts and outputs are saved in the system of record.
- UI System → Project Hub: supports · Shared UI components are used throughout the project shell.
- UI System → Protected Area: supports · Design system components power the protected workspace.