# pgramer1/hivenote architecture

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

- Interactive diagram: https://gitdiagram.com/pgramer1/hivenote
- Repository: https://github.com/pgramer1/hivenote

## Overview

#### Purpose and Entry Points
HiveNote is a Next.js App Router academic resource-sharing platform. Users browse scoped university content, upload resources, interact socially, and chat with PDF content. The application shell and public landing entry are `src/app/layout.tsx` and `src/app/page.tsx`; route pages under `src/app/resources`, `src/app/university`, `src/app/me`, and `src/app/admin` define primary user surfaces.

#### Application and Route Layer
Server-rendered App Router pages organize the main navigation: resource discovery/detail/upload at `src/app/resources/page.tsx`, `src/app/resources/[id]/page.tsx`, and `src/app/resources/upload/page.tsx`; hierarchical catalog browsing at `src/app/university/page.tsx` and `src/app/university/[department]/[batch]/[semester]/[subject]/page.tsx`. Shared providers are mounted through `src/app/providers.tsx`.

#### Identity, Sessions, and Access Control
NextAuth supports Google OAuth and credentials through `src/app/api/auth/[...nextauth]/route.ts`, with auth configuration in `src/lib/auth.ts`. Password and email-verification lifecycle endpoints live under `src/app/api/auth/*`. Authorization boundaries are centralized in `src/lib/permissions.ts`; admin routes (`src/app/admin/page.tsx`) manage academic taxonomy and require the ADMIN role.

#### Resource Lifecycle and Social Interactions
Resource creation and mutation are implemented as server actions, principally `src/actions/resources.ts`, while uploads are driven from `src/app/resources/upload/UploadForm.tsx`. Resources store metadata, classification, extracted content, and engagement state. Votes, favorites, comments, and views flow through `src/actions/vote.ts`, `src/actions/favorites.ts`, `src/actions/comments.ts`, and `src/actions/incrementView.ts`; detail-page client features render these interactions in `src/components/features/ResourcePageClient.tsx` and `src/components/features/ResourceDiscussion.tsx`.

#### Academic Taxonomy and Administration
Resources are classified along university → department → batch → semester → subject. The persistent model and relations are defined in `prisma/schema.prisma`. Administrative CRUD actions for these structural entities are separated into `src/actions/admin-departments.ts`, `src/actions/admin-batches.ts`, and `src/actions/admin-subjects.ts`, surfaced by corresponding routes under `src/app/admin/`.

#### AI Retrieval and PDF Chat
The PDF/chat boundary is the HTTP API at `src/app/api/chat/route.ts`, consumed by `src/components/features/ResourceChatBot.tsx`. Retrieval and generation orchestration reside in `src/lib/rag.ts`; embedding generation is isolated in `src/lib/embeddings.ts`. Schema migrations include RAG chunks, hybrid retrieval/citations, embeddings, and persisted chat history under `prisma/migrations/20260321000100_add_rag_pipeline` through `prisma/migrations/20260327154530_restore_hnsw_index`. Gemini and Groq are the model providers via Vercel AI SDK.

#### Persistence and External Infrastructure
Prisma (`src/lib/prisma.ts`) connects the Next.js server to PostgreSQL, intended for Neon; `prisma/schema.prisma` and `prisma/migrations/` are the schema source of truth. Cloudinary integration is contained in `src/lib/cloudinary.ts` for stored files. Brevo transactional mail is mediated by `src/lib/email.ts`. Deployment targets Vercel; runtime configuration is supplied through environment variables documented in `.env.example`.

