# ratiger/obsidian-banyan architecture

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

- Interactive diagram: https://gitdiagram.com/ratiger/obsidian-banyan
- Repository: https://github.com/ratiger/obsidian-banyan

## Overview

##### Project Type and Purpose
- Type: A client‐side Obsidian plugin written in TypeScript + React that enhances note organization and review.
- Purpose: Provides a card-style browsing UI, compound filtering, random review, and heat-map statistics for Obsidian notes, all running within the Obsidian host application.

##### File Structure
Top-Level Directories/Files of Interest
- src/
– main.ts: plugin entry point, registers commands & views with Obsidian API
– BanyanPlugin.ts: core plugin class (implements onload, onunload, event handlers)
– BanyanPluginSettings.ts & BanyanSettingTab.tsx: settings model + settings UI
– components/: reusable React components (ConfirmModal, TagInput, etc.)
– pages/: page-level React components (CardDashboard, sidebar panels, header, etc.)
– store/: state management hooks (useDashBoardStore, useFilterSchemeStore, etc.), likely using Zustand or similar
– models/: data schemas (FileInfo, FilterScheme, ViewScheme, TagFilter, DateRange)
– utils/: file utilities (reading/writing note files), fileWatcher, i18n support
- manifest.json: plugin metadata for Obsidian
- esbuild.config.mjs: build config
- jest.config.js & test/: unit tests for core logic
- docs/: markdown docs and demo assets

##### Extract Architecture Insights from README
- Single-page panel UI injected into Obsidian’s left sidebar
- React + TypeScript for UI
- Persistent state (filter schemes, view schemes, random review settings) saved as JSON/YAML files in plugin’s directory under the vault
- Obsidian API used for file read/write, command registration, and UI mounting

##### Main Components & Interactions
a. Obsidian Host Application
– Provides plugin API: commands, workspace events, vault file system, UI mounting points
b. Plugin Core (BanyanPlugin)
– Lifecycle hooks (onload, onunload)
– Registers commands (open panel, open new note, random review)
– Subscribes to file system events (via fileWatcher)
c. Settings Subsystem
– BanyanPluginSettings model ←→ BanyanSettingTab React UI
– Persists settings in Obsidian’s settings storage
d. State Management Store
– useDashBoardStore, useFilterSchemeStore, useRandomReviewStore, useViewSchemeStore, useSettingsStore
– Central store holds current filters, view schemes, random review configurations
e. UI Layer (React Components & Pages)
– Top-level: CardDashboard.tsx (renders card grid)
– Sidebar panels: FilterSchemeView, RandomReviewView, HeatmapView
– Header: AddNoteView, SearchView
– Reusable: ConfirmModal, TagInput, FolderSuggest
f. Data Models & Utilities
– models/: define types & validation for FileInfo (note metadata), FilterScheme, TagFilter, etc.
– utils/fileUtils.ts: read/write note files, parse frontmatter
– utils/fileWatcher.ts: listen to Vault changes, trigger store updates
– utils/i18n: provide localized strings
g. Local File System (Vault)
– Plugin reads/writes note files under `.obsidian/plugins/banyan/cards` (default directory)
– Persists custom filter/view schemes as JSON in plugin data folder

##### Architectural Patterns & Design Principles
- Modular layering: Core plugin logic, settings, UI components, state store, and utilities all in separate modules.
- Unidirectional data flow: user action → command or event → store update → React re-render.
- Observer pattern: fileWatcher observes Vault changes → notifies store.
- MVC-like:
– Model: `models/` + `store/`
– View: React components under `components/` and `pages/`
– Controller: commands and event handlers in `BanyanPlugin.ts` + `main.ts`

