# sayed-afnan-khazi/bookworm architecture

> Architecture diagram of the GitHub repository sayed-afnan-khazi/bookworm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sayed-afnan-khazi/bookworm
- Repository: https://github.com/sayed-afnan-khazi/bookworm

## Overview

Bookworm is a notebook-based PDF study app: users sign in, organize notebooks and chats, upload notes, and ask questions about them; the README highlights image-based PDF support. The frontend calls the Flask backend, which owns account/notebook/chat operations and delegates question answering to the Gemini wrapper. Separate backend modules provide MCQ generation and audio podcast generation. Sampled excerpts do not establish all route-to-page wiring or the full PDF-processing and persistence details, so uncertain links are omitted.

Main entry points: [`backend/app.py`](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py) (Flask API), [`frontend/src/App.js`](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/App.js) (App routing), [`backend/podcasts.py`](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/podcasts.py) (Podcast generation), [`frontend/src/hooks/Auth.js`](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/hooks/Auth.js) (Auth state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web app"]
  node_web_app["App routing<br/>[App.js]"]
  node_auth_ui["Auth state<br/>[Auth.js]"]
  node_notebooks_ui["Notebook management<br/>[Notebook.js]"]
  node_chat_ui["Chat interface<br/>[Chat.js]"]
  node_file_view["PDF viewer<br/>[FileCard.js]"]
  node_notebook_list["Notebook list<br/>[NotebooksList.js]"]
end

subgraph group_backend["Application backend"]
  node_flask_api["Flask API<br/>[app.py]"]
  node_question_answer["Question answering<br/>[gemini_wrap.py]"]
  node_user_store[("User records<br/>[app.py]")]
  node_notebook_store[("Notebook records<br/>[app.py]")]
  node_chat_store[("Chat records<br/>[app.py]")]
  node_pdf_collection[("PDF collection")]
end

subgraph group_ai_tools["Study generators"]
  node_mcq_generator["MCQ generation<br/>[mcq.py]"]
  node_podcast_generator["Podcast generation<br/>[podcasts.py]"]
  node_audio_merge["Audio merging<br/>[merge_audio.py]"]
  node_audio_files[("Generated audio")]
end

node_learner(("Learner"))
node_google_identity["Google identity"]
node_gemini_service["Gemini API"]

node_learner -->|"uses"| node_web_app
node_web_app -->|"provides auth"| node_auth_ui
node_web_app -->|"routes to"| node_notebook_list
node_web_app -->|"routes to"| node_notebooks_ui
node_web_app -->|"routes to"| node_chat_ui
node_auth_ui -->|"calls auth API"| node_flask_api
node_auth_ui -->|"verifies identity via"| node_google_identity
node_notebook_list -->|"requests notebooks"| node_flask_api
node_notebooks_ui -->|"manages notebook"| node_flask_api
node_notebooks_ui -->|"opens PDFs"| node_file_view
node_file_view -->|"fetches PDF data"| node_flask_api
node_chat_ui -->|"loads chat"| node_flask_api
node_chat_ui -->|"sends live messages"| node_flask_api
node_flask_api -->|"reads/writes"| node_user_store
node_flask_api -->|"reads/writes"| node_notebook_store
node_flask_api -->|"reads/writes"| node_chat_store
node_flask_api -->|"delegates questions"| node_question_answer
node_question_answer -->|"requests answers"| node_gemini_service
node_flask_api -->|"serves PDF files"| node_pdf_collection
node_mcq_generator -->|"generates questions"| node_gemini_service
node_podcast_generator -->|"generates transcript/audio"| node_gemini_service
node_podcast_generator -->|"merges tracks"| node_audio_merge
node_podcast_generator -->|"writes audio"| node_audio_files

click node_web_app "https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/App.js"
click node_auth_ui "https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/hooks/Auth.js"
click node_notebooks_ui "https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/pages/Notebook.js"
click node_chat_ui "https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/pages/Chat.js"
click node_file_view "https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/components/FileCard.js"
click node_notebook_list "https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/pages/NotebooksList.js"
click node_flask_api "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py"
click node_question_answer "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/gemini_wrap.py"
click node_user_store "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py"
click node_notebook_store "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py"
click node_chat_store "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py"
click node_pdf_collection "https://github.com/sayed-afnan-khazi/bookworm/tree/main/backend/pdfs"
click node_mcq_generator "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/mcq.py"
click node_podcast_generator "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/podcasts.py"
click node_audio_merge "https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/merge_audio.py"
click node_audio_files "https://github.com/sayed-afnan-khazi/bookworm/tree/main/backend/podcasts"

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_web_app,node_auth_ui,node_notebooks_ui,node_chat_ui,node_file_view,node_notebook_list toneBlue
class node_flask_api,node_question_answer,node_user_store,node_notebook_store,node_chat_store,node_pdf_collection toneAmber
class node_mcq_generator,node_podcast_generator,node_audio_merge,node_audio_files,node_gemini_service toneMint
class node_learner,node_google_identity toneIndigo
```

## Components

### Web app

- [App routing](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [Auth state](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/hooks/Auth.js): `frontend/src/hooks/Auth.js`
- [Notebook management](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/pages/Notebook.js): `frontend/src/pages/Notebook.js`
- [Chat interface](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/pages/Chat.js): `frontend/src/pages/Chat.js`
- [PDF viewer](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/components/FileCard.js): `frontend/src/components/FileCard.js`
- [Notebook list](https://github.com/sayed-afnan-khazi/bookworm/blob/main/frontend/src/pages/NotebooksList.js): `frontend/src/pages/NotebooksList.js`

### Application backend

- [Flask API](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py): `backend/app.py`
- [Question answering](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/gemini_wrap.py): `backend/gemini_wrap.py`
- [User records](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py): `backend/app.py`
- [Notebook records](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py): `backend/app.py`
- [Chat records](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/app.py): `backend/app.py`
- [PDF collection](https://github.com/sayed-afnan-khazi/bookworm/tree/main/backend/pdfs): `backend/pdfs`

### Study generators

- [MCQ generation](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/mcq.py): `backend/mcq.py`
- [Podcast generation](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/podcasts.py): `backend/podcasts.py`
- [Audio merging](https://github.com/sayed-afnan-khazi/bookworm/blob/main/backend/merge_audio.py): `backend/merge_audio.py`
- [Generated audio](https://github.com/sayed-afnan-khazi/bookworm/tree/main/backend/podcasts): `backend/podcasts`

### Other components

- **Learner**
- **Google identity**
- **Gemini API**

## Connections

- Learner → App routing: uses
- App routing → Auth state: provides auth
- App routing → Notebook list: routes to
- App routing → Notebook management: routes to
- App routing → Chat interface: routes to
- Auth state → Flask API: calls auth API
- Auth state → Google identity: verifies identity via
- Notebook list → Flask API: requests notebooks
- Notebook management → Flask API: manages notebook
- Notebook management → PDF viewer: opens PDFs
- PDF viewer → Flask API: fetches PDF data
- Chat interface → Flask API: loads chat
- Chat interface → Flask API: sends live messages
- Flask API → User records: reads/writes
- Flask API → Notebook records: reads/writes
- Flask API → Chat records: reads/writes
- Flask API → Question answering: delegates questions
- Question answering → Gemini API: requests answers
- Flask API → PDF collection: serves PDF files
- MCQ generation → Gemini API: generates questions
- Podcast generation → Gemini API: generates transcript/audio
- Podcast generation → Audio merging: merges tracks
- Podcast generation → Generated audio: writes audio