# goswamiaditya112-cpu/studyrewinds architecture

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

- Interactive diagram: https://gitdiagram.com/goswamiaditya112-cpu/studyrewinds
- Repository: https://github.com/goswamiaditya112-cpu/studyrewinds

## Overview

StudyRewind turns a student’s YouTube lecture playlists and PDF notes into a searchable, cited knowledge base. Students use the React app to organize materials, authenticate, trigger ingestion, and search a subject; the FastAPI routes own those operations. YouTube transcripts and page-aware PDF chunks are embedded locally and stored alongside relational records in PostgreSQL/pgvector, then semantic search returns source timestamps or pages. The README documents capabilities beyond the sampled implementation excerpts; those branches are included where routing or README evidence supports them.

Main entry points: [`backend/app/main.py`](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/main.py) (API application), [`backend/app/services/vector_storage.py`](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/vector_storage.py) (Vector persistence), [`backend/app/api/documents.py`](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/documents.py) (PDF materials), [`backend/app/services/search.py`](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/search.py) (Semantic search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student workspace"]
  node_webapp["Study workspace<br/>[App.tsx]"]
end

subgraph group_api["API and access"]
  node_server["API application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_identity["Token identity<br/>[deps.py]"]
  node_security["JWT security<br/>[security.py]"]
  node_subjects["Subject workspaces<br/>[subjects.py]"]
end

subgraph group_ingestion["Material ingestion"]
  node_playlist_api["Playlist ingestion<br/>[playlists.py]"]
  node_youtube["YouTube catalog<br/>[youtube.py]"]
  node_transcript_api["Transcript processing<br/>[transcripts.py]"]
  node_transcript["Transcript extraction<br/>[transcript.py]"]
  node_documents["PDF materials<br/>[documents.py]"]
  node_pdf["PDF extraction<br/>[pdf.py]"]
end

subgraph group_search["Semantic retrieval"]
  node_search_api["Search endpoint<br/>[search.py]"]
  node_search_service["Semantic search<br/>[search.py]"]
  node_embedding["Local embeddings<br/>[embedding.py]"]
end

subgraph group_persistence["Relational vector store"]
  node_vector_storage["Vector persistence<br/>[vector_storage.py]"]
  node_database[("PostgreSQL pgvector<br/>[session.py]")]
  node_records["Study records<br/>[subject.py]"]
  node_chunks["Transcript and PDF chunks<br/>[chunk.py]"]
end

node_student(("Student"))

node_student -->|"uses"| node_webapp
node_webapp -->|"calls REST API"| node_server
node_server -->|"registers routes"| node_auth
node_server -->|"registers routes"| node_subjects
node_server -->|"registers routes"| node_playlist_api
node_server -->|"registers routes"| node_transcript_api
node_server -->|"registers routes"| node_documents
node_server -->|"registers routes"| node_search_api
node_auth -->|"uses tokens"| node_security
node_identity -->|"validates token"| node_security
node_identity -->|"loads user"| node_database
node_playlist_api -->|"loads playlist"| node_youtube
node_transcript_api -->|"extracts transcript"| node_transcript
node_documents -->|"extracts pages"| node_pdf
node_documents -->|"stores vectors"| node_vector_storage
node_transcript -->|"stores vectors"| node_vector_storage
node_vector_storage -->|"embeds chunks"| node_embedding
node_vector_storage -->|"persists vectors"| node_database
node_search_api -->|"runs search"| node_search_service
node_search_service -->|"embeds query"| node_embedding
node_search_service -->|"queries vectors"| node_vector_storage
node_search_service -->|"searches chunks"| node_chunks
node_subjects -->|"manages subjects"| node_records
node_playlist_api -->|"catalogs playlist"| node_records
node_transcript_api -->|"creates chunks"| node_chunks
node_documents -->|"creates chunks"| node_chunks

click node_webapp "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/frontend/src/App.tsx"
click node_server "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/main.py"
click node_auth "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/auth.py"
click node_identity "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/deps.py"
click node_security "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/core/security.py"
click node_subjects "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/subjects.py"
click node_playlist_api "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/playlists.py"
click node_youtube "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/youtube.py"
click node_transcript_api "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/transcripts.py"
click node_transcript "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/transcript.py"
click node_documents "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/documents.py"
click node_pdf "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/pdf.py"
click node_search_api "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/search.py"
click node_search_service "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/search.py"
click node_embedding "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/embedding.py"
click node_vector_storage "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/vector_storage.py"
click node_database "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/db/session.py"
click node_records "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/models/subject.py"
click node_chunks "https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/models/chunk.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 toneBlue
class node_server,node_auth,node_identity,node_security,node_subjects toneAmber
class node_playlist_api,node_youtube,node_transcript_api,node_transcript,node_documents,node_pdf toneMint
class node_search_api,node_search_service,node_embedding toneRose
class node_vector_storage,node_database,node_records,node_chunks,node_student toneIndigo
```

## Components

### Student workspace

- [Study workspace](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### API and access

- [API application](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Token identity](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [JWT security](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Subject workspaces](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/subjects.py): `backend/app/api/subjects.py`

### Material ingestion

- [Playlist ingestion](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/playlists.py): `backend/app/api/playlists.py`
- [YouTube catalog](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/youtube.py): `backend/app/services/youtube.py`
- [Transcript processing](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/transcripts.py): `backend/app/api/transcripts.py`
- [Transcript extraction](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/transcript.py): `backend/app/services/transcript.py`
- [PDF materials](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [PDF extraction](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/pdf.py): `backend/app/services/pdf.py`

### Semantic retrieval

- [Search endpoint](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/api/search.py): `backend/app/api/search.py`
- [Semantic search](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/search.py): `backend/app/services/search.py`
- [Local embeddings](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/embedding.py): `backend/app/services/embedding.py`

### Relational vector store

- [Vector persistence](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/services/vector_storage.py): `backend/app/services/vector_storage.py`
- [PostgreSQL pgvector](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Study records](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/models/subject.py): `backend/app/models/subject.py`
- [Transcript and PDF chunks](https://github.com/goswamiaditya112-cpu/studyrewinds/blob/main/backend/app/models/chunk.py): `backend/app/models/chunk.py`

### Other components

- **Student**

## Connections

- Student → Study workspace: uses
- Study workspace → API application: calls REST API
- API application → Authentication: registers routes (evidence: `backend/app/main.py`)
- API application → Subject workspaces: registers routes (evidence: `backend/app/main.py`)
- API application → Playlist ingestion: registers routes (evidence: `backend/app/main.py`)
- API application → Transcript processing: registers routes (evidence: `backend/app/main.py`)
- API application → PDF materials: registers routes (evidence: `backend/app/main.py`)
- API application → Search endpoint: registers routes (evidence: `backend/app/main.py`)
- Authentication → JWT security: uses tokens (evidence: `backend/app/api/auth.py`)
- Token identity → JWT security: validates token (evidence: `backend/app/api/deps.py`)
- Token identity → PostgreSQL pgvector: loads user (evidence: `backend/app/api/deps.py`)
- Playlist ingestion → YouTube catalog: loads playlist (evidence: `backend/app/api/playlists.py`)
- Transcript processing → Transcript extraction: extracts transcript (evidence: `backend/app/api/transcripts.py`)
- PDF materials → PDF extraction: extracts pages (evidence: `backend/app/api/documents.py`)
- PDF materials → Vector persistence: stores vectors (evidence: `backend/app/api/documents.py`)
- Transcript extraction → Vector persistence: stores vectors (evidence: `backend/app/services/transcript.py`)
- Vector persistence → Local embeddings: embeds chunks (evidence: `backend/app/services/vector_storage.py`)
- Vector persistence → PostgreSQL pgvector: persists vectors (evidence: `backend/app/services/vector_storage.py`)
- Search endpoint → Semantic search: runs search (evidence: `backend/app/api/search.py`)
- Semantic search → Local embeddings: embeds query (evidence: `backend/app/services/search.py`)
- Semantic search → Vector persistence: queries vectors (evidence: `backend/app/services/search.py`)
- Semantic search → Transcript and PDF chunks: searches chunks (evidence: `backend/app/services/search.py`)
- Subject workspaces → Study records: manages subjects (evidence: `backend/app/api/subjects.py`)
- Playlist ingestion → Study records: catalogs playlist (evidence: `backend/app/api/playlists.py`)
- Transcript processing → Transcript and PDF chunks: creates chunks (evidence: `backend/app/api/transcripts.py`)
- PDF materials → Transcript and PDF chunks: creates chunks (evidence: `backend/app/api/documents.py`)