##### Final Checklist
- Clear component labels (e.g., “BanyanPlugin (onload, commands)”)
- Callouts for persistence layers (Obsidian settings vs. plugin data files)
- Related modules (models + utils, UI components + pages, store)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Obsidian Host"
        Host["Obsidian Host"]:::host
    end

    subgraph "Plugin Core"
        Main["main.ts"]:::core
        Plugin["BanyanPlugin.ts"]:::core
    end

    subgraph "Settings Subsystem"
        SettingsModel["BanyanPluginSettings.ts"]:::settings
        SettingsUI["BanyanSettingTab.tsx"]:::settings
    end

    subgraph "State Management Store"
        StoreIndex["index.ts"]:::store
        DashStore["useDashBoardStore.ts"]:::store
        FilterStore["useFilterSchemeStore.ts"]:::store
        RandomStore["useRandomReviewStore.ts"]:::store
        ViewStore["useViewSchemeStore.ts"]:::store
        SettingsStore["useSettingsStore.ts"]:::store
    end

    subgraph "UI Layer - Pages"
        CardDashboard["CardDashboard.tsx"]:::ui
        FilterView["FilterView.tsx"]:::ui
        RandomReview["RandomReviewInfo.tsx"]:::ui
        Heatmap["Heatmap.tsx"]:::ui
        AddNote["AddNoteView.tsx"]:::ui
        SearchView["SearchView.tsx"]:::ui
    end

    subgraph "UI Layer - Components"
        ConfirmModal["ConfirmModal.tsx"]:::ui
        TagInput["TagInput.tsx"]:::ui
        FolderSuggest["FolderSuggest.ts"]:::ui
        Icon["Icon.tsx"]:::ui
    end

    subgraph "Models"
        FileInfo["FileInfo.ts"]:::model
        FilterScheme["FilterScheme.ts"]:::model
        ViewScheme["ViewScheme.ts"]:::model
        TagFilter["TagFilter.ts"]:::model
        DateRange["DateRange.ts"]:::model
        RandomFilters["RandomReviewFilters.ts"]:::model
    end

    subgraph "Utilities"
        FileUtils["fileUtils.ts"]:::util
        FileWatcher["fileWatcher.ts"]:::util
        I18n["i18n/index.ts"]:::util
    end

    Vault["Vault File System"]:::fs

    %% Connections
    Host -->|"plugin load"| Main
    Host -->|"API calls"| Plugin
    Main -->|"instantiates"| Plugin
    Plugin -->|"uses settings model"| SettingsModel
    Plugin -->|"mounts settings UI"| SettingsUI
    Plugin -->|"initializes store"| StoreIndex
    StoreIndex --> DashStore
    StoreIndex --> FilterStore
    StoreIndex --> RandomStore
    StoreIndex --> ViewStore
    StoreIndex --> SettingsStore

    %% Store to UI pages
    DashStore -->|"state"| CardDashboard
    FilterStore -->|"state"| FilterView
    RandomStore -->|"state"| RandomReview
    ViewStore -->|"state"| Heatmap
    SettingsStore -->|"state"| SettingsUI

    %% Settings interactions
    SettingsUI -->|"saves"| SettingsModel
    SettingsModel -->|"persists"| SettingsStore

    %% UI pages to components
    CardDashboard --> ConfirmModal
    CardDashboard --> TagInput
    CardDashboard --> FolderSuggest
    CardDashboard --> Icon
    FilterView --> TagInput
    RandomReview --> Icon
    Heatmap --> Icon
    AddNote --> FileUtils
    SearchView --> TagInput

    %% Utilities and watchers
    FileWatcher -->|"onFileChange"| StoreIndex
    FileWatcher --> Vault
    FileUtils --> Vault
    I18n --> CardDashboard
    I18n --> FilterView
    I18n --> ConfirmModal

    %% User flows
    AddNote -->|"create note"| FileUtils
    FileUtils -->|"writeFile"| Vault
    FilterView -->|"apply filter"| FilterStore
    CardDashboard -->|"render cards"| CardDashboard

    %% Styles
    classDef host fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef settings fill:#d8bfd8,stroke:#333,stroke-width:1px;
    classDef store fill:#98fb98,stroke:#333,stroke-width:1px;
    classDef ui fill:#ffffe0,stroke:#333,stroke-width:1px;
    classDef model fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef util fill:#ffdead,stroke:#333,stroke-width:1px;
    classDef fs fill:#c0c0c0,stroke:#333,stroke-width:1px;

    %% Click Events
    click Main "https://github.com/ratiger/obsidian-banyan/blob/main/src/main.ts"
    click Plugin "https://github.com/ratiger/obsidian-banyan/blob/main/src/BanyanPlugin.ts"
    click SettingsModel "https://github.com/ratiger/obsidian-banyan/blob/main/src/BanyanPluginSettings.ts"
    click SettingsUI "https://github.com/ratiger/obsidian-banyan/blob/main/src/BanyanSettingTab.tsx"
    click StoreIndex "https://github.com/ratiger/obsidian-banyan/blob/main/src/store/index.ts"
    click DashStore "https://github.com/ratiger/obsidian-banyan/blob/main/src/store/useDashBoardStore.ts"
    click FilterStore "https://github.com/ratiger/obsidian-banyan/blob/main/src/store/useFilterSchemeStore.ts"
    click RandomStore "https://github.com/ratiger/obsidian-banyan/blob/main/src/store/useRandomReviewStore.ts"
    click ViewStore "https://github.com/ratiger/obsidian-banyan/blob/main/src/store/useViewSchemeStore.ts"
    click SettingsStore "https://github.com/ratiger/obsidian-banyan/blob/main/src/store/useSettingsStore.ts"
    click CardDashboard "https://github.com/ratiger/obsidian-banyan/blob/main/src/pages/CardDashboard.tsx"
    click FilterView "https://github.com/ratiger/obsidian-banyan/blob/main/src/pages/sidebar/filterScheme/FilterView.tsx"
    click RandomReview "https://github.com/ratiger/obsidian-banyan/blob/main/src/pages/sidebar/randomReview/RandomReviewInfo.tsx"
    click Heatmap "https://github.com/ratiger/obsidian-banyan/blob/main/src/pages/sidebar/heatmap/Heatmap.tsx"
    click AddNote "https://github.com/ratiger/obsidian-banyan/blob/main/src/pages/header/AddNoteView.tsx"
    click SearchView "https://github.com/ratiger/obsidian-banyan/blob/main/src/pages/header/searchbar/SearchView.tsx"
    click ConfirmModal "https://github.com/ratiger/obsidian-banyan/blob/main/src/components/ConfirmModal.tsx"
    click TagInput "https://github.com/ratiger/obsidian-banyan/blob/main/src/components/TagInput.tsx"
    click FolderSuggest "https://github.com/ratiger/obsidian-banyan/blob/main/src/components/FolderSuggest.ts"
    click Icon "https://github.com/ratiger/obsidian-banyan/blob/main/src/components/Icon.tsx"
    click FileInfo "https://github.com/ratiger/obsidian-banyan/blob/main/src/models/FileInfo.ts"
    click FilterScheme "https://github.com/ratiger/obsidian-banyan/blob/main/src/models/FilterScheme.ts"
    click ViewScheme "https://github.com/ratiger/obsidian-banyan/blob/main/src/models/ViewScheme.ts"
    click TagFilter "https://github.com/ratiger/obsidian-banyan/blob/main/src/models/TagFilter.ts"
    click DateRange "https://github.com/ratiger/obsidian-banyan/blob/main/src/models/DateRange.ts"
    click RandomFilters "https://github.com/ratiger/obsidian-banyan/blob/main/src/models/RandomReviewFilters.ts"
    click FileUtils "https://github.com/ratiger/obsidian-banyan/blob/main/src/utils/fileUtils.ts"
    click FileWatcher "https://github.com/ratiger/obsidian-banyan/blob/main/src/utils/fileWatcher.ts"
    click I18n "https://github.com/ratiger/obsidian-banyan/blob/main/src/utils/i18n/index.ts"
```
