# gagancreates/notesai architecture

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

- Interactive diagram: https://gitdiagram.com/gagancreates/notesai
- Repository: https://github.com/gagancreates/notesai

## Overview

NotesAI turns lecture PDFs into structured study notes. A student uploads a PDF; the API stores its document and job records, then background processing extracts and chunks text, embeds it, and indexes it. The student can check progress and request note generation; the RAG engine retrieves chunks, creates section notes and a summary with Claude, and persists the result for retrieval and presentation. The README also describes quiz-oriented notes and polished typography. Frontend components and some service implementations were not excerpted, so their internal interactions are shown only where documented or indexed.

Main entry points: [`backend/app/services/processing_pipeline.py`](https://github.com/gagancreates/notesai/blob/main/backend/app/services/processing_pipeline.py) (PDF processing), [`backend/app/core/database.py`](https://github.com/gagancreates/notesai/blob/main/backend/app/core/database.py) (Database client), [`frontend/components/dashboard.tsx`](https://github.com/gagancreates/notesai/blob/main/frontend/components/dashboard.tsx) (Study dashboard), [`backend/app/main.py`](https://github.com/gagancreates/notesai/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Student interface"]
  node_webapp["Notes workspace<br/>[page.tsx]"]
  node_dashboard["Study dashboard<br/>[dashboard.tsx]"]
  node_sidebar["Note navigation<br/>[Sidebar.tsx]"]
  node_ui["UI primitives<br/>[ui.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API workflow"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_upload_route["PDF upload route<br/>[upload.py]"]
  node_status_route["Progress route<br/>[status.py]"]
  node_notes_route["Notes routes<br/>[notes.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_settings["Settings<br/>[config.py]"]
end

subgraph group_ingest["PDF ingestion"]
  node_pipeline["PDF processing"]
  node_pdf_extract["PDF extraction<br/>[pdf_processor.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_openai["OpenAI embeddings"]
end

subgraph group_generation["Note generation"]
  node_rag["RAG note engine<br/>[rag.py]"]
  node_claude["Claude generation<br/>[claude_client.py]"]
  node_anthropic["Anthropic Claude"]
end

subgraph group_storage["Persistence"]
  node_vector_client["Vector index client<br/>[pinecone_client.py]"]
  node_db_client["Database client<br/>[database.py]"]
  node_supabase[("Supabase records")]
  node_pinecone[("Pinecone vectors")]
end

node_student(("Student"))

node_student -->|"uses"| node_webapp
node_webapp -->|"renders"| node_dashboard
node_dashboard -->|"renders"| node_sidebar
node_dashboard -->|"uses"| node_ui
node_sidebar -->|"uses"| node_ui
node_dashboard -.->|"requests"| node_api_client
node_api_client -.->|"calls API"| node_api_app
node_api_app -->|"registers"| node_upload_route
node_api_app -->|"registers"| node_status_route
node_api_app -->|"registers"| node_notes_route
node_upload_route -->|"validates response"| node_schemas
node_status_route -->|"validates response"| node_schemas
node_notes_route -->|"validates response"| node_schemas
node_upload_route -->|"schedules"| node_pipeline
node_upload_route -->|"creates records"| node_db_client
node_pipeline -->|"extracts chunks"| node_pdf_extract
node_pipeline -->|"embeds chunks"| node_embeddings
node_pipeline -->|"upserts vectors"| node_vector_client
node_pipeline -->|"updates status"| node_db_client
node_embeddings -.->|"creates embeddings"| node_openai
node_vector_client -->|"stores vectors"| node_pinecone
node_status_route -->|"reads status"| node_db_client
node_notes_route -->|"reads and writes"| node_db_client
node_notes_route -->|"runs generation"| node_rag
node_rag -->|"retrieves chunks"| node_vector_client
node_rag -->|"generates sections"| node_claude
node_claude -.->|"requests completion"| node_anthropic
node_db_client -->|"accesses records"| node_supabase
node_settings -.->|"configures access"| node_supabase

click node_webapp "https://github.com/gagancreates/notesai/blob/main/frontend/app/page.tsx"
click node_dashboard "https://github.com/gagancreates/notesai/blob/main/frontend/components/dashboard.tsx"
click node_sidebar "https://github.com/gagancreates/notesai/blob/main/frontend/components/Sidebar.tsx"
click node_ui "https://github.com/gagancreates/notesai/blob/main/frontend/components/ui.tsx"
click node_api_client "https://github.com/gagancreates/notesai/blob/main/frontend/lib/api.ts"
click node_api_app "https://github.com/gagancreates/notesai/blob/main/backend/app/main.py"
click node_upload_route "https://github.com/gagancreates/notesai/blob/main/backend/app/api/routes/upload.py"
click node_status_route "https://github.com/gagancreates/notesai/blob/main/backend/app/api/routes/status.py"
click node_notes_route "https://github.com/gagancreates/notesai/blob/main/backend/app/api/routes/notes.py"
click node_schemas "https://github.com/gagancreates/notesai/blob/main/backend/app/models/schemas.py"
click node_pipeline "https://github.com/gagancreates/notesai/blob/main/backend/app/services/processing_pipeline.py"
click node_pdf_extract "https://github.com/gagancreates/notesai/blob/main/backend/app/services/pdf_processor.py"
click node_embeddings "https://github.com/gagancreates/notesai/blob/main/backend/app/services/embeddings.py"
click node_vector_client "https://github.com/gagancreates/notesai/blob/main/backend/app/services/pinecone_client.py"
click node_rag "https://github.com/gagancreates/notesai/blob/main/backend/app/core/rag.py"
click node_claude "https://github.com/gagancreates/notesai/blob/main/backend/app/services/claude_client.py"
click node_settings "https://github.com/gagancreates/notesai/blob/main/backend/app/core/config.py"
click node_db_client "https://github.com/gagancreates/notesai/blob/main/backend/app/core/database.py"

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_webapp,node_dashboard,node_sidebar,node_ui,node_api_client toneBlue
class node_api_app,node_upload_route,node_status_route,node_notes_route,node_schemas,node_settings toneAmber
class node_pipeline,node_pdf_extract,node_embeddings,node_openai toneMint
class node_rag,node_claude,node_anthropic toneRose
class node_vector_client,node_db_client,node_supabase,node_pinecone,node_student toneIndigo
```

## Components

### Student interface

- [Notes workspace](https://github.com/gagancreates/notesai/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Study dashboard](https://github.com/gagancreates/notesai/blob/main/frontend/components/dashboard.tsx): `frontend/components/dashboard.tsx`
- [Note navigation](https://github.com/gagancreates/notesai/blob/main/frontend/components/Sidebar.tsx): `frontend/components/Sidebar.tsx`
- [UI primitives](https://github.com/gagancreates/notesai/blob/main/frontend/components/ui.tsx): `frontend/components/ui.tsx`
- [API client](https://github.com/gagancreates/notesai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API workflow

- [FastAPI application](https://github.com/gagancreates/notesai/blob/main/backend/app/main.py): `backend/app/main.py`
- [PDF upload route](https://github.com/gagancreates/notesai/blob/main/backend/app/api/routes/upload.py): `backend/app/api/routes/upload.py`
- [Progress route](https://github.com/gagancreates/notesai/blob/main/backend/app/api/routes/status.py): `backend/app/api/routes/status.py`
- [Notes routes](https://github.com/gagancreates/notesai/blob/main/backend/app/api/routes/notes.py): `backend/app/api/routes/notes.py`
- [API schemas](https://github.com/gagancreates/notesai/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`
- [Settings](https://github.com/gagancreates/notesai/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### PDF ingestion

- [PDF processing](https://github.com/gagancreates/notesai/blob/main/backend/app/services/processing_pipeline.py): `backend/app/services/processing_pipeline.py`
- [PDF extraction](https://github.com/gagancreates/notesai/blob/main/backend/app/services/pdf_processor.py): `backend/app/services/pdf_processor.py`
- [Text embeddings](https://github.com/gagancreates/notesai/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`
- **OpenAI embeddings**

### Note generation

- [RAG note engine](https://github.com/gagancreates/notesai/blob/main/backend/app/core/rag.py): `backend/app/core/rag.py`
- [Claude generation](https://github.com/gagancreates/notesai/blob/main/backend/app/services/claude_client.py): `backend/app/services/claude_client.py`
- **Anthropic Claude**

### Persistence

- [Vector index client](https://github.com/gagancreates/notesai/blob/main/backend/app/services/pinecone_client.py): `backend/app/services/pinecone_client.py`
- [Database client](https://github.com/gagancreates/notesai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **Supabase records**
- **Pinecone vectors**

### Other components

- **Student**

## Connections

- Student → Notes workspace: uses (evidence: `README.md`)
- Notes workspace → Study dashboard: renders (evidence: `frontend/app/page.tsx`)
- Study dashboard → Note navigation: renders (evidence: `frontend/components/dashboard.tsx`)
- Study dashboard → UI primitives: uses (evidence: `frontend/components/dashboard.tsx`)
- Note navigation → UI primitives: uses (evidence: `frontend/components/Sidebar.tsx`)
- Study dashboard → API client: requests
- API client → FastAPI application: calls API
- FastAPI application → PDF upload route: registers (evidence: `backend/app/main.py`)
- FastAPI application → Progress route: registers (evidence: `backend/app/main.py`)
- FastAPI application → Notes routes: registers (evidence: `backend/app/main.py`)
- PDF upload route → API schemas: validates response (evidence: `backend/app/api/routes/upload.py`)
- Progress route → API schemas: validates response (evidence: `backend/app/api/routes/status.py`)
- Notes routes → API schemas: validates response (evidence: `backend/app/api/routes/notes.py`)
- PDF upload route → PDF processing: schedules (evidence: `backend/app/api/routes/upload.py`)
- PDF upload route → Database client: creates records (evidence: `backend/app/api/routes/upload.py`)
- PDF processing → PDF extraction: extracts chunks (evidence: `backend/app/services/processing_pipeline.py`)
- PDF processing → Text embeddings: embeds chunks (evidence: `backend/app/services/processing_pipeline.py`)
- PDF processing → Vector index client: upserts vectors (evidence: `backend/app/services/processing_pipeline.py`)
- PDF processing → Database client: updates status (evidence: `backend/app/services/processing_pipeline.py`)
- Text embeddings → OpenAI embeddings: creates embeddings (evidence: `README.md`)
- Vector index client → Pinecone vectors: stores vectors (evidence: `backend/app/services/pinecone_client.py`)
- Progress route → Database client: reads status (evidence: `backend/app/api/routes/status.py`)
- Notes routes → Database client: reads and writes (evidence: `backend/app/api/routes/notes.py`)
- Notes routes → RAG note engine: runs generation (evidence: `backend/app/api/routes/notes.py`)
- RAG note engine → Vector index client: retrieves chunks (evidence: `backend/app/core/rag.py`)
- RAG note engine → Claude generation: generates sections (evidence: `backend/app/core/rag.py`)
- Claude generation → Anthropic Claude: requests completion (evidence: `README.md`)
- Database client → Supabase records: accesses records (evidence: `backend/app/core/database.py`)
- Settings → Supabase records: configures access