# wolframresearch/chatbook architecture

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

- Interactive diagram: https://gitdiagram.com/wolframresearch/chatbook
- Repository: https://github.com/wolframresearch/chatbook

## Overview

##### Project Type and Purpose
- It is neither a standalone web app nor a microservice-based system; it is a full-featured plugin composed of:
- Kernel code (Wolfram Language packages under `Source/Chatbook`)
- Build and packaging scripts (under `Scripts/` and `Developer/`)
- Configuration assets (LLM personas, vector databases, user snippets)

##### File Structure
- Top-level directories reveal architectural layers:
- FrontEnd: notebook stylesheets, text resources, system bitmaps—wired into Mathematica’s front end
- Source/Chatbook: core Wolfram Language code—business logic for chat sessions, prompt generation, request handling, state management, UI glue
- LLMConfiguration: predefined persona configurations for different chat modes
- VectorDatabases: builders and source data for embedding-based context retrieval
- Scripts: build pipelines (vector DB, paclet packaging, stylesheet building) and CI hooks
- Tests: automated notebooks and script tests verifying functionality
- Configuration files (`PacletInfo.wl`, `.github/workflows/*.yml`, `.gitignore`) define packaging and CI.

##### README for Additional Insights
- Chatbook is installed as a paclet; users enable the `Chatbook` stylesheet to get new cell styles.
- Users must supply an OpenAI API key (`SystemCredential["OPENAI_API_KEY"]`).
- The README highlights chat interaction, code generation, and in-place evaluation—key use cases the architecture must support.

##### Detail Without Overthinking
- Break the WD packages (`Source/Chatbook/*.wl`) into logical groups: State, UI, Services, PromptGenerators, Tools.
- Configuration directories (`LLMConfiguration`, `VectorDatabases`) as input to the kernel at startup.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User
    User["User"]:::external

    %% FrontEnd Integration
    subgraph "FrontEnd Integration"
        FE["Chatbook FrontEnd Extension"]:::internal
        Assets["Assets (stylesheets, icons, menus)"]:::internal
        Dark["DarkModeSupport"]:::internal
        FERes["FrontEndResources"]:::internal
    end

    %% Kernel Logic
    subgraph "Kernel Logic"
        Core["Core Logic (Source/Chatbook)"]:::internal
        State["ChatState.wl"]:::internal
        Prompts["PromptGenerators"]:::internal
        Services["Services.wl"]:::internal
        UIFe["FrontEnd.wl"]:::internal
        Handlers["Handlers.wl"]:::internal
        ToolMgr["ToolManager.wl"]:::internal
        ToolsDir["Tools"]:::internal
    end

    %% Configuration & Data
    subgraph "Configuration & Data"
        Personas["LLM Personas"]:::datastore
        VectorDB["VectorDatabases"]:::datastore
        VDBBuilder["VectorDatabaseBuilder.wl"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI Chat API"]:::external
        WolframAlpha["WolframAlpha API"]:::external
    end

    %% Build & CI
    subgraph "Build & CI"
        BuildPaclet["BuildPaclet.wls"]:::tooling
        BuildStyles["BuildStylesheet.wls"]:::tooling
        BuildVDB["BuildVectorDatabases.wls"]:::tooling
        FEBuilder["FrontEndResourceBuilder.wl"]:::tooling
        CI1["Build.yml"]:::tooling
        CI2["Release.yml"]:::tooling
        CI3["IncrementPacletVersion.yml"]:::tooling
        CI4["ExperimentalRelease.yml"]:::tooling
        Tests["Tests"]:::tooling
    end

    %% Connections
    User -->|"interacts with"| FE
    FE -->|"triggers event"| Core
    Core --> State
    Core --> Prompts
    Core --> Services
    Core --> UIFe
    Core --> Handlers
    Core --> ToolMgr
    ToolMgr --> ToolsDir
    Core -->|"uses config"| Personas
    Core -->|"uses config"| VectorDB
    VectorDB --> VDBBuilder
    Core -->|"calls"| OpenAI
    Core -->|"calls"| WolframAlpha
    OpenAI --> Core
    WolframAlpha --> Core
    BuildPaclet --> Core
    BuildStyles --> FE
    BuildVDB --> VectorDB
    FEBuilder --> Assets
    Tests --> Core
    CI1 --> BuildPaclet
    CI2 --> BuildPaclet
    CI3 --> BuildPaclet
    CI4 --> BuildPaclet

    %% Click Events
    click FE "https://github.com/wolframresearch/chatbook/tree/main/FrontEnd/"
    click Assets "https://github.com/wolframresearch/chatbook/tree/main/Assets/"
    click Dark "https://github.com/wolframresearch/chatbook/tree/main/DarkModeSupport/"
    click FERes "https://github.com/wolframresearch/chatbook/tree/main/Developer/Resources/FrontEndResources/"
    click Core "https://github.com/wolframresearch/chatbook/tree/main/Source/Chatbook/"
    click State "https://github.com/wolframresearch/chatbook/blob/main/Source/Chatbook/ChatState.wl"
    click Prompts "https://github.com/wolframresearch/chatbook/tree/main/Source/Chatbook/PromptGenerators/"
    click Services "https://github.com/wolframresearch/chatbook/blob/main/Source/Chatbook/Services.wl"
    click UIFe "https://github.com/wolframresearch/chatbook/blob/main/Source/Chatbook/FrontEnd.wl"
    click Handlers "https://github.com/wolframresearch/chatbook/blob/main/Source/Chatbook/Handlers.wl"
    click ToolMgr "https://github.com/wolframresearch/chatbook/blob/main/Source/Chatbook/ToolManager.wl"
    click ToolsDir "https://github.com/wolframresearch/chatbook/tree/main/Source/Chatbook/Tools/"
    click Personas "https://github.com/wolframresearch/chatbook/tree/main/LLMConfiguration/Personas/"
    click VectorDB "https://github.com/wolframresearch/chatbook/tree/main/VectorDatabases/"
    click VDBBuilder "https://github.com/wolframresearch/chatbook/blob/main/Developer/VectorDatabases/VectorDatabaseBuilder.wl"
    click BuildPaclet "https://github.com/wolframresearch/chatbook/blob/main/Scripts/BuildPaclet.wls"
    click BuildStyles "https://github.com/wolframresearch/chatbook/blob/main/Scripts/BuildStylesheet.wls"
    click BuildVDB "https://github.com/wolframresearch/chatbook/blob/main/Scripts/BuildVectorDatabases.wls"
    click FEBuilder "https://github.com/wolframresearch/chatbook/blob/main/Developer/FrontEndResourceBuilder.wl"
    click CI1 "https://github.com/wolframresearch/chatbook/blob/main/.github/workflows/Build.yml"
    click CI2 "https://github.com/wolframresearch/chatbook/blob/main/.github/workflows/Release.yml"
    click CI3 "https://github.com/wolframresearch/chatbook/blob/main/.github/workflows/IncrementPacletVersion.yml"
    click CI4 "https://github.com/wolframresearch/chatbook/blob/main/.github/workflows/ExperimentalRelease.yml"
    click Tests "https://github.com/wolframresearch/chatbook/tree/main/Tests/"

    %% Styles
    classDef internal fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef external fill:#bbdefb,stroke:#1565c0,color:#0d47a1
    classDef tooling fill:#fff9c4,stroke:#f9a825,color:#f57f17
    classDef datastore fill:#ffe0b2,stroke:#ef6c00,color:#e65100
```
