# parhamash96/lecturelens architecture

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

- Interactive diagram: https://gitdiagram.com/parhamash96/lecturelens
- Repository: https://github.com/parhamash96/lecturelens

## Overview

LectureLens is a command-line lecture-to-Notion note-taking app. The user supplies course and lecture titles, records audio, and the main workflow uploads it, transcribes it, saves the transcript, generates and saves enhanced notes, publishes them to Notion, then removes local artifacts. The graph distinguishes orchestration from file persistence and external services. The README documents the stages; source excerpts show the calls and storage behavior. The GUI and CLI app files are empty or minimal in the supplied excerpts, so they are not treated as runtime entry points.

Main entry points: [`main.py`](https://github.com/parhamash96/lecturelens/blob/main/main.py) (Workflow runner), [`src/notetaker/core/cleaner/cleaner.py`](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/cleaner/cleaner.py) (Artifact cleaner), [`src/notetaker/core/google_storage/voice_saver.py`](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/google_storage/voice_saver.py) (Audio uploader), [`src/notetaker/core/speech_to_text/google_stt.py`](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/speech_to_text/google_stt.py) (Speech transcription)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow orchestration"]
  node_main["Workflow runner<br/>[main.py]"]
  node_cleaner["Artifact cleaner<br/>[cleaner.py]"]
end

subgraph group_capture["Audio and transcription"]
  node_recorder["Audio recorder<br/>[recorder.py]"]
  node_gcs_upload["Audio uploader<br/>[voice_saver.py]"]
  node_stt["Speech transcription<br/>[google_stt.py]"]
end

subgraph group_notes["Notes and publishing"]
  node_transcript_save["Transcript saver"]
  node_summariser["Note summariser<br/>[openai_o3.py]"]
  node_summary_save["Summary saver<br/>[summary_saver.py]"]
  node_publisher["Notion publisher"]
end

subgraph group_persistence["Local data"]
  node_audio_file["Recorded WAV"]
  node_transcript_file["Transcript JSON"]
  node_summary_file["Notes JSON"]
end

node_user(("Student"))
node_gcs[("Google Cloud Storage")]
node_speech_api["Google Speech-to-Text"]
node_openai["OpenAI API"]
node_notion[("Notion")]

node_user -->|"starts workflow"| node_main
node_main -->|"invokes"| node_recorder
node_main -->|"invokes"| node_gcs_upload
node_main -->|"invokes"| node_stt
node_main -->|"invokes"| node_transcript_save
node_main -->|"invokes"| node_summariser
node_main -->|"invokes"| node_summary_save
node_main -->|"invokes"| node_publisher
node_main -->|"invokes"| node_cleaner
node_recorder -->|"writes WAV"| node_audio_file
node_gcs_upload -->|"uploads audio"| node_audio_file
node_gcs_upload -->|"stores audio"| node_gcs
node_stt -->|"reads audio URI"| node_gcs
node_stt -->|"requests transcription"| node_speech_api
node_transcript_save -->|"writes transcript"| node_transcript_file
node_summariser -->|"reads transcript"| node_transcript_file
node_summariser -->|"requests notes"| node_openai
node_summary_save -->|"writes notes"| node_summary_file
node_publisher -->|"reads notes"| node_summary_file
node_publisher -->|"creates page"| node_notion
node_cleaner -->|"removes file"| node_audio_file
node_cleaner -->|"removes file"| node_transcript_file
node_cleaner -->|"removes file"| node_summary_file

click node_main "https://github.com/parhamash96/lecturelens/blob/main/main.py"
click node_recorder "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/audio_recorder/recorder.py"
click node_gcs_upload "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/google_storage/voice_saver.py"
click node_stt "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/speech_to_text/google_stt.py"
click node_transcript_save "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/transcript_saver/transcript_saver.py"
click node_summariser "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/summariser/openai_o3.py"
click node_summary_save "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/summary_saver/summary_saver.py"
click node_publisher "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/publisher/notion_publisher.py"
click node_cleaner "https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/cleaner/cleaner.py"
click node_audio_file "https://github.com/parhamash96/lecturelens/tree/main/src/notetaker/core/data"
click node_transcript_file "https://github.com/parhamash96/lecturelens/tree/main/src/notetaker/core/data"
click node_summary_file "https://github.com/parhamash96/lecturelens/tree/main/src/notetaker/core/data"

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_main,node_cleaner toneBlue
class node_recorder,node_gcs_upload,node_stt,node_gcs,node_notion toneAmber
class node_transcript_save,node_summariser,node_summary_save,node_publisher,node_openai toneMint
class node_audio_file,node_transcript_file,node_summary_file toneRose
class node_user,node_speech_api toneIndigo
```

## Components

### Workflow orchestration

- [Workflow runner](https://github.com/parhamash96/lecturelens/blob/main/main.py): `main.py`
- [Artifact cleaner](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/cleaner/cleaner.py): `src/notetaker/core/cleaner/cleaner.py`

### Audio and transcription

- [Audio recorder](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/audio_recorder/recorder.py): `src/notetaker/core/audio_recorder/recorder.py`
- [Audio uploader](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/google_storage/voice_saver.py): `src/notetaker/core/google_storage/voice_saver.py`
- [Speech transcription](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/speech_to_text/google_stt.py): `src/notetaker/core/speech_to_text/google_stt.py`

### Notes and publishing

- [Transcript saver](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/transcript_saver/transcript_saver.py): `src/notetaker/core/transcript_saver/transcript_saver.py`
- [Note summariser](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/summariser/openai_o3.py): `src/notetaker/core/summariser/openai_o3.py`
- [Summary saver](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/summary_saver/summary_saver.py): `src/notetaker/core/summary_saver/summary_saver.py`
- [Notion publisher](https://github.com/parhamash96/lecturelens/blob/main/src/notetaker/core/publisher/notion_publisher.py): `src/notetaker/core/publisher/notion_publisher.py`

### Local data

- [Recorded WAV](https://github.com/parhamash96/lecturelens/tree/main/src/notetaker/core/data): `src/notetaker/core/data`
- [Transcript JSON](https://github.com/parhamash96/lecturelens/tree/main/src/notetaker/core/data): `src/notetaker/core/data`
- [Notes JSON](https://github.com/parhamash96/lecturelens/tree/main/src/notetaker/core/data): `src/notetaker/core/data`

### Other components

- **Student**
- **Google Cloud Storage**
- **Google Speech-to-Text**
- **OpenAI API**
- **Notion**

## Connections

- Student → Workflow runner: starts workflow (evidence: `README.md`)
- Workflow runner → Audio recorder: invokes (evidence: `main.py`)
- Workflow runner → Audio uploader: invokes (evidence: `main.py`)
- Workflow runner → Speech transcription: invokes (evidence: `main.py`)
- Workflow runner → Transcript saver: invokes (evidence: `main.py`)
- Workflow runner → Note summariser: invokes (evidence: `main.py`)
- Workflow runner → Summary saver: invokes (evidence: `main.py`)
- Workflow runner → Notion publisher: invokes (evidence: `main.py`)
- Workflow runner → Artifact cleaner: invokes (evidence: `main.py`)
- Audio recorder → Recorded WAV: writes WAV (evidence: `src/notetaker/core/audio_recorder/recorder.py`)
- Audio uploader → Recorded WAV: uploads audio (evidence: `src/notetaker/core/google_storage/voice_saver.py`)
- Audio uploader → Google Cloud Storage: stores audio (evidence: `src/notetaker/core/google_storage/voice_saver.py`)
- Speech transcription → Google Cloud Storage: reads audio URI (evidence: `src/notetaker/core/speech_to_text/google_stt.py`)
- Speech transcription → Google Speech-to-Text: requests transcription (evidence: `src/notetaker/core/speech_to_text/google_stt.py`)
- Transcript saver → Transcript JSON: writes transcript (evidence: `src/notetaker/core/transcript_saver/transcript_saver.py`)
- Note summariser → Transcript JSON: reads transcript (evidence: `src/notetaker/core/summariser/openai_o3.py`)
- Note summariser → OpenAI API: requests notes (evidence: `src/notetaker/core/summariser/openai_o3.py`)
- Summary saver → Notes JSON: writes notes (evidence: `src/notetaker/core/summary_saver/summary_saver.py`)
- Notion publisher → Notes JSON: reads notes (evidence: `src/notetaker/core/publisher/notion_publisher.py`)
- Notion publisher → Notion: creates page (evidence: `src/notetaker/core/publisher/notion_publisher.py`)
- Artifact cleaner → Recorded WAV: removes file (evidence: `src/notetaker/core/cleaner/cleaner.py`)
- Artifact cleaner → Transcript JSON: removes file (evidence: `src/notetaker/core/cleaner/cleaner.py`)
- Artifact cleaner → Notes JSON: removes file (evidence: `src/notetaker/core/cleaner/cleaner.py`)
