# pleaseprompto/notebooklm-skill architecture

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

- Interactive diagram: https://gitdiagram.com/pleaseprompto/notebooklm-skill
- Repository: https://github.com/pleaseprompto/notebooklm-skill

## Overview

##### Project type and purpose
- This is an open-source “Claude Code Skill” plugin written in Python.
- Purpose: let Claude Code (local CLI AI agent) query Google NotebookLM via browser automation (Patchright/Playwright) for source-grounded answers based on user-uploaded docs.

##### File structure
- Top level:
- SKILL.md – Claude’s instructions/manifest for the skill
- scripts/ – all Python automation modules
- requirements.txt – Python dependencies (patchright, python-dotenv)
- AUTHENTICATION.md, SKILL.md, references/ – docs
- data/ (created at runtime) – stores library.json, auth_info.json, browser_state/
- scripts directory:
- run.py – entry point invoked by Claude Code
- auth_manager.py – handles one-time Google login via Chrome
- notebook_manager.py – manages “library” of NotebookLM links and metadata
- ask_question.py – sends queries to NotebookLM, extracts answer+citation
- cleanup_manager.py – clears cookies/local state when needed
- setup_environment.py – bootstraps .venv, installs Chrome, dependencies
- browser_session.py – low-level browser launch and context management

##### README for architecture insights
- The “Architecture” section already outlines a 3-piece flow:
1. Claude loads the skill → 2. Python script runs → 3. Browser automation interacts with NotebookLM → returns answers
- Data storage is local and stateless per question (fresh browser session per query), but the library persists.

##### Elements
– Blue for user-facing components (Claude Code CLI, SKILL.md)
– Green for local code (scripts folder, .venv)
– Orange for external dependencies (Chrome, NotebookLM service)
– Gray for data storage (library.json, auth_info.json)
- Notation for “stateless session” on the browser component and “persistent storage” on data store component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and CLI
    User["User"]:::userFacing
    ClaudeCLI["Claude Code CLI"]:::userFacing
    User -->|"invokes skill"| ClaudeCLI

    %% Skill Loader
    SkillLoader["Skill Loader\n(SKILL.md)"]:::userFacing
    ClaudeCLI -->|"reads manifest\nand calls run.py"| SkillLoader
    click SkillLoader "https://github.com/pleaseprompto/notebooklm-skill/blob/master/SKILL.md"

    %% Python Environment
    subgraph "Python Environment" 
        direction TB
        Venv["Virtual Environment\n(.venv + requirements.txt)"]:::localCode
        SetupEnv["Environment Setup\n(scripts/setup_environment.py)"]:::localCode
        Venv --> SetupEnv
        click SetupEnv "https://github.com/pleaseprompto/notebooklm-skill/blob/master/scripts/setup_environment.py"
        click Venv "https://github.com/pleaseprompto/notebooklm-skill/blob/master/requirements.txt"
    end
    SkillLoader -->|"bootstraps env"| Venv

    %% Scripts
    subgraph "Skill Scripts" 
        direction TB
        EntryPoint["Entry Point\n(scripts/run.py)"]:::localCode
        AuthManager["Authentication Manager\n(scripts/auth_manager.py)"]:::localCode
        QuestionHandler["Question Handling\n(scripts/ask_question.py)"]:::localCode
        LibraryManager["Library Management\n(scripts/notebook_manager.py)"]:::localCode
        CleanupManager["Cleanup Manager\n(scripts/cleanup_manager.py)"]:::localCode
        BrowserSession["Browser Automation Layer\n(scripts/browser_session.py)"]:::localCode

        EntryPoint --> AuthManager
        EntryPoint --> QuestionHandler
        EntryPoint --> LibraryManager
        EntryPoint --> CleanupManager
        AuthManager --> BrowserSession
        QuestionHandler --> BrowserSession
        BrowserSession --> CleanupManager
        click EntryPoint "https://github.com/pleaseprompto/notebooklm-skill/blob/master/scripts/run.py"
        click AuthManager "https://github.com/pleaseprompto/notebooklm-skill/blob/master/scripts/auth_manager.py"
        click QuestionHandler "https://github.com/pleaseprompto/notebooklm-skill/blob/master/scripts/ask_question.py"
        click LibraryManager "https://github.com/pleaseprompto/notebooklm-skill/blob/master/scripts/notebook_manager.py"
        click CleanupManager "https://github.com/pleaseprompto/notebooklm-skill/blob/master/scripts/cleanup_manager.py"
        click BrowserSession "https://github.com/pleaseprompto/notebooklm-skill/blob/master/scripts/browser_session.py"
    end
    Venv --> EntryPoint

    %% External Services
    subgraph "External Services"
        direction TB
        Chrome["Chrome Browser"]:::external
        NotebookLM["NotebookLM Service"]:::external
    end
    BrowserSession -->|"launches browser"| Chrome
    BrowserSession -->|"navigates to NotebookLM"| NotebookLM
    NotebookLM -->|"returns HTML response"| BrowserSession

    %% Data Storage
    subgraph "Local Data Store"
        direction TB
        LibraryJSON["library.json"]:::data
        AuthInfo["auth_info.json"]:::data
    end
    LibraryManager -->|"reads/writes metadata"| LibraryJSON
    AuthManager -->|"stores credentials"| AuthInfo

    %% Return flow
    BrowserSession -->|"parsed answer + citations"| QuestionHandler
    QuestionHandler -->|"JSON answer"| ClaudeCLI

    %% Documentation
    subgraph "Documentation"
        README["README.md"]:::userFacing
        AuthDoc["AUTHENTICATION.md"]:::userFacing
        References["references/"]:::userFacing
        click README "https://github.com/pleaseprompto/notebooklm-skill/blob/master/README.md"
        click AuthDoc "https://github.com/pleaseprompto/notebooklm-skill/blob/master/AUTHENTICATION.md"
        click References "https://github.com/pleaseprompto/notebooklm-skill/tree/master/references/"
    end

    %% Styles
    classDef userFacing fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef localCode fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#000,stroke-width:1px
```
