# cpbotha/obsidian-ai-chat-as-md architecture

> Architecture diagram of the GitHub repository cpbotha/obsidian-ai-chat-as-md, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cpbotha/obsidian-ai-chat-as-md
- Repository: https://github.com/cpbotha/obsidian-ai-chat-as-md

## Overview

##### Main Components
- Obsidian Editor Environment: This is the host application where the plugin is installed, and where users interact with their Markdown notes.
- Plugin Core (main.ts): This module acts as the central entry point. It registers commands and communicates with the Obsidian API.
- Command & UI Handlers: These components capture user events (e.g., invoking “Send current thread to AI”) from the Obsidian command palette.
- Markdown Parsing & Conversation Engine: This module scans the note content for nested headings, extracts conversation threads, and organizes them in a structured format.
- AI Integration Module: This part of the system constructs requests (possibly using configuration from the plugin settings or YAML frontmatter overrides), calls the specified AI API endpoint, and processes the responses.
- Configuration & System Prompt Management: Using configuration defined in the plugin settings (and optionally in the Markdown frontmatter), this component determines which API host, key, and model to use, as well as handling system prompts or user-defined prompt files.
- Build & Development Infrastructure: Although not part of runtime, files like esbuild.config.mjs, tsconfig.json, and package.json indicate a build system using Yarn with PnP and TypeScript that compiles the main.ts source into a form utilized by Obsidian.

##### Relationships and Interactions
- The Obsidian Editor acts as the user interface, triggering events that the plugin intercepts.
- When a command is activated, the Command Handler in main.ts is invoked. It then hands off to the Markdown Parsing engine to extract the conversation context (by analyzing nested headings).
- The parsed conversation and any additional system prompt (which can be embedded or loaded from an external markdown file based on frontmatter configuration) are passed to the AI Integration Module.
- The AI Integration Module sends the constructed message payload to the configured AI API (for example, OpenAI-compatible endpoint).
- Once a response is received, control returns to the plugin core, which then appends the response as a new sub-heading in the Markdown note.

##### Important Architectural Patterns/Design Principles
- Modularity: Each concern (command handling, markdown parsing, API communication, configuration management) is separated into its own logical component.
- Extensibility: The plugin supports per-document/model overrides via YAML frontmatter, allowing dynamic configuration.
- User-driven Data Flow: The system is heavily driven by user actions in Obsidian's interface (command invocations) that trigger a series of well-defined interactions.
- Integration with External Services: A clear separation is maintained between the local plugin operations and external AI API services.

##### Relevant Technologies, Frameworks, or Libraries
- TypeScript: The use of main.ts and tsconfig.json indicate that the plugin is written in TypeScript.
- Esbuild: The presence of esbuild.config.mjs suggests that bundling and transpilation is managed via esbuild.
- NodeJS & Yarn: The README mentions Node.js (v16+) and Yarn (with PnP) for dependency management and development.
- Obsidian Plugin API: The integration depends on the Obsidian environment’s plugin infrastructure to register commands and interact with note content.
- OpenAI (or compatible): The project directly configures an API host and key, implying integration with an AI language model API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Obsidian Editor Environment"]:::ui
    B["Plugin Core (main.ts)"]:::core
    C["Command & UI Handlers (main.ts)"]:::core
    D["Markdown Parsing & Conversation Engine (main.ts)"]:::core

    subgraph "Configuration & System Prompt Management"
        F1["Plugin Config (manifest.json)"]:::config
        F2["System Prompt Example (docs/example_system_prompt.md)"]:::config
    end

    E["AI Integration Module (main.ts)"]:::core
    G["AI API Endpoint (OpenAI)"]:::external
    H["Append AI Response to Note (Plugin Core)"]:::ui

    subgraph "Build & Development Infrastructure"
        I["esbuild.config.mjs"]:::build
        J["tsconfig.json"]:::build
        K["package.json"]:::build
        L["version-bump.mjs"]:::build
    end

    A -->|"triggers"| B
    B -->|"registers_commands"| C
    C -->|"invokes_parsing"| D
    D -->|"extracts_config"| F1
    D -->|"extracts_prompt"| F2
    F1 -->|"supplies_data"| E
    F2 -->|"supplies_data"| E
    E -->|"calls_API"| G
    G -->|"returns_response"| E
    E -->|"updates_note"| H
    H -->|"displays_update"| A

    %% Build system connections (not part of runtime flow)
    I --- J
    J --- K
    K --- L

    click B "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/main.ts"
    click C "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/main.ts"
    click D "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/main.ts"
    click E "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/main.ts"
    click F1 "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/manifest.json"
    click F2 "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/docs/example_system_prompt.md"
    click I "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/esbuild.config.mjs"
    click J "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/tsconfig.json"
    click K "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/package.json"
    click L "https://github.com/cpbotha/obsidian-ai-chat-as-md/blob/master/version-bump.mjs"

    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
