# a-f-v/obsidian-arcana architecture

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

- Interactive diagram: https://gitdiagram.com/a-f-v/obsidian-arcana
- Repository: https://github.com/a-f-v/obsidian-arcana

## Overview

This project is an Obsidian plugin called “Arcana” which leverages AI tools to enhance note-taking by providing creative and productivity tools inspired by historical figures. The plugin integrates multiple tool “modules” (Socrates for conversation, Henry Ford for metadata automation, Agatha Christie for content generation, etc.) into Obsidian, enabling advanced features like text-to-speech, flashcard generation, auto-tagging, and custom agent integrations.

##### Main Components
- Plugin Core: Start with the entry point, “src/main.ts”, which initializes and coordinates the overall behavior.
- UI Components: The “src/components” folder includes UI elements such as buttons, modals, dropdowns, and views (e.g., “ObsidianView”, “MarkdownViewer”). These are responsible for the user interface within the Obsidian sidebar or modals.
- Plugin Modules: The “src/plugins” directory is divided into sub-folders corresponding to individual functionalities (e.g., Socrates, Christie, Ford, Feynman, Darwin, Nostradamus, Polo). Each has associated typescript files for the main logic and settings.
- Core Functional Logic: “src/include” holds helper utilities and core logic functions. This includes AI handling interfaces (“src/include/ai”) for conversation, text-to-speech, etc. It encapsulates business logic like file system crawling, cursor movement, and text post-processing.
- Application Hooks & Context: The “src/hooks” folder establishes context and custom hooks that connect state management or service wiring between components.
- Styling & Assets: “src/scss” and asset folders like “imgs” and “gifs” serve as the visual and styling support for the UI.
- Configurations and Metadata: Files such as “manifest.json”, “package.json”, “tsconfig.json”, and various config files at the root represent build configurations, project settings, and plugin metadata needed by Obsidian.

##### Architectural Patterns and Design Principles
- Modularization: Emphasize each plugin module in its folder with a clear separation of concerns. Each feature (e.g., Socrates’s conversational logic, Ford’s metadata handling) is self-contained.
- Layered Architecture: Separate UI components from service logic and external integrations. This layered approach improves maintainability.
- Extensibility: Note that custom chat agents can be added by dropping new files into a specified folder (as detailed in the Socrates section of the README), showcasing flexible extension points.
- Integration via Context & Hooks: The “src/hooks” folder suggests a context-based state management system that ties various parts of the application together.

##### Relevant Technologies, Frameworks, or Libraries
- JavaScript/TypeScript: The project uses TypeScript (as seen with “.ts”, “.tsx” files and tsconfig.json).
- UI Framework: Likely React or a similar library (judging by the use of .tsx files).
- Obsidian Plugin API: The manifest and the organization of “main.ts” support the Obsidian plugin architecture.
- AI Service Integration: Components in “src/include/ai” represent the integration with AI APIs such as OpenAI.
- Build Tools: The presence of “esbuild.config.mjs” indicates the usage of esbuild for bundling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ObsidianHost["Obsidian Host"]:::external
    PluginCore["Plugin Core"]:::logic
    UIComponents["UI Components"]:::ui
    CoreServices["Core Functional Logic & AI Integration"]:::logic
    Hooks["Application Hooks & Context"]:::logic
    StylingAssets["Styling & Assets"]:::asset
    ConfigMetadata["Configurations & Metadata"]:::logic
    ExternalOpenAI["OpenAI API"]:::external
    ExternalWhisper["Whisper API"]:::external

    ObsidianHost -->|"loads"| PluginCore
    PluginCore -->|"initializes"| UIComponents
    PluginCore -->|"loads"| PluginModules["Plugin Modules"]
    PluginCore -->|"uses"| CoreServices
    PluginCore -->|"connects"| Hooks
    PluginCore -->|"styled_by"| StylingAssets
    PluginCore -->|"configured_via"| ConfigMetadata

    subgraph "Plugin Modules"
        Socrates["Socrates Module"]:::logic
        Christie["Christie Module"]:::logic
        Ford["Ford Module"]:::logic
        Feynman["Feynman Module"]:::logic
        Darwin["Darwin Module"]:::logic
        Nostradamus["Nostradamus Module"]:::logic
        Polo["Polo Module"]:::logic
    end

    UIComponents -->|"triggers"| Socrates
    UIComponents -->|"triggers"| Christie
    UIComponents -->|"triggers"| Ford
    UIComponents -->|"triggers"| Feynman
    UIComponents -->|"triggers"| Darwin
    UIComponents -->|"triggers"| Nostradamus
    UIComponents -->|"triggers"| Polo

    Socrates -->|"accesses"| CoreServices
    Christie -->|"accesses"| CoreServices
    Ford -->|"accesses"| CoreServices
    Feynman -->|"accesses"| CoreServices
    Darwin -->|"accesses"| CoreServices
    Nostradamus -->|"accesses"| CoreServices
    Polo -->|"accesses"| CoreServices

    Socrates -->|"updates_state"| Hooks
    Christie -->|"updates_state"| Hooks
    Ford -->|"updates_state"| Hooks
    Feynman -->|"updates_state"| Hooks
    Darwin -->|"updates_state"| Hooks
    Nostradamus -->|"updates_state"| Hooks
    Polo -->|"updates_state"| Hooks

    ExternalOpenAI -->|"provides_data"| CoreServices
    ExternalWhisper -->|"provides_data"| CoreServices

    click PluginCore "https://github.com/a-f-v/obsidian-arcana/blob/master/src/main.ts"
    click UIComponents "https://github.com/a-f-v/obsidian-arcana/tree/master/src/components"
    click Socrates "https://github.com/a-f-v/obsidian-arcana/tree/master/src/plugins/Socrates"
    click Christie "https://github.com/a-f-v/obsidian-arcana/tree/master/src/plugins/Christie"
    click Ford "https://github.com/a-f-v/obsidian-arcana/tree/master/src/plugins/Ford"
    click Feynman "https://github.com/a-f-v/obsidian-arcana/tree/master/src/plugins/Feynman"
    click Darwin "https://github.com/a-f-v/obsidian-arcana/tree/master/src/plugins/Darwin"
    click Nostradamus "https://github.com/a-f-v/obsidian-arcana/tree/master/src/plugins/Nostradamus"
    click Polo "https://github.com/a-f-v/obsidian-arcana/tree/master/src/plugins/Polo"
    click CoreServices "https://github.com/a-f-v/obsidian-arcana/tree/master/src/include"
    click Hooks "https://github.com/a-f-v/obsidian-arcana/tree/master/src/hooks"
    click StylingAssets "https://github.com/a-f-v/obsidian-arcana/tree/master/src/scss"
    click ConfigMetadata "https://github.com/a-f-v/obsidian-arcana/blob/master/manifest.json"

    classDef ui fill:#ccf,stroke:#333,stroke-width:2px;
    classDef logic fill:#fcf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef asset fill:#cff,stroke:#333,stroke-width:2px;
```
