# klindikaraj/studyscribe architecture

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

- Interactive diagram: https://gitdiagram.com/klindikaraj/studyscribe
- Repository: https://github.com/klindikaraj/studyscribe

## Overview

StudyScribe is a Windows, local-first course-lecture recorder and transcription CLI. Users create a session by recording system loopback audio into durable WAV segments, then transcribe that session locally; runs can resume and transcripts can be exported. Recovery repairs abandoned recordings. The README describes study-note generation and a web UI as planned, not implemented, so they are not shown as runtime components. Relationships reflect the README and source-index references; unsampled modules are represented only where their role is documented or indexed.

Main entry points: [`src/studyscribe/cli.py`](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/cli.py) (Command-line interface), [`src/studyscribe/db/repo.py`](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/db/repo.py) (Session and transcript queries), [`src/studyscribe/audio/capture.py`](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/capture.py) (Loopback capture), [`src/studyscribe/transcribe/pipeline.py`](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/pipeline.py) (Windowed transcription pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Session workflow"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_session["Session lifecycle<br/>[session.py]"]
  node_recording["Recorder process handle<br/>[recording.py]"]
  node_recovery["Crash recovery<br/>[recovery.py]"]
  node_export["Transcript export<br/>[export.py]"]
end

subgraph group_audio["Audio capture"]
  node_capture["Loopback capture<br/>[capture.py]"]
  node_devices["Output device tracking<br/>[devices.py]"]
  node_timeline["Audio timeline alignment<br/>[timeline.py]"]
  node_dsp["Audio signal processing<br/>[dsp.py]"]
  node_segments["Segment writer<br/>[segments.py]"]
  node_wav["Crash-tolerant WAV files<br/>[wav.py]"]
end

subgraph group_transcription["Transcription"]
  node_audio_reader["Session audio reader<br/>[reader.py]"]
  node_runner["Transcription run manager<br/>[runner.py]"]
  node_pipeline["Windowed transcription pipeline<br/>[pipeline.py]"]
  node_language["Language detection<br/>[language.py]"]
  node_filters["Transcript filtering<br/>[filters.py]"]
  node_vad["Voice activity detection<br/>[vad.py]"]
  node_whisper["Faster Whisper engine<br/>[whisper.py]"]
end

subgraph group_storage["Persistence"]
  node_db[("SQLite session database<br/>[connection.py]")]
  node_repo["Session and transcript queries<br/>[repo.py]"]
  node_config["Paths and settings<br/>[config.py]"]
end

node_user(("Course learner"))
node_audio_output(("Windows audio output"))
node_local_model[("Local speech model")]

node_user -->|"runs commands"| node_cli
node_cli -->|"creates sessions"| node_session
node_cli -->|"starts recording"| node_recording
node_recording -->|"spawns process"| node_capture
node_capture -->|"captures loopback"| node_audio_output
node_capture -->|"tracks output"| node_devices
node_capture -->|"aligns packets"| node_timeline
node_timeline -->|"processes audio"| node_dsp
node_capture -->|"writes samples"| node_segments
node_segments -->|"writes segments"| node_wav
node_session -->|"creates session rows"| node_repo
node_session -->|"registers closed segments"| node_segments
node_cli -->|"repairs sessions"| node_recovery
node_recovery -->|"repairs WAV headers"| node_wav
node_recovery -->|"repairs manifest"| node_repo
node_cli -->|"starts transcription"| node_runner
node_runner -->|"loads session audio"| node_audio_reader
node_audio_reader -->|"reads segment manifest"| node_repo
node_runner -->|"transcribes windows"| node_pipeline
node_pipeline -->|"detects language"| node_language
node_pipeline -->|"filters segments"| node_filters
node_pipeline -->|"finds speech pauses"| node_vad
node_pipeline -->|"requests recognition"| node_whisper
node_whisper -->|"runs local model"| node_local_model
node_runner -->|"stores run results"| node_repo
node_cli -->|"exports transcript"| node_export
node_export -->|"reads transcript data"| node_repo
node_cli -->|"lists session status"| node_repo
node_db -->|"provides connection"| node_repo
node_session -->|"opens connection"| node_db
node_config -->|"sets database path"| node_db
node_config -->|"sets audio paths"| node_audio_reader

click node_cli "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/cli.py"
click node_session "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/session.py"
click node_recording "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/recording.py"
click node_recovery "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/recovery.py"
click node_export "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/export.py"
click node_capture "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/capture.py"
click node_devices "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/devices.py"
click node_timeline "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/timeline.py"
click node_dsp "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/dsp.py"
click node_segments "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/segments.py"
click node_wav "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/wav.py"
click node_audio_reader "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/reader.py"
click node_runner "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/runner.py"
click node_pipeline "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/pipeline.py"
click node_language "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/language.py"
click node_filters "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/filters.py"
click node_vad "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/vad.py"
click node_whisper "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/whisper.py"
click node_db "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/db/connection.py"
click node_repo "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/db/repo.py"
click node_config "https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/config.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_cli,node_session,node_recording,node_recovery,node_export toneBlue
class node_capture,node_devices,node_timeline,node_dsp,node_segments,node_wav,node_local_model toneAmber
class node_audio_reader,node_runner,node_pipeline,node_language,node_filters,node_vad,node_whisper toneMint
class node_db,node_repo,node_config toneRose
class node_user,node_audio_output toneIndigo
```

## Components

### Session workflow

- [Command-line interface](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/cli.py): `src/studyscribe/cli.py`
- [Session lifecycle](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/session.py): `src/studyscribe/session.py`
- [Recorder process handle](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/recording.py): `src/studyscribe/recording.py`
- [Crash recovery](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/recovery.py): `src/studyscribe/recovery.py`
- [Transcript export](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/export.py): `src/studyscribe/transcribe/export.py`

### Audio capture

- [Loopback capture](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/capture.py): `src/studyscribe/audio/capture.py`
- [Output device tracking](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/devices.py): `src/studyscribe/audio/devices.py`
- [Audio timeline alignment](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/timeline.py): `src/studyscribe/audio/timeline.py`
- [Audio signal processing](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/dsp.py): `src/studyscribe/audio/dsp.py`
- [Segment writer](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/segments.py): `src/studyscribe/audio/segments.py`
- [Crash-tolerant WAV files](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/wav.py): `src/studyscribe/audio/wav.py`

### Transcription

- [Session audio reader](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/audio/reader.py): `src/studyscribe/audio/reader.py`
- [Transcription run manager](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/runner.py): `src/studyscribe/transcribe/runner.py`
- [Windowed transcription pipeline](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/pipeline.py): `src/studyscribe/transcribe/pipeline.py`
- [Language detection](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/language.py): `src/studyscribe/transcribe/language.py`
- [Transcript filtering](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/filters.py): `src/studyscribe/transcribe/filters.py`
- [Voice activity detection](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/vad.py): `src/studyscribe/transcribe/vad.py`
- [Faster Whisper engine](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/transcribe/whisper.py): `src/studyscribe/transcribe/whisper.py`

### Persistence

- [SQLite session database](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/db/connection.py): `src/studyscribe/db/connection.py`
- [Session and transcript queries](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/db/repo.py): `src/studyscribe/db/repo.py`
- [Paths and settings](https://github.com/klindikaraj/studyscribe/blob/main/src/studyscribe/config.py): `src/studyscribe/config.py`

### Other components

- **Course learner**
- **Windows audio output**
- **Local speech model**

## Connections

- Course learner → Command-line interface: runs commands (evidence: `README.md`)
- Command-line interface → Session lifecycle: creates sessions (evidence: `src/studyscribe/cli.py`)
- Command-line interface → Recorder process handle: starts recording (evidence: `src/studyscribe/cli.py`)
- Recorder process handle → Loopback capture: spawns process (evidence: `src/studyscribe/recording.py`)
- Loopback capture → Windows audio output: captures loopback (evidence: `README.md`)
- Loopback capture → Output device tracking: tracks output (evidence: `src/studyscribe/audio/capture.py`)
- Loopback capture → Audio timeline alignment: aligns packets (evidence: `src/studyscribe/audio/capture.py`)
- Audio timeline alignment → Audio signal processing: processes audio (evidence: `src/studyscribe/audio/timeline.py`)
- Loopback capture → Segment writer: writes samples (evidence: `src/studyscribe/audio/capture.py`)
- Segment writer → Crash-tolerant WAV files: writes segments (evidence: `src/studyscribe/audio/segments.py`)
- Session lifecycle → Session and transcript queries: creates session rows (evidence: `src/studyscribe/session.py`)
- Session lifecycle → Segment writer: registers closed segments (evidence: `src/studyscribe/session.py`)
- Command-line interface → Crash recovery: repairs sessions (evidence: `src/studyscribe/cli.py`)
- Crash recovery → Crash-tolerant WAV files: repairs WAV headers (evidence: `src/studyscribe/recovery.py`)
- Crash recovery → Session and transcript queries: repairs manifest (evidence: `src/studyscribe/recovery.py`)
- Command-line interface → Transcription run manager: starts transcription (evidence: `src/studyscribe/cli.py`)
- Transcription run manager → Session audio reader: loads session audio (evidence: `src/studyscribe/transcribe/runner.py`)
- Session audio reader → Session and transcript queries: reads segment manifest (evidence: `src/studyscribe/audio/reader.py`)
- Transcription run manager → Windowed transcription pipeline: transcribes windows (evidence: `src/studyscribe/transcribe/runner.py`)
- Windowed transcription pipeline → Language detection: detects language (evidence: `src/studyscribe/transcribe/pipeline.py`)
- Windowed transcription pipeline → Transcript filtering: filters segments (evidence: `src/studyscribe/transcribe/pipeline.py`)
- Windowed transcription pipeline → Voice activity detection: finds speech pauses (evidence: `src/studyscribe/transcribe/pipeline.py`)
- Windowed transcription pipeline → Faster Whisper engine: requests recognition (evidence: `src/studyscribe/transcribe/pipeline.py`)
- Faster Whisper engine → Local speech model: runs local model (evidence: `README.md`)
- Transcription run manager → Session and transcript queries: stores run results (evidence: `src/studyscribe/transcribe/runner.py`)
- Command-line interface → Transcript export: exports transcript (evidence: `src/studyscribe/cli.py`)
- Transcript export → Session and transcript queries: reads transcript data (evidence: `src/studyscribe/transcribe/export.py`)
- Command-line interface → Session and transcript queries: lists session status (evidence: `src/studyscribe/cli.py`)
- SQLite session database → Session and transcript queries: provides connection (evidence: `src/studyscribe/db/connection.py`)
- Session lifecycle → SQLite session database: opens connection (evidence: `src/studyscribe/session.py`)
- Paths and settings → SQLite session database: sets database path (evidence: `src/studyscribe/config.py`)
- Paths and settings → Session audio reader: sets audio paths (evidence: `src/studyscribe/audio/reader.py`)