Main entry points: [`src/lib/prisma.ts`](https://github.com/pgramer1/hivenote/blob/main/src/lib/prisma.ts) (Prisma data access), [`src/lib/rag.ts`](https://github.com/pgramer1/hivenote/blob/main/src/lib/rag.ts) (RAG orchestration), [`src/app/layout.tsx`](https://github.com/pgramer1/hivenote/blob/main/src/app/layout.tsx) (App shell), [`src/app/resources/page.tsx`](https://github.com/pgramer1/hivenote/blob/main/src/app/resources/page.tsx) (Resource routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js application"]
  node_shell["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_providers["Shared providers<br/>React providers<br/>[providers.tsx]"]
  node_resource_routes["Resource routes<br/>App Router pages<br/>[page.tsx]"]
  node_catalog_routes["University catalog<br/>App Router pages<br/>[page.tsx]"]
  node_upload_form["Upload form<br/>client feature<br/>[UploadForm.tsx]"]
  node_resource_actions["Resource actions<br/>server actions<br/>[resources.ts]"]
  node_social_actions["Social actions<br/>server actions<br/>[vote.ts]"]
  node_resource_client["Resource interactions<br/>client feature"]
end

subgraph group_identity["Identity and access"]
  node_admin_routes["Admin area<br/>App Router page<br/>[page.tsx]"]
  node_auth_api["NextAuth API<br/>auth route<br/>[route.ts]"]
  node_auth_config["Auth configuration<br/>auth service<br/>[auth.ts]"]
  node_permissions["Authorization rules<br/>access control<br/>[permissions.ts]"]
end

subgraph group_data["Data and taxonomy"]
  node_admin_actions["Taxonomy admin actions<br/>server actions"]
  node_prisma["Prisma data access<br/>ORM client<br/>[prisma.ts]"]
  node_schema["Academic and RAG schema<br/>Prisma schema<br/>[schema.prisma]"]
end

subgraph group_ai["PDF chat and retrieval"]
  node_chat_api["PDF chat API<br/>HTTP route<br/>[route.ts]"]
  node_chat_client["Resource chat UI<br/>client feature"]
  node_rag["RAG orchestration<br/>retrieval service<br/>[rag.ts]"]
  node_embeddings["Embedding generation<br/>AI service<br/>[embeddings.ts]"]
end

subgraph group_external["External services"]
  node_postgres[("PostgreSQL / Neon<br/>database")]
  node_models{{"Gemini and Groq<br/>model providers"}}
  node_cloudinary{{"Cloudinary<br/>file storage<br/>[cloudinary.ts]"}}
end

node_shell -->|"mounts"| node_providers
node_shell -->|"serves"| node_resource_routes
node_shell -->|"serves"| node_catalog_routes
node_providers -.->|"session access"| node_auth_api
node_resource_routes -->|"renders"| node_upload_form
node_upload_form -->|"submits"| node_resource_actions
node_resource_actions -->|"persists metadata"| node_prisma
node_resource_actions -->|"stores files"| node_cloudinary
node_resource_routes -->|"renders detail features"| node_resource_client
node_resource_client -->|"interacts"| node_social_actions
node_social_actions -->|"persists engagement"| node_prisma
node_catalog_routes -->|"queries scoped catalog"| node_prisma
node_admin_routes -->|"requires ADMIN"| node_permissions
node_admin_routes -->|"manages taxonomy"| node_admin_actions
node_admin_actions -->|"updates hierarchy"| node_prisma
node_auth_api -->|"uses"| node_auth_config
node_auth_config -->|"loads identities"| node_prisma
node_prisma -.->|"maps"| node_schema
node_prisma -->|"connects"| node_postgres
node_resource_client -->|"hosts"| node_chat_client
node_chat_client -->|"sends chat requests"| node_chat_api
node_chat_api -->|"orchestrates"| node_rag
node_rag -->|"embeds and retrieves"| node_embeddings
node_rag -->|"reads chunks and history"| node_prisma
node_rag -->|"generates answers"| node_models

click node_shell "https://github.com/pgramer1/hivenote/blob/main/src/app/layout.tsx"
click node_providers "https://github.com/pgramer1/hivenote/blob/main/src/app/providers.tsx"
click node_resource_routes "https://github.com/pgramer1/hivenote/blob/main/src/app/resources/page.tsx"
click node_catalog_routes "https://github.com/pgramer1/hivenote/blob/main/src/app/university/page.tsx"
click node_upload_form "https://github.com/pgramer1/hivenote/blob/main/src/app/resources/upload/UploadForm.tsx"
click node_resource_actions "https://github.com/pgramer1/hivenote/blob/main/src/actions/resources.ts"
click node_social_actions "https://github.com/pgramer1/hivenote/blob/main/src/actions/vote.ts"
click node_resource_client "https://github.com/pgramer1/hivenote/blob/main/src/components/features/ResourcePageClient.tsx"
click node_admin_routes "https://github.com/pgramer1/hivenote/blob/main/src/app/admin/page.tsx"
click node_auth_api "https://github.com/pgramer1/hivenote/blob/main/src/app/api/auth/%5B...nextauth%5D/route.ts"
click node_auth_config "https://github.com/pgramer1/hivenote/blob/main/src/lib/auth.ts"
click node_permissions "https://github.com/pgramer1/hivenote/blob/main/src/lib/permissions.ts"
click node_admin_actions "https://github.com/pgramer1/hivenote/blob/main/src/actions/admin-departments.ts"
click node_prisma "https://github.com/pgramer1/hivenote/blob/main/src/lib/prisma.ts"
click node_schema "https://github.com/pgramer1/hivenote/blob/main/prisma/schema.prisma"
click node_chat_api "https://github.com/pgramer1/hivenote/blob/main/src/app/api/chat/route.ts"
click node_chat_client "https://github.com/pgramer1/hivenote/blob/main/src/components/features/ResourceChatBot.tsx"
click node_rag "https://github.com/pgramer1/hivenote/blob/main/src/lib/rag.ts"
click node_embeddings "https://github.com/pgramer1/hivenote/blob/main/src/lib/embeddings.ts"
click node_cloudinary "https://github.com/pgramer1/hivenote/blob/main/src/lib/cloudinary.ts"

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_shell,node_providers,node_resource_routes,node_catalog_routes,node_upload_form,node_resource_actions,node_social_actions,node_resource_client toneBlue
class node_admin_routes,node_auth_api,node_auth_config,node_permissions toneAmber
class node_admin_actions,node_prisma,node_schema toneMint
class node_chat_api,node_chat_client,node_rag,node_embeddings toneRose
class node_postgres,node_models,node_cloudinary toneIndigo
```

## Components

### Next.js application

App Router pages, clients, and server actions.

- [App shell](https://github.com/pgramer1/hivenote/blob/main/src/app/layout.tsx): Next.js layout · `src/app/layout.tsx`
- [Shared providers](https://github.com/pgramer1/hivenote/blob/main/src/app/providers.tsx): React providers · `src/app/providers.tsx`
- [Resource routes](https://github.com/pgramer1/hivenote/blob/main/src/app/resources/page.tsx): App Router pages · Discovery, detail, and upload surfaces. · `src/app/resources/page.tsx`
- [University catalog](https://github.com/pgramer1/hivenote/blob/main/src/app/university/page.tsx): App Router pages · Scoped academic browsing hierarchy. · `src/app/university/page.tsx`
- [Upload form](https://github.com/pgramer1/hivenote/blob/main/src/app/resources/upload/UploadForm.tsx): client feature · `src/app/resources/upload/UploadForm.tsx`
- [Resource actions](https://github.com/pgramer1/hivenote/blob/main/src/actions/resources.ts): server actions · Creates and mutates resource records. · `src/actions/resources.ts`
- [Social actions](https://github.com/pgramer1/hivenote/blob/main/src/actions/vote.ts): server actions · Votes, favorites, comments, and views. · `src/actions/vote.ts`
- [Resource interactions](https://github.com/pgramer1/hivenote/blob/main/src/components/features/ResourcePageClient.tsx): client feature · `src/components/features/ResourcePageClient.tsx`

### Identity and access

- [Admin area](https://github.com/pgramer1/hivenote/blob/main/src/app/admin/page.tsx): App Router page · ADMIN-only taxonomy management. · `src/app/admin/page.tsx`
- [NextAuth API](https://github.com/pgramer1/hivenote/blob/main/src/app/api/auth/%5B...nextauth%5D/route.ts): auth route · Google OAuth and credentials entry point. · `src/app/api/auth/[...nextauth]/route.ts`
- [Auth configuration](https://github.com/pgramer1/hivenote/blob/main/src/lib/auth.ts): auth service · `src/lib/auth.ts`
- [Authorization rules](https://github.com/pgramer1/hivenote/blob/main/src/lib/permissions.ts): access control · `src/lib/permissions.ts`

### Data and taxonomy

- [Taxonomy admin actions](https://github.com/pgramer1/hivenote/blob/main/src/actions/admin-departments.ts): server actions · Department, batch, and subject CRUD. · `src/actions/admin-departments.ts`
- [Prisma data access](https://github.com/pgramer1/hivenote/blob/main/src/lib/prisma.ts): ORM client · `src/lib/prisma.ts`
- [Academic and RAG schema](https://github.com/pgramer1/hivenote/blob/main/prisma/schema.prisma): Prisma schema · Resources, taxonomy, social state, chunks, and chat history. · `prisma/schema.prisma`

### PDF chat and retrieval

- [PDF chat API](https://github.com/pgramer1/hivenote/blob/main/src/app/api/chat/route.ts): HTTP route · `src/app/api/chat/route.ts`
- [Resource chat UI](https://github.com/pgramer1/hivenote/blob/main/src/components/features/ResourceChatBot.tsx): client feature · `src/components/features/ResourceChatBot.tsx`
- [RAG orchestration](https://github.com/pgramer1/hivenote/blob/main/src/lib/rag.ts): retrieval service · Hybrid retrieval, citations, generation, and chat history. · `src/lib/rag.ts`
- [Embedding generation](https://github.com/pgramer1/hivenote/blob/main/src/lib/embeddings.ts): AI service · `src/lib/embeddings.ts`

### External services

- **PostgreSQL / Neon**: database
- **Gemini and Groq**: model providers · Accessed through Vercel AI SDK.
- [Cloudinary](https://github.com/pgramer1/hivenote/blob/main/src/lib/cloudinary.ts): file storage · `src/lib/cloudinary.ts`

## Connections

- App shell → Shared providers: mounts
- App shell → Resource routes: serves
- App shell → University catalog: serves
- Shared providers → NextAuth API: session access
- Resource routes → Upload form: renders
- Upload form → Resource actions: submits
- Resource actions → Prisma data access: persists metadata
- Resource actions → Cloudinary: stores files
- Resource routes → Resource interactions: renders detail features
- Resource interactions → Social actions: interacts
- Social actions → Prisma data access: persists engagement
- University catalog → Prisma data access: queries scoped catalog
- Admin area → Authorization rules: requires ADMIN
- Admin area → Taxonomy admin actions: manages taxonomy
- Taxonomy admin actions → Prisma data access: updates hierarchy
- NextAuth API → Auth configuration: uses
- Auth configuration → Prisma data access: loads identities
- Prisma data access → Academic and RAG schema: maps
- Prisma data access → PostgreSQL / Neon: connects
- Resource interactions → Resource chat UI: hosts
- Resource chat UI → PDF chat API: sends chat requests
- PDF chat API → RAG orchestration: orchestrates
- RAG orchestration → Embedding generation: embeds and retrieves
- RAG orchestration → Prisma data access: reads chunks and history
- RAG orchestration → Gemini and Groq: generates answers